> ## Documentation Index > Fetch the complete documentation index at: https://developers.stellar.org/llms.txt > Use this file to discover all available pages before exploring further. # Check balances and metadata > Read balances and token metadata with `stellar token balance`, `name`, `symbol`, and `decimals`, no key required. Check what an account holds and what a token is before touching it. These are reads, so they need no key, no funded account, and no signing. ## Ask your agent ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} What are the decimals and symbol for USDC on Stellar testnet, and what does agent-1 hold of it? ``` The examples use testnet USDC, `USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5`. ## Steps 1. Identify an unfamiliar asset before you touch it: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} stellar token name --id --network stellar token symbol --id --network stellar token decimals --id --network ``` 2. Read a balance: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} stellar token balance --id --account --network ``` 3. Add `--decimal` for a human-readable amount, or leave it off for the raw smallest-unit value you would feed back into `--amount` on a transfer: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} stellar token balance --id --account --network --decimal ``` ## Reading on mainnet The built-in `mainnet` entry ships as a placeholder, so reads fail with `Invalid URL Bring Your Own: ...` until you add a real RPC endpoint: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} stellar network add mainnet \ --rpc-url \ --network-passphrase "Public Global Stellar Network ; September 2015" ``` The public `https://mainnet.sorobanrpc.com` needs no signup and is enough for reads. Stellar's [RPC providers page](https://developers.stellar.org/docs/data/apis/rpc/providers.md) lists others. ## Two output quirks For a Stellar Asset Contract, `name` returns the full `CODE:ISSUER` string, not a friendly name. For the native asset, both `name` and `symbol` return the literal string `native`. These reads return what the contract stores, with no separate metadata registry behind them. ## Raw units versus decimal Without `--decimal`, `balance` returns the token's smallest unit as an integer string. With `--decimal`, it divides by the token's own `decimals` and returns a human-readable number. Use the raw form whenever the value is going back into `--amount` on `transfer` or `approve`. Use `--decimal` only for display. ## A native balance is not the spendable amount `stellar token balance --id native` reports the account's full ledger balance. Stellar holds part of that as the base reserve plus a reserve per subentry, so the spendable figure is lower. Sending the entire reported balance fails at simulation with `Error(Contract, #10)`, `"resulting balance is not within the allowed range"`, confirmed on testnet. That same code also covers an ordinary insufficient balance, so treat it as "this account cannot part with that amount" rather than "this balance is wrong". Leave reserve and fee headroom. ## What these reads cannot do There is no command that lists what an account holds. Every read names one token, so "what does this account hold" is not a question this CLI answers; enumerating an account's trustlines means querying Horizon. Reframe the request as "how much of these specific tokens", and get the token list from the user. `--account` accepts a `G…` address, a `C…` contract address, or a saved alias, so a contract's holdings are readable the same way an account's are. ## Machine-readable output `--output json` wraps each read in an object keyed by the command, for example `{"decimals":7}` or `{"balance":"99999988251"}`. `--output json-formatted` is the same object, pretty-printed. It is not always a single key. `--decimal` adds a second one: `token balance --decimal --output json` returns `{"balance":"9999.9988251","decimals":7}`, and `token allowance --decimal --output json` returns `{"allowance":"0.00001","decimals":7}`. A parser that assumes one key, counts keys, or reaches for the first entry breaks the moment someone adds `--decimal`. ## Common pitfalls A bad token id fails with a `config`-typed error, not a balance of zero: ```console theme={"theme":{"light":"github-light","dark":"github-dark"}} $ stellar token balance --id nonexistent_bad_id --account agent-1 --network testnet --output json {"error":{"type":"config","message":"contract not found: nonexistent_bad_id"}} ``` Check the error type before trusting a balance of zero as real. A balance read against an account that does not exist on the network at all fails differently from one against an existing account with no trustline. The first is `Error(Contract, #6)`, `"account entry is missing"`. The second, for a classic asset, is `Error(Contract, #13)`, `"trustline entry is missing for account"`. Both arrive as `type:"invoke"`, and only the message text tells them apart. ## Related pages * [Send tokens](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/send-tokens.md) * [Delegate spending](https://developers.stellar.org/docs/tools/cli/agent-cli/guides/delegate-spending.md) * [Quickstart](https://developers.stellar.org/docs/tools/cli/agent-cli/quickstart.md) * [Output and errors](https://developers.stellar.org/docs/tools/cli/agent-cli/reference/output-and-errors.md)