check_stx_balance
Check the STX token balance for any Stacks blockchain address to verify holdings and monitor account status.
Instructions
Check the STX balance for a Stacks address. Simple and fast balance lookup.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Stacks address to check balance for | |
| token | No | Specific token contract to check (e.g., SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.token-name) |
Implementation Reference
- The 'execute' function that implements the core logic of the 'check_stx_balance' tool. It handles both STX balance checks and optional fungible token balances using StacksApiService.
execute: async (args, context) => { try { await recordTelemetry({ action: "check_stx_balance" }, context); const apiService = new StacksApiService(); const network = (process.env.STACKS_NETWORK as "mainnet" | "testnet" | "devnet") || "mainnet"; if (args.token) { // Check specific token balance const [contractAddress, contractName] = args.token.split('.'); const balance = await apiService.getFungibleTokenBalance(args.token, args.address, network); return `# Token Balance **Address**: ${args.address} **Token**: ${args.token} **Balance**: ${balance} base units ## Token Details - **Contract**: ${args.token} Use \`get_sip010_info\` to get more details about this token contract.`; } else { // Check STX balance const accountInfo = await apiService.getAccountInfo(args.address, network); const stxBalance = parseInt(accountInfo.balance) / 1000000; const lockedSTX = parseInt(accountInfo.locked) / 1000000; const totalSTX = stxBalance + lockedSTX; return `# STX Balance **Address**: ${args.address} **Available STX**: ${stxBalance.toLocaleString()} STX **Locked STX**: ${lockedSTX.toLocaleString()} STX **Total STX**: ${totalSTX.toLocaleString()} STX **Account Nonce**: ${accountInfo.nonce} ${lockedSTX > 0 ? `\n⚠️ **Note**: ${lockedSTX.toLocaleString()} STX is locked (likely in Stacking)` : ''} Use \`get_stacks_account_info\` with \`includeTokens: true\` to see all token balances.`; } } catch (error) { return `❌ Failed to check balance: ${error}`; } }, - Zod schema defining the input parameters for the check_stx_balance tool: required 'address' and optional 'token'.
const BalanceCheckScheme = z.object({ address: z.string().describe("Stacks address to check balance for"), token: z.string().optional().describe("Specific token contract to check (e.g., SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.token-name)"), }); - src/tools/index.ts:73-73 (registration)The line where checkSTXBalanceTool is registered with the MCP server using server.addTool().
server.addTool(checkSTXBalanceTool);