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 — getIssuerTokenActivity() and getIssuerTokenDistribution() — which let issuers query the full history and current state of any token they control.

​
Explore Your Token Activity

Use getIssuerTokenActivity() to fetch the full audit trail of events related to your token. This is useful when you want to answer questions like: When did this token get minted? Who transferred it? Has it been frozen or burned recently?

This call returns a paginated list of operations such as:

  • ISSUER_ANNOUNCE – Marks the creation of a token on Bitcoin L1. This event includes the token’s name, ticker, supply cap, and other metadata.
  • ISSUER_MINT – Logs the issuance of new tokens by the issuer. These tokens are added to the circulating supply.
  • USER_TRANSFER – Represents a token transfer between users on Spark. Captures typical usage and movement of tokens.
  • ISSUER_BURN – Tokens permanently removed from circulation by the issuer. Often used to reduce total supply.
  • ISSUER_FREEZE - The issuer has frozen a specific address, preventing it from transferring tokens.
  • ISSUER_UNFREEZE — Lifts a freeze on an address, restoring its ability to transfer tokens.

​
Parameters

The call takes in the following metadata:

ParameterTypeDescription
pageSizenumber(Optional, default: 100) Number of transactions per page
cursorListAllTokenTransactionsCursor(Optional) Cursor for paginating through results
operationTypesOperationType[](Optional) Filter by specific operation types (ISSUER_ANNOUNCE, ISSUER_MINT, etc.)
beforeTimestampDate(Optional) Only include events that occurred before this timestamp
afterTimestampDate(Optional) Only include events that occurred after this timestamp

Tip: Combine operationTypes with date filters to create precise queries — like “all mints in Q1” or “burns after a freeze.”

const activity = await wallet.getIssuerTokenActivity();

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

​
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);