List Balances

GET /api/v1/balances

Overview

Retrieves a list of all balances associated with an account across different chains and currencies.

Authorization

Header: Authorization: Bearer $PAYBYTOKEN_SECRET_KEY

Request Details

Request

curl https://api-prod.paybytoken.io/api/v1/balances \
  -X GET \
  -H "Authorization: Bearer $PAYBYTOKEN_SECRET_KEY"

Request parameters

Parameter	Type	Description
`chain`	string	Filter by exact chain code.
`currency`	string	Filter by exact asset code.
`limit`	integer	Page size from 1 through 100.
`offset`	integer	Number of records to skip before returning the page.

Response Details

Response

The response returns a list of non-zero balance records. Treat each chain-and-currency record independently. The legacy total presentation value is not a cross-asset accounting total.

Attributes

Attribute	Type	Description
`total`	string	Legacy display sum of the page's `total_balance` values. Do not use it as a cross-asset accounting total.
`data`	array of objects	List of balance objects with their details.

Example Response

{
  "total": "12052.6",
  "data": [
    {
      "id": "bal_t24d49WDnBzTTwcA",
      "account_id": "acct_t24daokSqxEmdQGD",
      "chain": "base",
      "currency": "USDC",
      "available_balance": "1052.6",
      "pending_balance": "0.0",
      "reserved_balance": "0.0",
      "total_balance": "1052.6",
      "token": {
        "id": "tok_base_usdc",
        "currency": "USDC",
        "chain": "base",
        "decimals": 6,
        "name": "USD Coin"
      },
      "created_at": "2025-09-04T12:21:26.000Z",
      "updated_at": "2025-09-04T12:21:26.000Z"
    },
    {
      "id": "bal_t24d4cB4kHtJ9Fmn",
      "account_id": "acct_t24daokSqxEmdQGD",
      "chain": "ethereum",
      "currency": "USDC",
      "available_balance": "1000.0",
      "pending_balance": "0.0",
      "reserved_balance": "0.0",
      "total_balance": "1000.0",
      "token": {
        "id": "tok_ethereum_usdc",
        "currency": "USDC",
        "chain": "ethereum",
        "decimals": 6,
        "name": "USD Coin"
      },
      "created_at": "2025-09-04T12:21:26.000Z",
      "updated_at": "2025-09-04T12:21:26.000Z"
    },
    {
      "id": "bal_t24d4eLzZP02J7Dw",
      "account_id": "acct_t24daokSqxEmdQGD",
      "chain": "base",
      "currency": "USDT",
      "available_balance": "5000.0",
      "pending_balance": "0.0",
      "reserved_balance": "0.0",
      "total_balance": "5000.0",
      "token": {
        "id": "tok_base_usdt",
        "currency": "USDT",
        "chain": "base",
        "decimals": 6,
        "name": "Tether USD"
      },
      "created_at": "2025-09-04T12:21:26.000Z",
      "updated_at": "2025-09-04T12:21:26.000Z"
    },
    {
      "id": "bal_t24d4rumAPGwo6R8",
      "account_id": "acct_t24daokSqxEmdQGD",
      "chain": "ethereum",
      "currency": "USDT",
      "available_balance": "5000.0",
      "pending_balance": "0.0",
      "reserved_balance": "0.0",
      "total_balance": "5000.0",
      "token": {
        "id": "tok_ethereum_usdt",
        "currency": "USDT",
        "chain": "ethereum",
        "decimals": 6,
        "name": "Tether USD"
      },
      "created_at": "2025-09-04T12:21:26.000Z",
      "updated_at": "2025-09-04T12:21:26.000Z"
    }
  ]
}