get_sip010_balance
Check SIP-010 token balance for any Stacks address across mainnet, testnet, or devnet networks. Returns balance in base units for accurate display calculations.
Instructions
Get the SIP-010 fungible token balance for a specific address. Returns the balance in base units (consider decimals for display).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | The Stacks address to check balance for | |
| contractAddress | Yes | The contract address | |
| contractName | Yes | The contract name of the SIP-010 token | |
| network | Yes | The Stacks network |
Implementation Reference
- The main handler function for the get_sip010_balance tool. It calls the contract's get-balance function via Hiro API and parses the result.export const getSIP010BalanceTool: Tool<undefined, typeof SIP010BalanceScheme> = { name: "get_sip010_balance", description: "Get the SIP-010 fungible token balance for a specific address. Returns the balance in base units (consider decimals for display).", parameters: SIP010BalanceScheme, execute: async (args, context) => { try { await recordTelemetry({ action: "get_sip010_balance" }, context); const result = await callReadOnlyFunction( args.contractAddress, args.contractName, "get-balance", [`0x${Buffer.from(args.address, 'utf8').toString('hex')}`], args.network ); if (result.okay && result.result) { const balance = parseInt(result.result.replace('u', '')); return `Balance: ${balance} base units\n\nTo get human-readable amount, divide by 10^decimals.\nUse get_sip010_info to get the decimal count.`; } else { return `❌ Failed to get balance: ${result.error || 'Unknown error'}`; } } catch (error) { return `❌ Failed to get SIP-010 balance: ${error}`; } }, };
- Zod schema defining the input parameters for the get_sip010_balance tool.const SIP010BalanceScheme = z.object({ contractAddress: z.string().describe("The contract address"), contractName: z.string().describe("The contract name of the SIP-010 token"), address: z.string().describe("The Stacks address to check balance for"), network: NetworkScheme.describe("The Stacks network"), });
- src/tools/index.ts:48-48 (registration)Registers the getSIP010BalanceTool (named get_sip010_balance) with the FastMCP server.server.addTool(getSIP010BalanceTool);
- Helper function to call read-only contract functions via Hiro Systems API, used by the handler to query get-balance.async function callReadOnlyFunction( contractAddress: string, contractName: string, functionName: string, functionArgs: any[], network: string ): Promise<any> { const apiUrl = network === "mainnet" ? "https://api.hiro.so" : "https://api.testnet.hiro.so"; try { const response = await fetch( `${apiUrl}/v2/contracts/call-read/${contractAddress}/${contractName}/${functionName}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ sender: contractAddress, arguments: functionArgs, }), } ); if (!response.ok) { const data: any = await response.json(); throw new Error(data.error || `HTTP ${response.status}`); } return await response.json(); } catch (error) { throw new Error(`Failed to call ${functionName}: ${error}`); } }