mcpField
T
tokens

tokens

github.com/aibtcdevOther11156 installsUpdated today
Repository

About tokens

A command-line skill for working with SIP-010 fungible tokens on Stacks L2. It supports balance and metadata queries, token-holder listings, and transfers that require an unlocked wallet.

Key features

  1. 01Check token balances
  2. 02Read token metadata
  3. 03List address token holdings
  4. 04View top holders with pagination
  5. 05Transfer tokens with fee options

Use cases

  1. 01Check a wallet’s SIP-010 token balance
  2. 02Inspect token metadata before use
  3. 03Review token holders
  4. 04Send tokens from an unlocked wallet

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/aibtcdev/skills --skill tokens

After installing, type/tokensin Claude Code to confirm it loaded.

Bundled filesAGENT.mdtokens.ts

Details

From the project README

Tokens Skill

Provides SIP-010 fungible token operations on Stacks L2. Transfer operations require an unlocked wallet (use bun run wallet/wallet.ts unlock first). Balance and info queries work without a wallet.

Supports well-known tokens by symbol: sBTC, USDCx, ALEX, DIKO Or use the full contract ID: SP2...address.contract-name

Usage

bun run tokens/tokens.ts <subcommand> [options]

Subcommands

get-balance

Get the balance of any SIP-010 token for a wallet address.

bun run tokens/tokens.ts get-balance --token <symbol-or-id> [--address <addr>]

Options:

  • --token (required) — Token symbol (e.g., USDCx, sBTC) or contract ID
  • --address (optional) — Stacks address to check (uses active wallet if omitted)

Output:

{
  "address": "SP2...",
  "network": "mainnet",
  "token": {
    "contractId": "SP2...address.usdc-token",
    "symbol": "USDCx",
    "name": "USD Coin",
    "decimals": 6
  },
  "balance": {
    "raw": "1000000",
    "formatted": "1 USDCx"
  }
}
transfer

Transfer any SIP-010 token to a recipient address. Requires an unlocked wallet.

bun run tokens/tokens.ts transfer --token <symbol-or-id> --recipient <addr> --amount <amount> [--memo <text>] [--fee low|medium|high|<microStx>]

Options:

  • --token (required) — Token symbol or contract ID
  • --recipient (required) — Stacks address to send to
  • --amount (required) — Amount in smallest unit (depends on token decimals)
  • --memo (optional) — Memo message (max 34 bytes)
  • --fee (optional) — Fee preset (low|medium|high) or micro-STX amount; auto-estimated if omitted

Output:

{
  "success": true,
  "txid": "abc123...",
  "from": "SP2...",
  "recipient": "SP3...",
  "token": "USDCx",
  "amount": "1000000",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}
get-info

Get metadata for a SIP-010 token (name, symbol, decimals, total supply).

bun run tokens/tokens.ts get-info --token <symbol-or-id>

Options:

  • --token (required) — Token symbol or contract ID

Output:

{
  "network": "mainnet",
  "contractId": "SP2...address.usdc-token",
  "name": "USD Coin",
  "symbol": "USDCx",
  "decimals": 6,
  "totalSupply": "1000000000000",
  "tokenUri": "https://..."
}
list-user-tokens

List all fungible tokens owned by an address.

bun run tokens/tokens.ts list-user-tokens [--address <addr>]

Options:

  • --address (optional) — Stacks address to check (uses active wallet if omitted)

Output:

{
  "address": "SP2...",
  "network": "mainnet",
  "tokenCount": 2,
  "tokens": [
    { "contractId": "SP2....usdc-token::usdcx", "balance": "1000000" },
    { "contractId": "SP3....alex-token::alex", "balance": "500000000" }
  ]
}
get-holders

Get the top holders of a SIP-010 token.

bun run tokens/tokens.ts get-holders --token <symbol-or-id> [--limit <n>] [--offset <n>]

Options:

  • --token (required) — Token symbol or contract ID
  • --limit (optional) — Maximum number of holders to return (default: 20)
  • --offset (optional) — Offset for pagination (default: 0)

Output:

{
  "token": "USDCx",
  "network": "mainnet",
  "total": 1234,
  "holders": [
    { "address": "SP2...", "balance": "50000000000" },
    { "address": "SP3...", "balance": "25000000000" }
  ]
}

Notes

  • Token balance and info queries use the public Hiro API (no authentication required)
  • Transfer operations require an unlocked wallet
  • Well-known token symbols: sBTC, USDCx, ALEX, DIKO — or use the full contract ID
  • Token amounts are in the smallest unit — check decimals field to convert to human-readable values

Comments

Markdown supported