Retrieve token info#

The purpose of this tutorial is to walk through the steps necessary to retrieve information about a token, including its contract details, total supply, status, and identity balances.

Overview#

Once a token contract is registered, its metadata and balances can be queried without submitting a state transition. This tutorial retrieves the token’s contract info, total supply, status, and the token balances held by two identities. Additional details are available in the tokens explanation and the token protocol reference.

Prerequisites#

Code#

token-info.mjs#
import { setupDashClient } from '../setupDashClient.mjs';

const { sdk, keyManager } = await setupDashClient();

// TOKEN_CONTRACT_ID comes from token-register.mjs.
const dataContractId = process.env.TOKEN_CONTRACT_ID;
const tokenPosition = 0;

// Default recipient (testnet). Replace or override via RECIPIENT_ID.
const recipientId =
  process.env.RECIPIENT_ID || '7XcruVSsGQVSgTcmPewaE4tXLutnW1F6PXxwMbo8GYQC';

try {
  if (!dataContractId) {
    throw new Error(
      'Set TOKEN_CONTRACT_ID in .env from token-register.mjs output.',
    );
  }

  const tokenId = await sdk.tokens.calculateId(dataContractId, tokenPosition);
  const contractInfo = await sdk.tokens.contractInfo(tokenId);
  const totalSupply = await sdk.tokens.totalSupply(tokenId);
  const statuses = await sdk.tokens.statuses([tokenId]);
  const identityBalances = await sdk.tokens.identityBalances(
    keyManager.identityId,
    [tokenId],
  );
  const recipientBalances = await sdk.tokens.identityBalances(recipientId, [
    tokenId,
  ]);

  // A token only has a status record once one is published on-chain (e.g. via
  // an emergency pause), so the Map is empty for a freshly registered token.
  const status = statuses.get(tokenId);

  console.log('Token ID:', tokenId);
  console.log('Token contract info:\n', contractInfo?.toJSON());
  console.log(
    'Token status:',
    status ? status.isPaused : '(no status published)',
  );
  console.log('Total token supply:', totalSupply?.totalSupply ?? 0n);
  console.log(`Identity token balance: ${identityBalances.get(tokenId) ?? 0n}`);
  console.log(
    `Recipient token balance: ${recipientBalances.get(tokenId) ?? 0n}`,
  );
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

What’s Happening#

After connecting to the client, we derive the token ID from the contract ID and token position with sdk.tokens.calculateId(). We then query several pieces of information:

  • sdk.tokens.contractInfo() returns the token’s contract metadata.

  • sdk.tokens.totalSupply() returns the number of tokens currently in circulation.

  • sdk.tokens.statuses() returns a Map of token statuses. A status record only exists once one is published on-chain (for example, after an emergency pause), so the Map is empty for a freshly registered token. We fall back to (no status published) in that case.

  • sdk.tokens.identityBalances() returns each identity’s token balance, keyed by token ID.

The recipient defaults to a demo testnet identity so the script can run without extra setup. Set RECIPIENT_ID in the .env file to your own second identity when you want the recipient balance check to reflect an identity you control.

Tip

See this in an example app: DashMint Lab — DashMint token flow reads the signed-in identity’s token balance to display remaining mint capacity.