Wallet Balances - Integration Guide

This guide explains how to retrieve wallet balances from one or multiple blockchains using the BCReader API. You can get balances for a specific blockchain or retrieve multi-blockchain and multi-token balances in a single request.

📊 View Flow Diagram

Overview

The Balances API uses a generic proxy pattern to route requests to BCReader. The IBEx.Fi API provides a transparent proxy endpoint that forwards requests to the BCReader API, which handles the actual balance queries.

The proxy endpoints are:

For balances, you call:

💡 Recommendation :

1. Get Single Blockchain Balance (v1)

Use this endpoint to retrieve the balance for a wallet address on a specific blockchain. This routes through the generic proxy to BCReader's /api/balances endpoint.

Endpoint : GET /v1.1/bcreader/balances (via generic proxy GET /v1.1/bcreader/:verb)

Headers :

Query Parameters :

Request Example :

GET /v1.1/bcreader/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

{
  "timestamp": "2025-06-02T13:30:45Z",
  "balance": {
    "address": "0xd676c6188195372EC269E9C2cAf815C56436A679",
    "balance": "25.000"
  }
}
💡 Note : If address is omitted, the API automatically uses the first Safe address of the authenticated user for the current rpId.

2. Get Multi-Blockchain and Multi-Token Balances (v1.1)

Use this endpoint to retrieve detailed token balances across one or multiple blockchains, with optional price data. This routes through the generic proxy to BCReader's /api/v1.1/balances endpoint.

Endpoint : GET /v1.1/bcreader/v1.1/balances or GET /v1.1/bcreader/balances (via generic proxy)

Headers :

Query Parameters :

Single Blockchain Response

When X-Blockchain-Id header is provided:

Request Example :

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

{
  "timestamp": "2025-06-02T13:30:45Z",
  "blockchainId": "421614",
  "balance": {
    "tokens": [
      {
        "tokenAddress": "0xEURE12345678901234567890123456789012345678",
        "primaryAddress": "0xEURE12345678901234567890123456789012345678",
        "secondaryAddress": null,
        "active": true,
        "symbol": "EURE",
        "decimals": 18,
        "balance": "25.000",
        "status": "MATCH",
        "source": "DB",
        "price_usd": 1.08,
        "price_eur": 0.92,
        "value_usd": "27.00",
        "value_eur": "23.00",
        "price_updated_at": "2025-06-02T13:30:00Z",
        "price_source": "coinbase"
      }
    ],
    "summary": {
      "mismatches": 0,
      "total": 1,
      "total_value_usd": "27.00",
      "total_value_eur": "23.00"
    }
  },
  "prices_available": true
}

Multi-Blockchain Response

When X-Blockchain-Id header is omitted, returns balances for all configured blockchains:

Request Example :

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "timestamp": "2025-06-02T13:30:45Z",
  "balances": {
    "421614": {
      "balance": {
        "tokens": [
          {
            "tokenAddress": "0xEURE12345678901234567890123456789012345678",
            "primaryAddress": "0xEURE12345678901234567890123456789012345678",
            "secondaryAddress": null,
            "active": true,
            "symbol": "EURE",
            "decimals": 18,
            "balance": "25.000",
            "status": "MATCH",
            "source": "DB"
          }
        ],
        "summary": {
          "total": 1
        }
      }
    },
    "100": {
      "balance": {
        "tokens": [
          {
            "tokenAddress": "0xEURE12345678901234567890123456789012345678",
            "primaryAddress": "0xEURE12345678901234567890123456789012345678",
            "secondaryAddress": null,
            "active": true,
            "symbol": "EURE",
            "decimals": 18,
            "balance": "50.25",
            "status": "MATCH",
            "source": "DB"
          }
        ],
        "summary": {
          "total": 1
        }
      }
    }
  }
}
💾 To Store :

3. Response Fields Explained

Token Object Fields

Summary Object Fields

4. Filtering and Options

Filter by Token

You can filter balances by specific token address or symbol:

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679&tokenAddress=0xEURE12345678901234567890123456789012345678
Authorization: Bearer <access_token>

Include Native Token

To include the native blockchain token (ETH, etc.):

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679&includeNative=true
Authorization: Bearer <access_token>

Include Zero Balances

To include tokens with zero balance:

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679&includeZero=true
Authorization: Bearer <access_token>

Disable Price Data

To disable price data (faster response):

GET /v1.1/bcreader/v1.1/balances?address=0xd676c6188195372EC269E9C2cAf815C56436A679&includePrices=false
Authorization: Bearer <access_token>

5. Integration with Sign-In

You can optionally include balance data in the sign-in response by setting includeBalance: true in the sign-in request body:

Request Example :

POST /v1.2/auth/sign-in
Content-Type: application/json

{
  "credential": { ... },
  "includeBalance": true
}

Response (200 OK) :

{
  "access_token": "...",
  "refresh_token": "...",
  "safeAddress": { ... },
  "balance": {
    "timestamp": "2025-06-02T13:30:45Z",
    "balance": {
      "address": "0xd676c6188195372EC269E9C2cAf815C56436A679",
      "balance": "25.000"
    }
  }
}
💡 Note : This is optional. If includeBalance is not set or is false, the balance field will not be included in the response.

6. Error Handling

401 Unauthorized

If the JWT is missing or invalid, you will receive a 401 error. Make sure to include a valid Authorization header.

404 Not Found

If the wallet address is not found or the user has no Safe addresses, you will receive a 404 error.

400 Bad Request

If the address format is invalid, you will receive a 400 error.

7. Complete Flow Summary

  1. Get wallet address : Use the authenticated user's Safe address or provide it explicitly
  2. Choose endpoint : Use v1 for simple balance or v1.1 for multi-blockchain/multi-token
  3. Set blockchain : Use X-Blockchain-Id header for single blockchain, omit for all blockchains
  4. Retrieve balances : Call the appropriate endpoint with authentication
  5. Process response : Extract token balances, values, and summary data
  6. Optional: Include in sign-in : Set includeBalance: true in sign-in requests
⚠️ Important Points :

Technical Deep Dive - For AI Integration

This section provides detailed technical information for AI systems integrating the IBEX wallet balances flow, including architecture patterns, data models, and implementation details.

Balance Retrieval - Technical Details

Generic Proxy Pattern

GET /v1.1/bcreader/balances

GET /v1.1/bcreader/v1.1/balances

Data Model

Single Blockchain Response:

{
  "timestamp": "ISO-8601 timestamp",
  "blockchainId": "string (chain ID)",
  "balance": {
    "tokens": [
      {
        "tokenAddress": "0x...",
        "primaryAddress": "0x...",
        "secondaryAddress": "0x... | null",
        "active": boolean,
        "symbol": "string",
        "decimals": number,
        "balance": "string (human-readable)",
        "status": "MATCH | MISMATCH",
        "source": "DB | RPC",
        "price_usd": number,
        "price_eur": number,
        "value_usd": "string",
        "value_eur": "string",
        "price_updated_at": "ISO-8601 timestamp",
        "price_source": "string"
      }
    ],
    "summary": {
      "total": number,
      "mismatches": number,
      "total_value_usd": "string",
      "total_value_eur": "string"
    }
  },
  "prices_available": boolean
}

Multi-Blockchain Response:

{
  "timestamp": "ISO-8601 timestamp",
  "balances": {
    "blockchainId1": {
      "balance": {
        "tokens": [...],
        "summary": {...}
      }
    },
    "blockchainId2": {
      "balance": {
        "tokens": [...],
        "summary": {...}
      }
    }
  }
}

Price Integration

Price Data:

Token Status and Source

Status Values:

Source Values:

Integration Points

Sign-In Integration:

WebSocket Integration:

Error Handling

Key Implementation Files

Complete Flow - Technical Sequence

  1. Request balance : GET /v1.1/bcreader/balances?address=0x... or GET /v1.1/bcreader/v1.1/balances?address=0x...
  2. Authenticate : API validates JWT token
  3. Resolve address : If address omitted (v1), uses first Safe of authenticated user
  4. Proxy to BCReader : API forwards request to BCReader upstream
  5. BCReader queries : BCReader queries blockchain(s) for token balances
  6. Price lookup : If includePrices=true, BCReader fetches real-time prices
  7. Format response : BCReader formats response with token metadata
  8. Return data : API returns balance data to client
  9. Process response : Client extracts tokens, values, and summary
← Back to Main Guide