native_token_balance
Retrieve native token balances for EVM addresses across multiple blockchain networks. Specify chain and wallet address to get current balance with market value, historical data, and token metadata.
Instructions
Lightweight endpoint to just get the native token balance for an EVM address. Required: chainName (blockchain network), walletAddress (wallet address). Optional: quoteCurrency for value conversion, blockHeight for historical balance. Returns native token balance with current market value and token metadata.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chainName | Yes | The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet'). | |
| walletAddress | Yes | The wallet address to get native token balance for. Passing in an ENS, RNS, Lens Handle, or an Unstoppable Domain resolves automatically. | |
| quoteCurrency | No | Currency to quote native token value in (e.g., 'USD', 'EUR'). If not specified, uses default quote currency. | |
| blockHeight | No | Specific block height to get historical native token balance from. |
Implementation Reference
- src/services/BalanceService.ts:432-488 (handler)The native_token_balance tool handler registration and implementation in BalanceService.ts. It uses the Covalent SDK's BalanceService to fetch the balance.
server.tool( "native_token_balance", "Lightweight endpoint to just get the native token balance for an EVM address. " + "Required: chainName (blockchain network), walletAddress (wallet address). " + "Optional: quoteCurrency for value conversion, blockHeight for historical balance. " + "Returns native token balance with current market value and token metadata.", { chainName: z .enum(Object.values(ChainName) as [string, ...string[]]) .describe( "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')." ), walletAddress: z .string() .describe( "The wallet address to get native token balance for. Passing in an ENS, RNS, Lens Handle, or an Unstoppable Domain resolves automatically." ), quoteCurrency: z .enum(Object.values(validQuoteValues) as [string, ...string[]]) .optional() .describe( "Currency to quote native token value in (e.g., 'USD', 'EUR'). If not specified, uses default quote currency." ), blockHeight: z .union([z.string(), z.number()]) .optional() .describe( "Specific block height to get historical native token balance from." ), }, async (params) => { try { const response = await goldRushClient.BalanceService.getNativeTokenBalance( params.chainName as Chain, params.walletAddress, { quoteCurrency: params.quoteCurrency as Quote, blockHeight: params.blockHeight, } ); return { content: [ { type: "text", text: stringifyWithBigInt(response.data), }, ], }; } catch (error) { return { content: [{ type: "text", text: `Error: ${error}` }], isError: true, }; } } );