Balances
How much of each token an account holds.
List address balances
/v1/addresses/{address}/balancesLists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form.
Path Parameters
Query Parameters
Which Tempo network to query. Use the alias mainnet or testnet, or a numeric chain id. Defaults to mainnet when omitted.
stringmainnettestnetnumberstringOnly include verified tokens denominated in this currency (e.g. USD). Case-insensitive. Implies verified=true because the balances snapshot does not store currency for unverified tokens. Unknown currency strings are accepted but match no rows.
stringOpaque keyset cursor from a previous response (nextCursor); pass it back verbatim to fetch the next page. Omit for the first (head) page.
booleanWhen true, include only tokens eligible to pay transaction fees on Tempo: verified tokens that have a Fee AMM pool, plus the default fee token (pathUSD). Use this to avoid a second /fee-amm/pools query when you only want fee-payable holdings.
string[]Comma-separated optional resources to embed, e.g. totalCount.
totalCountinteger·min 5·max 200·default 10How many items to return per page (5–200, default 10).
integer·min 1·max 9007199254740991Page number, 1-indexed (positional pagination for page-numbered access; page=1 is the head page). Mutually exclusive with cursor, and page × limit must be at most 10000 rows — use cursor pagination for deeper traversal. Pages are positional, so rows arriving at the head of a live feed can shift page contents.
Responses
integerHow many requests you may make in the current time window. Not sent on cached responses or 402 payment challenges.
integerHow many requests you have left in the current window before you are rate-limited. Not sent on cached responses or 402 payment challenges.
integerWhen the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or 402 payment challenges.
stringWhich quota this request counted against (e.g. data:read). Not sent on cached responses or 402 payment challenges.
stringA unique id for this request, returned on every response (and as requestId in error bodies). Include it when contacting support so we can find your request.
object[]The balances in this page, ordered from largest to smallest amount.
stringA non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.
stringThe same balance in human-readable decimal form, using the token’s decimals.
stringA stable resource ID for this balance, equal to the token contract address.
booleanWhether this token can be used to pay transaction fees on Tempo: true when the token is verified and has a Fee AMM pool, or is the default fee token (pathUSD). Lets you identify fee-payable holdings without a separate /fee-amm/pools query. Omitted (best-effort) when the fee-token lookup is unavailable.
objectA compact TIP-20 token reference with identity and display fields only.
stringThe TIP-20 token contract address on Tempo.
stringThe currency label for this token, such as USD for USD-denominated stablecoins.
integer·min 0·max 9007199254740991The number of decimal places the token uses; Tempo stablecoins typically use 6.
stringA stable resource ID for this token, equal to its contract address.
stringA URL for the token’s logo image, when one is available.
stringThe short ticker symbol wallets and apps show for this token.
objectPage-level resources you requested with include.
booleanWhether totalCount hit the count cap. When true, totalCount is a lower bound rather than an exact total.
objectWhat went wrong.
stringA short, stable code you can branch on in your code (e.g. token_not_found).
query_invalidparam_invalidbody_invalidaddress_invalidtoken_invalidobject[]A list of specific problems, when the error is about your request (e.g. invalid fields).
objectWhat went wrong.
stringA short, stable code you can branch on in your code (e.g. token_not_found).
api_key_missingapi_key_invalidunauthorizedobject[]A list of specific problems, when the error is about your request (e.g. invalid fields).
stringOn a 402 response, the payment challenge to satisfy. Use it to build the Authorization: Payment credential and retry the request.
integerHow many requests you may make in the current time window. Not sent on cached responses or 402 payment challenges.
integerHow many requests you have left in the current window before you are rate-limited. Not sent on cached responses or 402 payment challenges.
integerWhen the current window resets, as a Unix timestamp in seconds. Not sent on cached responses or 402 payment challenges.
stringWhich quota this request counted against (e.g. data:read). Not sent on cached responses or 402 payment challenges.
stringA unique id for this request, returned on every response (and as requestId in error bodies). Include it when contacting support so we can find your request.
integerHow many seconds to wait before trying again. Sent with 429 (rate-limited) responses.
objectWhat went wrong.
stringA short, stable code you can branch on in your code (e.g. token_not_found).
rate_limit_exceededpayment_requiredobject[]A list of specific problems, when the error is about your request (e.g. invalid fields).
objectWhat went wrong.
stringA short, stable code you can branch on in your code (e.g. token_not_found).
internal_errorobject[]A list of specific problems, when the error is about your request (e.g. invalid fields).
objectWhat went wrong.
stringA short, stable code you can branch on in your code (e.g. token_not_found).
upstream_errorobject[]A list of specific problems, when the error is about your request (e.g. invalid fields).
Was this helpful?