Pools - IBEx.Fi API Integration Guide

View Flow Diagram

Overview

The Pools 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 pool queries.

The proxy endpoints are:

GET /v1.1/bcreader/:verb : Generic proxy for BCReader GET requests (where :verb is pools or pools/:address)
POST /v1.1/bcreader/:verb : Generic proxy for BCReader POST requests

For pools, you call:

GET /v1.1/bcreader/pools : List active pools for a blockchain - routes to BCReader /api/v1.1/pools
GET /v1.1/bcreader/pools/:address : Get pool balances and yields for a wallet - routes to BCReader /api/v1.1/pools/:address

💡 Pools Overview :

Pools represent liquidity protocols like AAVE where users can deposit tokens to earn yields
Use pools to view available liquidity protocols and their configurations
Query pool balances to see user positions, gains, APR, and APY
Use AAVE_SUPPLY and AAVE_WITHDRAW operations to deposit and withdraw from pools
The IBEx.Fi API acts as a transparent proxy - all parameters are forwarded to BCReader as documented in BCReader Endpoints

1. List Active Pools

Use this endpoint to retrieve the list of active pools (liquidity protocols) available on a specific blockchain. This routes through the generic proxy to BCReader's /api/v1.1/pools endpoint.

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

Headers :

Authorization: Bearer <access_token> (required)
X-Blockchain-Id: <chainId> (required) : Target blockchain ID

Request Example :

GET /v1.1/bcreader/pools
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

[
  {
    "id": 1,
    "blockchainId": "421614",
    "provider": "AAVE",
    "poolAddress": "0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951",
    "addressesProvider": "0x012bAC54348C0E635dCAc9D5FB99f06F24136C9A",
    "metadata": {
      "network": "arbitrum-sepolia",
      "version": "v3"
    },
    "active": true,
    "supplyToken": {
      "address": "0xEURE12345678901234567890123456789012345678",
      "symbol": "EURE",
      "name": "Monerium EUR emoney",
      "decimals": 18
    },
    "borrowToken": {
      "address": "0xEURE12345678901234567890123456789012345678",
      "symbol": "EURE",
      "name": "Monerium EUR emoney",
      "decimals": 18
    },
    "poolToken": {
      "address": "0xaEURE12345678901234567890123456789012345678",
      "symbol": "aEURE",
      "name": "Aave Token EURE",
      "decimals": 18
    }
  }
]

💡 Note : The X-Blockchain-Id header is required to specify which blockchain to query. You can also use the query parameter ?blockchainId=<id> as an alternative.

2. Get Pool Balances for a Wallet

Use this endpoint to retrieve pool balances, yields, and performance metrics for a specific wallet address. This shows how much the user has deposited in each pool and the gains they've earned. This routes through the generic proxy to BCReader's /api/v1.1/pools/:address endpoint.

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

Headers :

Authorization: Bearer <access_token> (required)
X-Blockchain-Id: <chainId> (required) : Target blockchain ID

Query Parameters :

includeZero (boolean, optional, default: false) : Include pools with zero balance

Request Example :

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

Response (200 OK) :

{
  "timestamp": "2025-06-02T13:30:45Z",
  "blockchainId": "421614",
  "address": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "pools": [
    {
      "provider": "AAVE",
      "items": [
        {
          "tokenAddress": "0xEURE12345678901234567890123456789012345678",
          "symbol": "EURE",
          "decimals": 18,
          "baseBalance": "100.0000",
          "currentBalance": "101.2345",
          "gain": "1.2345",
          "gainPct": 0.0123,
          "method": "ATOKEN_INDEX",
          "apr": 0.0456,
          "apy": 0.0467
        }
      ]
    }
  ]
}

💡 Note : The address must be "watched" by BCReader; otherwise, a 404 Not Found error is returned. The response includes performance metrics like APR (Annual Percentage Rate) and APY (Annual Percentage Yield) for each pool position.

3. Deposit to a Pool (AAVE_SUPPLY)

To deposit tokens into a pool (e.g., AAVE), use the AAVE_SUPPLY operation type in a Safe operation.

Endpoint : POST /v1.1/safes/operations

Request Body :

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "chainId": 421614,
  "signerId": "signer_id",
  "operations": [
    {
      "type": "AAVE_SUPPLY",
      "amount": "100.0",
      "assetTicker": "EURE"
    }
  ]
}

Alternative (using tokenAddress) :

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "chainId": 421614,
  "signerId": "signer_id",
  "operations": [
    {
      "type": "AAVE_SUPPLY",
      "amount": "100.0",
      "tokenAddress": "0xEURE12345678901234567890123456789012345678",
      "decimals": 18,
      "referralCode": 12345
    }
  ]
}

💡 Note : The pool address is automatically resolved via BCReader's /config/pools endpoint. You can optionally provide poolAddress to override the automatic resolution. The referralCode parameter (0-65535) is optional and used for AAVE referral programs.

4. Withdraw from a Pool (AAVE_WITHDRAW)

To withdraw tokens from a pool (e.g., AAVE), use the AAVE_WITHDRAW operation type in a Safe operation.

Endpoint : POST /v1.1/safes/operations

Request Body :

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "chainId": 421614,
  "signerId": "signer_id",
  "operations": [
    {
      "type": "AAVE_WITHDRAW",
      "amount": "50.0",
      "assetTicker": "EURE"
    }
  ]
}

Alternative (using tokenAddress) :

{
  "safeAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
  "chainId": 421614,
  "signerId": "signer_id",
  "operations": [
    {
      "type": "AAVE_WITHDRAW",
      "amount": "50.0",
      "tokenAddress": "0xEURE12345678901234567890123456789012345678",
      "decimals": 18
    }
  ]
}

💡 Note : Withdrawals return tokens to the Safe wallet. The pool address is automatically resolved via BCReader's /config/pools endpoint. You can optionally provide poolAddress to override the automatic resolution.

Complete Flow Example

Here's a complete example of the pools flow:

// Step 1: List available pools
const poolsResponse = await fetch('https://api.ibex.fi/v1.1/bcreader/pools', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-Blockchain-Id': '421614'
  }
});

const pools = await poolsResponse.json();
// [{ id: 1, provider: "AAVE", poolAddress: "0x...", ... }]

// Step 2: Check user's pool balances
const balancesResponse = await fetch('https://api.ibex.fi/v1.1/bcreader/pools/0xd676c6188195372EC269E9C2cAf815C56436A679', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-Blockchain-Id': '421614'
  }
});

const balances = await balancesResponse.json();
// { pools: [{ provider: "AAVE", items: [{ symbol: "EURE", currentBalance: "101.2345", gain: "1.2345", apr: 0.0456 }] }] }

// Step 3: Deposit to pool (AAVE_SUPPLY)
const supplyResponse = await fetch('https://api.ibex.fi/v1.1/safes/operations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    safeAddress: '0xd676c6188195372EC269E9C2cAf815C56436A679',
    chainId: 421614,
    signerId: 'signer_id',
    operations: [{
      type: 'AAVE_SUPPLY',
      amount: '100.0',
      assetTicker: 'EURE'
    }]
  })
});

const supplyResult = await supplyResponse.json();
// { credentialRequestOptions: {...}, ... }

// Step 4: Sign and finalize (PUT /v1.1/safes/operations)
// ... (same as other operations)

// Step 5: Withdraw from pool (AAVE_WITHDRAW)
const withdrawResponse = await fetch('https://api.ibex.fi/v1.1/safes/operations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    safeAddress: '0xd676c6188195372EC269E9C2cAf815C56436A679',
    chainId: 421614,
    signerId: 'signer_id',
    operations: [{
      type: 'AAVE_WITHDRAW',
      amount: '50.0',
      assetTicker: 'EURE'
    }]
  })
});

const withdrawResult = await withdrawResponse.json();
// { credentialRequestOptions: {...}, ... }

Error Handling

400 Bad Request : Invalid blockchain ID, missing required fields, or invalid pool address
401 Unauthorized : Invalid or missing JWT token
404 Not Found : Pool not found, address not watched, or no pools available for the specified blockchain
500 Internal Server Error : BCReader API error or network error

⚠️ Important Points :

The X-Blockchain-Id header is required for pool queries
Addresses must be "watched" by BCReader to query pool balances
Pool addresses are automatically resolved from BCReader's configuration
AAVE operations require the pool to be active and configured
Gains, APR, and APY are calculated by BCReader based on pool performance

Technical Deep Dive - For AI Integration

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

Pools - Technical Details

Generic Proxy Pattern

The IBEx.Fi API provides generic proxy endpoints: GET /v1.1/bcreader/:verb and POST /v1.1/bcreader/:verb
For pools, :verb is pools or pools/:address, so you call GET /v1.1/bcreader/pools or GET /v1.1/bcreader/pools/:address
The proxy forwards all query parameters and headers to BCReader without modification
BCReader handles the actual pool queries according to its own API documentation
See BCReader Endpoints for complete BCReader API documentation

GET /v1.1/bcreader/pools

Endpoint: Generic proxy GET /v1.1/bcreader/:verb with verb=pools
Routes to: BCReader GET /api/v1.1/pools
Authentication: JWT required (validated by IBEx.Fi API before proxying)
Blockchain selection: X-Blockchain-Id header or ?blockchainId= query parameter (required, forwarded to BCReader)
Response format: Array of WatchedPool objects (as returned by BCReader)
Pool fields: id, blockchainId, provider, poolAddress, addressesProvider, metadata, active, supplyToken, borrowToken, poolToken
Use case: Discover available liquidity protocols and their configurations

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

Endpoint: Generic proxy GET /v1.1/bcreader/:verb with verb=pools/:address
Routes to: BCReader GET /api/v1.1/pools/:address
Authentication: JWT required (validated by IBEx.Fi API before proxying)
Blockchain selection: X-Blockchain-Id header or ?blockchainId= query parameter (required, forwarded to BCReader)
Query parameters: includeZero (boolean, optional, forwarded to BCReader)
Address requirement: Address must be "watched" by BCReader (returns 404 if not watched)
Response format: Object with timestamp, blockchainId, address, and pools array (as returned by BCReader)
Pool items: tokenAddress, symbol, decimals, baseBalance, currentBalance, gain, gainPct, method, apr, apy
Use case: View user positions, performance metrics, and yields in liquidity pools

AAVE_SUPPLY Operation

Operation type: AAVE_SUPPLY
Purpose: Deposit tokens into an AAVE liquidity pool
Parameters:
- amount (string, required): Amount to deposit (human-readable format)
- assetTicker (string, optional): Token symbol (e.g., "EURE")
- tokenAddress (string, optional): Token contract address (0x...)
- decimals (number, optional): Token decimals (required if using tokenAddress)
- referralCode (number, optional): AAVE referral code (0-65535)
- poolAddress (string, optional): Override automatic pool resolution
Pool resolution: Automatically resolved via BCReader /config/pools for the selected chain
Transaction: Calls AAVE pool's supply() function
Use case: Earn yields by depositing tokens into AAVE pools

AAVE_WITHDRAW Operation

Operation type: AAVE_WITHDRAW
Purpose: Withdraw tokens from an AAVE liquidity pool back to the Safe
Parameters:
- amount (string, required): Amount to withdraw (human-readable format)
- assetTicker (string, optional): Token symbol (e.g., "EURE")
- tokenAddress (string, optional): Token contract address (0x...)
- decimals (number, optional): Token decimals (required if using tokenAddress)
- poolAddress (string, optional): Override automatic pool resolution
Pool resolution: Automatically resolved via BCReader /config/pools for the selected chain
Transaction: Calls AAVE pool's withdraw() function
Use case: Retrieve deposited tokens and earned yields from AAVE pools

Data Model

WatchedPool (from GET /v1.1/bcreader/pools):

{
  "id": number,
  "blockchainId": "string",
  "provider": "string (e.g., 'AAVE')",
  "poolAddress": "string (0x...)",
  "addressesProvider": "string (0x...)",
  "metadata": {
    "network": "string",
    "version": "string"
  },
  "active": boolean,
  "supplyToken": {
    "address": "string (0x...)",
    "symbol": "string",
    "name": "string",
    "decimals": number
  },
  "borrowToken": {
    "address": "string (0x...)",
    "symbol": "string",
    "name": "string",
    "decimals": number
  },
  "poolToken": {
    "address": "string (0x...)",
    "symbol": "string",
    "name": "string",
    "decimals": number
  }
}

Pool Balances (from GET /v1.1/bcreader/pools/:address):

{
  "timestamp": "ISO-8601 timestamp",
  "blockchainId": "string",
  "address": "string (0x...)",
  "pools": [
    {
      "provider": "string",
      "items": [
        {
          "tokenAddress": "string (0x...)",
          "symbol": "string",
          "decimals": number,
          "baseBalance": "string (human-readable)",
          "currentBalance": "string (human-readable)",
          "gain": "string (human-readable)",
          "gainPct": number,
          "method": "string",
          "apr": number,
          "apy": number
        }
      ]
    }
  ]
}

Key Implementation Files

src/routes/v1.2/bcreader.ts : Generic proxy endpoints (GET /v1.1/bcreader/:verb, POST /v1.1/bcreader/:verb)
src/clients/BCReader.ts : BCReader API client (handles actual BCReader communication)
src/routes/v1/safesOperations.ts : AAVE_SUPPLY and AAVE_WITHDRAW operation handlers
docs/BCREADER_ENDPOINTS_v1.1.en.md : Complete BCReader API documentation

Complete Flow - Technical Sequence

List pools : GET /v1.1/bcreader/pools with X-Blockchain-Id header
Generic proxy routing : IBEx.Fi API routes via GET /v1.1/bcreader/:verb where verb=pools
Authenticate : IBEx.Fi API validates JWT token
Forward to BCReader : IBEx.Fi API forwards request to BCReader with blockchain ID
BCReader queries : BCReader queries pool configuration for the specified blockchain
Return pools : IBEx.Fi API returns active pools list to client
Query pool balances : GET /v1.1/bcreader/pools/:address with X-Blockchain-Id header
BCReader validates : BCReader checks if address is watched
BCReader queries : BCReader queries on-chain pool positions and calculates yields
Return balances : IBEx.Fi API returns pool balances with performance metrics
Deposit to pool : POST /v1.1/safes/operations with AAVE_SUPPLY operation
Resolve pool : IBEx.Fi API resolves pool address via BCReader /config/pools
Build transaction : IBEx.Fi API builds AAVE supply() call
Sign and execute : User signs with passkey, transaction is executed via bundler
Withdraw from pool : POST /v1.1/safes/operations with AAVE_WITHDRAW operation
Resolve pool : IBEx.Fi API resolves pool address via BCReader /config/pools
Build transaction : IBEx.Fi API builds AAVE withdraw() call
Sign and execute : User signs with passkey, transaction is executed via bundler

← Back to Main Guide