BlockChainReader Endpoints

The BlockChainReader endpoints provide access to on-chain data for IBEx wallets. Retrieve balances, transactions, pool yields, lending positions, and swap orders — all scoped to watched addresses and watched tokens configured per tenant.

Note: These endpoints can be called directly via Swagger UI:

GET /v1.2/bcreader/{verb}

POST /v1.2/bcreader/{verb}

Blockchain scope: Most endpoints accept the X-Blockchain-Id header (or ?blockchainId= query param) to scope data to a specific chain. When omitted, data is returned for all configured chains.

Balances
Transactions
Pools
Lending
Swaps
Statistics
Configuration
Price Integration

Balances

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

Multi-token balances for all watched addresses (DB-based).

Parameters:

address (string, optional): Comma-separated list of addresses to filter
includeZero (boolean, optional, default: false): Include zero-balance tokens
includePrices (boolean, optional, default: true): Attach real-time prices
page (number, optional): Page number (pagination enabled when both page and limit present)
limit (number, optional): Items per page (1–100)

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, optional): Chain ID. Scope to one chain; omit for all chains.

Response (200 OK) — single blockchain:

{
  "timestamp": "2025-06-02T13:30:45Z",
  "blockchainId": "421614",
  "balances": {
    "0xabc…": {
      "tokens": [
        {
          "tokenAddress": "0xEURE…",
          "symbol": "EURe",
          "decimals": 18,
          "balance": "123.456",
          "price_usd": 1.08,
          "price_eur": 0.92,
          "value_usd": "133.33",
          "value_eur": "113.58",
          "price_updated_at": "2025-06-02T13:30:00Z",
          "price_source": "coinbase"
        }
      ],
      "pending": []
    }
  },
  "prices_available": true,
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false
  }
}

GET /v1.2/bcreader/v1.1/balances/:address

Multi-token balances for a specific watched address (on-chain RPC call). Address must be in WatchedAddresses (active). Returns 404 if not monitored.

Parameters:

:address (string, required, path): EVM address (0x format)
includeZero (boolean, optional, default: false): Include zero-balance tokens
includePrices (boolean, optional, default: true): Attach real-time prices

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, optional): Chain ID. Scope to one chain; omit for all chains.

Response (200 OK):

{
  "timestamp": "2025-06-02T13:30:45Z",
  "blockchainId": "421614",
  "balance": {
    "tokens": [
      {
        "tokenAddress": "0xEURE…",
        "primaryAddress": "0xEURE…",
        "secondaryAddress": null,
        "active": true,
        "symbol": "EURe",
        "decimals": 18,
        "balance": "123.456",
        "price_usd": 1.08,
        "value_usd": "133.33"
      }
    ],
    "pending": [],
    "summary": {
      "total_value_usd": "233.33",
      "total_value_eur": "198.58"
    }
  },
  "prices_available": true
}

GET /v1.2/bcreader/v1.1/balances/:address/:timestampBegin/:timestampEnd

Balances and evolution within a time window. timestampBegin must be less than timestampEnd (returns 400 otherwise).

Parameters:

:address (string, required, path): Wallet address (0x…)
:timestampBegin (number, required, path): Start timestamp in Unix milliseconds
:timestampEnd (number, required, path): End timestamp in Unix milliseconds
includeZero (boolean, optional): Include zero-balance tokens
includePrices (boolean, optional, default: true): Attach real-time prices

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, required): Chain ID

Response (200 OK):

{
  "timestamp": "2025-12-05T12:00:00Z",
  "blockchainId": "421614",
  "timeWindow": {
    "begin": "2025-12-04T22:57:30.458Z",
    "end": "2025-12-05T22:57:30.458Z"
  },
  "balance": {
    "tokens": [ … ],
    "pending": [],
    "summary": { "total_value_usd": "500.00", "total_value_eur": "425.00" }
  },
  "evolution": [
    {
      "timestamp": "2025-12-05T10:15:00Z",
      "tokenAddress": "0xEURE…",
      "symbol": "EURe",
      "balance": "200.00",
      "change": "+50.00",
      "direction": "IN"
    }
  ],
  "prices_available": true
}

Transactions

GET /v1.2/bcreader/v1.1/transactions

Enhanced transaction listing with multi-token and price support.

Parameters:

address (string, optional): Wallet address
startDate (string, optional): Start date (YYYY-MM-DD, inclusive)
endDate (string, optional): End date (YYYY-MM-DD, inclusive)
direction (string, optional): IN or OUT
tokenType (string, optional): ERC20, ERC721, ERC1155, NATIVE
tokenAddress (string, optional): 0x… or comma-separated list
hash (string, optional): Filter by transaction hash
page (number, optional, default: 1): Page number
limit (number, optional, default: 50): Items per page
includePrices (boolean, optional, default: true): Attach real-time prices

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, optional): Scope to one chain; omit for all

Response (200 OK) — single blockchain:

{
  "blockchainId": "421614",
  "total": 42,
  "page": 1,
  "limit": 50,
  "totalPages": 1,
  "data": [
    {
      "hash": "0x1234…",
      "blockNumber": 12345678,
      "timestamp": "2025-06-01T14:20:00Z",
      "from": "0xaaa…",
      "to": "0xbbb…",
      "value": "100.0",
      "direction": "IN",
      "tokenType": "ERC20",
      "tokenAddress": "0xEURE…",
      "tokenSymbol": "EURe",
      "tokenDecimals": 18,
      "price_usd": 1.08,
      "value_usd": "108.00"
    }
  ],
  "prices_available": true
}

GET /v1.2/bcreader/v1.1/transactions/:hash

Single transaction by hash, with optional price data.

Parameters:

:hash (string, required, path): Transaction hash (0x format)
includePrices (boolean, optional, default: true): Attach real-time prices

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, optional): Scope to one chain

Pools

GET /v1.2/bcreader/v1.1/pools

List watched pools for the selected chain.

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, optional): Chain ID

Response (200 OK):

[
  {
    "id": 1,
    "blockchainId": "421614",
    "provider": "AAVE",
    "poolAddress": "0xpool…",
    "addressesProvider": "0xprovider…",
    "metadata": {},
    "active": true,
    "supplyToken": "0xUSDC…",
    "borrowToken": null,
    "poolToken": "0xaUSDC…"
  }
]

GET /v1.2/bcreader/v1.1/pools/:address

Pool balances and yields for a specific watched address. Address must be watched; otherwise 404 is returned.

Parameters:

:address (string, required, path): Wallet address (must be in WatchedAddresses)
includeZero (boolean, optional, default: false): Include zero-balance items

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, required): Chain ID

Response (200 OK):

{
  "timestamp": "2025-06-02T13:30:45Z",
  "blockchainId": "421614",
  "address": "0xabc…",
  "pools": [
    {
      "provider": "AAVE",
      "items": [
        {
          "tokenAddress": "0xUSDC…",
          "symbol": "USDC",
          "decimals": 6,
          "baseBalance": "1000.00",
          "currentBalance": "1012.50",
          "gain": "12.50",
          "gainPct": "1.25",
          "method": "supply",
          "apr": "5.2",
          "apy": "5.33"
        }
      ]
    }
  ]
}

Lending

GET /v1.2/bcreader/v1.1/lending

List active lending pools.

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, required): Chain ID

Response (200 OK):

[
  {
    "id": 1,
    "blockchainId": "421614",
    "name": "Aave V3",
    "address": "0xlending…",
    "acceptedTokenAddresses": ["0xUSDC…", "0xWBTC…"],
    "active": true
  }
]

GET /v1.2/bcreader/v1.1/lending/:address

Single lending pool by address.

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, required): Chain ID

GET /v1.2/bcreader/v1.1/lending/name/:name

Lending pools filtered by name (case-insensitive).

Headers:

Authorization (Bearer JWT)
X-Blockchain-Id (number, required): Chain ID

Swaps

POST /v1.2/bcreader/v1.1/swap/order/create

Start tracking a CoWSwap or 1INCH swap order.

Body parameters:

safeAddress (string, required): Owner address (must be in WatchedAddresses)
provider (string, required): COWSWAP or 1INCH
blockchainId (string, required): Chain ID (e.g. 100)
uid (string, required for COWSWAP): CoWSwap order UID
txHash (string, required for 1INCH): 1INCH swap transaction hash
sellTokenAddress (string, optional): Sell token address
sellAmount (string, optional): Sell amount (atomic units)
buyTokenAddress (string, optional): Buy token address
buyAmount (string, optional): Buy amount (atomic units)

Response (200 OK):

{
  "message": "Order tracked successfully",
  "order": {
    "uid": "0xorder-uid…",
    "safeAddress": "0xabc…",
    "provider": "COWSWAP",
    "status": "open",
    "blockchainId": "100"
  }
}

GET /v1.2/bcreader/v1.1/swap/order/:id

Fetch a tracked order by UID or txHash. If :id matches 0x + 64 hex chars → search by txHash; otherwise → by UID.

Headers: Authorization (Bearer JWT)

GET /v1.2/bcreader/v1.1/swap/orders/:address

Fetch all swap orders for an address from the provider API.

Parameters:

provider (string, optional, default: COWSWAP): Provider name
blockchainId (string/header, required): Chain ID

Headers: Authorization (Bearer JWT)

Statistics

GET /v1.2/bcreader/statistics/aum

Assets Under Management — net totals per token and per address.

Parameters:

startDate (string, optional): ISO datetime filter
endDate (string, optional): ISO datetime filter

Response (200 OK):

{
  "timestamp": "2025-06-02T13:30:45Z",
  "filters": { "startDate": "2025-01-01", "endDate": "2025-06-30" },
  "total": "12345.67",
  "perToken": [
    { "tokenAddress": "0xEURE…", "tokenSymbol": "EURe", "net": "10000.00" }
  ],
  "perAddress": [
    { "address": "0xabc…", "net": "8000.00" }
  ]
}

GET /v1.2/bcreader/statistics/eure

EURe-specific statistics (IN/OUT totals, counts, averages).

Configuration

Configuration endpoints manage watched addresses, tokens, pools, and lending pools.

GET /v1.2/bcreader/v1.1/config/chains

Returns all supported blockchains.

GET /v1.2/bcreader/v1.1/config/addresses

List all monitored addresses.

POST /v1.2/bcreader/v1.1/config/addresses

Add a new monitored address.

Body: { "address": "0x…", "issuer": "Company B" }

GET /v1.2/bcreader/v1.1/config/tokens

List monitored tokens. With X-Blockchain-Id: flat array. Without: grouped by blockchainId.

GET /v1.2/bcreader/v1.1/config/pools

List monitored pools.

GET /v1.2/bcreader/v1.1/config/lending

List monitored lending pools.

Price Integration

When includePrices=true (default on v1.1 endpoints), each token/transaction includes:

Field	Description
`price_usd`	Token price in USD
`price_eur`	Token price in EUR
`value_usd`	Calculated value in USD (balance × price)
`value_eur`	Calculated value in EUR (balance × price)
`price_updated_at`	Timestamp of last price update
`price_source`	Data source (coinbase, binance, chainlink…)

Response-level flag: prices_available: true|false indicates whether prices were retrieved successfully.

Note: Amounts are returned as strings to preserve decimal precision (no floats). If address is omitted for balance or transaction queries, the backend automatically uses the first Safe address of the authenticated user for the current rpId.

BlockChainReader Endpoints

Table of Contents

Balances

Transactions

Pools

Lending

Swaps

Statistics

Configuration

Price Integration