> ## Documentation Index > Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get token balances > Get token balances and transfer history for an earn account. Returns on-chain token balances for all tokens the earn account has interacted with, along with the complete transfer history for each token. Balances are keyed by token symbol for easy access. Use this endpoint to display account balances, track token movements, or build transaction history interfaces. ## OpenAPI ````yaml /v2/combined_spec.json get /v2/earn/balances openapi: 3.1.0 info: title: Compass API description: Compass Labs DeFi API version: 0.0.1 servers: - url: https://api.compasslabs.ai description: Production server security: - ApiKeyAuth: [] paths: /v2/earn/balances: get: tags: - Earn summary: Get token balances description: >- Get token balances and transfer history for an earn account. Returns on-chain token balances for all tokens the earn account has interacted with, along with the complete transfer history for each token. Balances are keyed by token symbol for easy access. Use this endpoint to display account balances, track token movements, or build transaction history interfaces. operationId: v2_earn_balances parameters: - name: chain in: query required: true schema: type: string enum: - arbitrum - base - bsc - ethereum - tempo title: Chain default: base - name: owner in: query required: true schema: type: string title: Owner default: '0x06A9aF046187895AcFc7258450B15397CAc67400' description: The address of the owner of the earn account. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EarnBalancesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: python label: Python (SDK) source: |- from compass_api_sdk import CompassAPI, models with CompassAPI( api_key_auth="", ) as compass_api: res = compass_api.earn.earn_balances(chain=models.V2EarnBalancesChain.BASE, owner="0x06A9aF046187895AcFc7258450B15397CAc67400") # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { CompassApiSDK } from "@compass-labs/api-sdk"; const compassApiSDK = new CompassApiSDK({ apiKeyAuth: "", }); async function run() { const result = await compassApiSDK.earn.earnBalances({ chain: "base", owner: "0x06A9aF046187895AcFc7258450B15397CAc67400", }); console.log(result); } run(); components: schemas: EarnBalancesResponse: properties: earn_account_address: type: string title: Earn Account Address description: The derived earn account address. examples: - '0xA4Dc919c61fDAA100AC9aB8Fae4A2d725165C181' balances: additionalProperties: $ref: >- #/components/schemas/compass__api_backend__v2__models__balances__TokenBalance type: object title: Balances description: Token balances keyed by token symbol. example: USDC: balance: '70710737' balance_formatted: '70.710737' token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' token_decimals: 6 token_symbol: USDC transfers: - amount: '70710737' amount_formatted: '70.710737' block_number: 43830869 block_timestamp: '2026-03-25T15:04:45Z' direction: in from_address: '0x111111125421cA6dc452d289314280a0f8842A65' to_address: '0xA4Dc919c61fDAA100AC9aB8Fae4A2d725165C181' transaction_hash: >- 0x949969bf49c100beca5d05bebbc99a57608a6d1f7472c621f3b00a5987bb417a usd_value: '70.77' WETH: balance: '876484654169830' balance_formatted: '0.000876' token_address: '0x4200000000000000000000000000000000000006' token_decimals: 18 token_symbol: WETH transfers: - amount: '876484654169830' amount_formatted: '0.000876' block_number: 43482380 block_timestamp: '2026-03-17T13:28:27Z' direction: in from_address: '0xd4a0e0b9149bcee3c920d2e00b5de09138fd8bb7' to_address: '0xA4Dc919c61fDAA100AC9aB8Fae4A2d725165C181' transaction_hash: >- 0x4165f6f2185375050f39413833e7a77f33c9c4afd429acec0d867315d96b2ea4 usd_value: '1.80' total_usd_value: anyOf: - type: string - type: 'null' title: Total Usd Value description: Total USD value of all balances (sum of available values). example: '72.57' type: object required: - earn_account_address title: EarnBalancesResponse description: Response containing earn account balances and transfer history. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError compass__api_backend__v2__models__balances__TokenBalance: properties: token_address: type: string title: Token Address description: The token contract address. examples: - '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' token_symbol: type: string title: Token Symbol description: The token symbol (e.g., 'USDC'). examples: - USDC token_decimals: type: integer title: Token Decimals description: The token's decimal places. examples: - 6 balance: type: string title: Balance description: The current on-chain balance (raw). examples: - '70710737' balance_formatted: type: string title: Balance Formatted description: The human-readable balance. examples: - '70.710737' usd_value: anyOf: - type: string - type: 'null' title: Usd Value description: Balance value in USD (null if price unavailable). examples: - '70.77' transfers: items: $ref: '#/components/schemas/TokenTransfer' type: array title: Transfers description: List of all transfers involving this token. type: object required: - token_address - token_symbol - token_decimals - balance - balance_formatted title: TokenBalance description: Balance and transfer history for a single token. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TokenTransfer: properties: from_address: type: string title: From Address description: The address tokens were sent from. examples: - '0x111111125421cA6dc452d289314280a0f8842A65' to_address: type: string title: To Address description: The address tokens were sent to. examples: - '0xA4Dc919c61fDAA100AC9aB8Fae4A2d725165C181' amount: type: string title: Amount description: The raw transfer amount (in token's smallest unit). examples: - '70710737' amount_formatted: type: string title: Amount Formatted description: The human-readable transfer amount. examples: - '70.710737' block_number: type: integer title: Block Number description: The block number of the transfer. examples: - 43830869 block_timestamp: type: string format: date-time title: Block Timestamp description: The timestamp of the transfer. examples: - '2026-03-25T15:04:45Z' transaction_hash: type: string title: Transaction Hash description: The transaction hash of the transfer. examples: - '0x949969bf49c100beca5d05bebbc99a57608a6d1f7472c621f3b00a5987bb417a' direction: type: string enum: - in - out title: Direction description: >- Direction relative to the product account: 'in' for received, 'out' for sent. examples: - in type: object required: - from_address - to_address - amount - amount_formatted - block_number - block_timestamp - transaction_hash - direction title: TokenTransfer description: A single ERC20 token transfer event. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Compass API Key. Get your key [here](https://www.compasslabs.ai/dashboard). ````