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
decimalsfield to convert to human-readable values