Understanding how your token moves through Spark is foundational to operating as an issuer. You might need to know who holds it, when it was minted, burned, or frozen, and how it’s being transferred across Spark. We’re developing multiple ways for issuers to observe and understand token behavior. A Spark Explorer is in the works to provide a more intuitive, visual experience, but we’ve also exposed these insights at the SDK level to offer greater precision and flexibility for power users. As a starting point, the SDK surfaces two core functions — queryTokenTransactions() and getIssuerTokenDistribution() — which let issuers query the full history and current state of any token they control.

​
Retrieve Token Transaction History

Use queryTokenTransactions() to retrieve a detailed, filterable history of your token’s activity. The function now uses an object-based parameter structure for more flexible filtering. By combining the optional parameters you can slice the data any way you need—for example, “all outgoing transfers from this wallet” or “all transactions related to my issuer key”.

​
Parameters

ParameterTypeDescription
ownerPublicKeysstring[](Optional) Only include transactions that involve any of the provided owner public keys.
issuerPublicKeysstring[](Optional) Only include transactions created by any of the provided issuer public keys.
tokenTransactionHashesstring[](Optional) Restrict results to the specified transaction hashes.
tokenIdentifiersstring[](Optional) Filter by one or more Bech32m token identifiers (btkn1…).
outputIdsstring[](Optional) Only include transactions that reference the given output IDs.

​
Return Value

The function resolves to an array of TokenTransactionWithStatus objects:
  • tokenTransaction — The underlying TokenTransaction record
  • status — The current lifecycle stage of the transaction
  • confirmationMetadata — Additional chain-confirmation details once the transaction is finalized
Status values:
StatusMeaning
TOKEN_TRANSACTION_STARTEDTransaction created but not yet signed
TOKEN_TRANSACTION_SIGNEDTransaction signed by all required parties
TOKEN_TRANSACTION_REVEALEDTransaction revealed on-chain, awaiting finalization
TOKEN_TRANSACTION_FINALIZEDTransaction confirmed and finalized
TOKEN_TRANSACTION_STARTED_CANCELLEDTransaction cancelled before signing
TOKEN_TRANSACTION_SIGNED_CANCELLEDTransaction cancelled after signing
TOKEN_TRANSACTION_UNKNOWNUnknown or unexpected state
const transactions = await wallet.queryTokenTransactions({
  ownerPublicKeys: ["<ownerPublicKey>"],
  issuerPublicKeys: ["<issuerPublicKey>"],
  tokenIdentifiers: ["btkn1qwertyuiopasdfghjklzxcvbnm1234567890abcdef"],
});

console.log("Token transactions:", transactions);

​
Explore Your Token Analytics

This feature is currently under development and will be available in an upcoming Spark release.
Use getIssuerTokenDistribution() to get a snapshot of how your token is distributed. This includes metrics like how many wallets hold it, how much is in circulation, and how much has been burned. This is helpful when you want to monitor supply metrics, assess adoption, or build custom analytics on top of your issuance logic. It will return:
  • totalCirculatingSupply: Total circulating supply of the token
  • totalIssued: Total number of tokens ever minted
  • totalBurned: Cumulative tokens burned
  • numHoldingAddress: Unique token holders
  • numConfirmedTransactions: Confirmed transactions involving this token
const distribution = await wallet.getIssuerTokenDistribution();

console.log("Token distribution:" + distribution);