---
updatedAt: 2026-06-17T07:20:34.000Z
agentTools:
  projectIndex: https://readme.cipherowl.ai/llms.txt
---

# Batch get balances

Retrieves balance information for up to 100 addresses on the same blockchain in a single efficient request. Partial failures are supported - if some addresses fail, successful results are still returned with error details for failed addresses.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "API ENDPOINTS",
    "description": "CipherOwl blockchain compliance and risk assessment APIs.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://svc.cipherowl.ai"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Onchain Service",
      "description": "Query balances and transaction detail on a specific network. Balances and transactions live on one network, so these endpoints take a network (`/networks/{network}/…`, e.g. `ethereum_mainnet`), not a chain family such as `evm`."
    }
  ],
  "paths": {
    "/api/onchain/v1/networks/{network}/balances:batchget": {
      "post": {
        "summary": "Batch get balances",
        "description": "Retrieves balance information for up to 100 addresses on the same blockchain in a single efficient request. Partial failures are supported - if some addresses fail, successful results are still returned with error details for failed addresses.",
        "operationId": "OnChainService_BatchGetBalance",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/v1BatchGetBalanceResponse"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "network",
            "description": "Network key, for example bitcoin_mainnet. All addresses must be on this network.",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bitcoin_mainnet"
            }
          }
        ],
        "tags": [
          "Onchain Service"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OnChainServiceBatchGetBalanceBody"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 access token obtained from /oauth/token using client credentials."
      }
    },
    "schemas": {
      "OnChainServiceBatchGetBalanceBody": {
        "type": "object",
        "properties": {
          "addresses": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "title": "List of blockchain addresses to query (1-100 addresses)"
          },
          "network": {
            "type": "string",
            "description": "Network key, for example bitcoin_mainnet. All addresses must be on this network."
          }
        },
        "description": "Batch request for efficient multi-address queries on a single blockchain.\nAll addresses must be on the same network.\n\n**Performance:**\n- Single API call for up to 100 addresses\n- Faster than individual requests\n- Partial failures are handled gracefully",
        "title": "Request for retrieving balances of multiple addresses"
      },
      "v1Balance": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "title": "Blockchain address that was queried"
          },
          "balance": {
            "type": "string",
            "title": "Native balance in smallest unit (satoshi, wei, lamport, drop) as string"
          },
          "unit": {
            "type": "string",
            "title": "Unit name of the native balance (e.g., \"satoshi\", \"wei\", \"lamport\", \"drop\")"
          },
          "tokens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1TokenBalance"
            },
            "title": "List of token balances held by this address (empty for non-token chains)"
          },
          "error": {
            "type": "string",
            "title": "Error message if the address query failed (empty string on success)"
          }
        },
        "description": "Contains the native currency balance and any token holdings.\nAmounts are returned as strings in the smallest unit to preserve precision.\n\n**Native Balance Units:**\n- Bitcoin: satoshi (1 BTC = 100,000,000 satoshi)\n- Ethereum/Ethereum Classic: wei (1 ETH = 1,000,000,000,000,000,000 wei)\n- Solana: lamport (1 SOL = 1,000,000,000 lamport)\n- XRP: drop (1 XRP = 1,000,000 drops)\n\n**Error Handling:**\nIf an error occurs (invalid address, network issue, etc.), the error field will contain details\nand the balance/tokens fields may be empty or partial.",
        "title": "Balance information for a blockchain address"
      },
      "v1BatchGetBalanceResponse": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "description": "Deprecated. Same value as `network`; it will be removed in a future version."
          },
          "balances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v1Balance"
            },
            "title": "Balance information for each queried address (same order as request)"
          },
          "network": {
            "type": "string",
            "title": "Network key of the request"
          }
        },
        "description": "Returns balance data for all requested addresses.\nIf individual addresses fail, their error field will contain details while other addresses return successfully.",
        "title": "Response containing balance information for multiple addresses"
      },
      "v1TokenBalance": {
        "type": "object",
        "properties": {
          "contract": {
            "type": "string",
            "title": "Token contract address or identifier (e.g., 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 for USDC on Ethereum)"
          },
          "name": {
            "type": "string",
            "title": "Human-readable token name (e.g., \"USD Coin\", \"Wrapped Bitcoin\")"
          },
          "symbol": {
            "type": "string",
            "title": "Token symbol (e.g., \"USDC\", \"USDT\", \"WBTC\")"
          },
          "balance": {
            "type": "string",
            "title": "Token balance in smallest unit as string (to preserve precision for large numbers)"
          },
          "decimals": {
            "type": "integer",
            "format": "int32",
            "title": "Number of decimal places for the token (typically 6-18)"
          },
          "type": {
            "type": "string",
            "title": "Token standard (e.g., \"ERC-20\", \"SPL\", \"XRC-20\")"
          }
        },
        "description": "Represents a single token holding (ERC-20, SPL, XRC-20, etc.) with full metadata.\nBalance amounts are returned as strings to preserve precision for large numbers.\n\n**Decimal Conversion Example:**\nIf balance=\"1000000\" and decimals=6, the human-readable amount is 1.0 tokens",
        "title": "Information about a token balance held by an address"
      }
    }
  }
}
```