Wallet Transactions - Integration Guide

This guide explains how to retrieve wallet transactions from one or multiple blockchains using the BCReader API. You can get transactions for a specific blockchain or retrieve multi-blockchain and multi-token transactions in a single request, with optional filtering, pagination, and real-time price data.

📊 View Flow Diagram

Overview

The Transactions 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 transaction queries.

The proxy endpoints are:

For transactions, you call:

💡 Recommendation :

1. Get Single Blockchain Transactions (v1)

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

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

Headers :

Query Parameters :

Request Example :

GET /v1.1/bcreader/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&startDate=2025-01-01&endDate=2025-01-31&limit=20&page=1
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

{
  "total": 125,
  "page": 1,
  "limit": 20,
  "totalPages": 7,
  "data": [
    {
      "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "from": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefab",
      "to": "0xd676c6188195372EC269E9C2cAf815C56436A679",
      "watchedAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
      "direction": "IN",
      "tokenAddress": "0xEURE12345678901234567890123456789012345678",
      "tokenType": "ERC20",
      "valueFormatted": "10.5",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ]
}
💡 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 Transactions (v1.1)

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

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

Headers :

Query Parameters :

Single Blockchain Response

When X-Blockchain-Id header is provided:

Request Example :

GET /v1.1/bcreader/v1.1/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&startDate=2025-01-01&endDate=2025-01-31&includeTokenMeta=true&includePrices=true&limit=20
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

{
  "blockchainId": "421614",
  "total": 125,
  "page": 1,
  "limit": 20,
  "totalPages": 7,
  "data": [
    {
      "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "from": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefab",
      "to": "0xd676c6188195372EC269E9C2cAf815C56436A679",
      "watchedAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
      "direction": "IN",
      "tokenAddress": "0xEURE12345678901234567890123456789012345678",
      "primaryAddress": "0xeure12345678901234567890123456789012345678",
      "secondaryAddress": null,
      "active": true,
      "tokenType": "ERC20",
      "tokenSymbol": "EURE",
      "tokenName": "EURe",
      "tokenDecimals": 18,
      "valueFormatted": "10.5",
      "price_usd": 1.08,
      "price_eur": 0.92,
      "value_usd": "11.34",
      "value_eur": "9.66",
      "price_updated_at": "2025-01-15T10:30:00Z",
      "price_source": "coinbase",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "prices_available": true
}

Multi-Blockchain Response

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

Request Example :

GET /v1.1/bcreader/v1.1/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&startDate=2025-01-01&endDate=2025-01-31&limit=20
Authorization: Bearer <access_token>

Response (200 OK) :

{
  "timestamp": "2025-06-02T13:30:45Z",
  "transactions": {
    "421614": {
      "total": 125,
      "page": 1,
      "limit": 20,
      "totalPages": 7,
      "data": [
        {
          "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "from": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefab",
          "to": "0xd676c6188195372EC269E9C2cAf815C56436A679",
          "watchedAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
          "direction": "IN",
          "tokenAddress": "0xEURE12345678901234567890123456789012345678",
          "primaryAddress": "0xeure12345678901234567890123456789012345678",
          "secondaryAddress": null,
          "active": true,
          "tokenType": "ERC20",
          "valueFormatted": "10.5",
          "timestamp": "2025-01-15T10:30:00.000Z"
        }
      ]
    },
    "100": {
      "total": 80,
      "page": 1,
      "limit": 20,
      "totalPages": 4,
      "data": [
        {
          "transactionHash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd",
          "from": "0xd676c6188195372EC269E9C2cAf815C56436A679",
          "to": "0x1234567890123456789012345678901234567890",
          "watchedAddress": "0xd676c6188195372EC269E9C2cAf815C56436A679",
          "direction": "OUT",
          "tokenAddress": "0xEURE12345678901234567890123456789012345678",
          "primaryAddress": "0xeure12345678901234567890123456789012345678",
          "secondaryAddress": null,
          "active": true,
          "tokenType": "ERC20",
          "valueFormatted": "5.25",
          "timestamp": "2025-01-15T12:00:00.000Z"
        }
      ]
    }
  }
}

Transaction Aggregation

You can aggregate transactions by token using aggregateBy=token:

Request Example :

GET /v1.1/bcreader/v1.1/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&aggregateBy=token&limit=20
Authorization: Bearer <access_token>
X-Blockchain-Id: 421614

Response (200 OK) :

{
  "blockchainId": "421614",
  "total": 125,
  "page": 1,
  "limit": 20,
  "totalPages": 7,
  "data": [ /* ...transactions... */ ],
  "aggregates": {
    "byToken": [
      {
        "tokenAddress": "0xEURE12345678901234567890123456789012345678",
        "symbol": "EURE",
        "count": 80,
        "sumValue": "250.75"
      },
      {
        "tokenAddress": "0xUSDC12345678901234567890123456789012345678",
        "symbol": "USDC",
        "count": 45,
        "sumValue": "130.00"
      }
    ]
  }
}
💾 To Store :

3. Response Fields Explained

Transaction Object Fields

4. Filtering and Options

Filter by Date Range

Filter transactions by date range (inclusive):

GET /v1.1/bcreader/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&startDate=2025-01-01&endDate=2025-01-31
Authorization: Bearer <access_token>

Filter by Direction

Filter by transaction direction:

GET /v1.1/bcreader/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&direction=IN
Authorization: Bearer <access_token>

Filter by Token

Filter by specific token address or symbol (v1.1):

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

Or by symbol:

GET /v1.1/bcreader/v1.1/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&symbol=EURE,USDC
Authorization: Bearer <access_token>

Watched Tokens Only

Keep only transactions for watched tokens (v1.1):

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

Include Token Metadata

Include token symbol, name, and decimals in each transaction (v1.1):

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

Disable Price Data

To disable price data (faster response, v1.1):

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

5. Pagination

Transactions are paginated by default. Use page and limit to navigate through results:

Request Example (Page 1) :

GET /v1.1/bcreader/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&page=1&limit=20
Authorization: Bearer <access_token>

Request Example (Page 2) :

GET /v1.1/bcreader/transactions?address=0xd676c6188195372EC269E9C2cAf815C56436A679&page=2&limit=20
Authorization: Bearer <access_token>
💡 Note : You can also use offset instead of page for pagination. For example, offset=20 is equivalent to page=2 with limit=20.

6. Integration with Sign-In

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

Request Example :

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

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

Response (200 OK) :

{
  "access_token": "...",
  "refresh_token": "...",
  "safeAddress": { ... },
  "transactions": {
    "total": 125,
    "page": 1,
    "limit": 20,
    "totalPages": 7,
    "data": [ /* ...transactions... */ ]
  }
}
💡 Note : This is optional. If includeTransactions is not set or is false, the transactions field will not be included in the response.

7. 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 or date filters are malformed, you will receive a 400 error.

8. 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 queries or v1.1 for multi-blockchain/multi-token
  3. Set filters : Apply date range, direction, token filters as needed
  4. Set blockchain : Use X-Blockchain-Id header for single blockchain, omit for all blockchains
  5. Retrieve transactions : Call the appropriate endpoint with authentication
  6. Handle pagination : Use page and limit to navigate through results
  7. Process response : Extract transaction data, metadata, and aggregates
  8. Optional: Include in sign-in : Set includeTransactions: 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 transactions flow, including architecture patterns, data models, and implementation details.

Transaction Retrieval - Technical Details

Generic Proxy Pattern

GET /v1.1/bcreader/transactions

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

Data Model

Single Blockchain Response:

{
  "blockchainId": "string (chain ID)",
  "total": number,
  "page": number,
  "limit": number,
  "totalPages": number,
  "data": [
    {
      "transactionHash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "watchedAddress": "0x...",
      "direction": "IN | OUT",
      "tokenAddress": "0x...",
      "primaryAddress": "0x...",
      "secondaryAddress": "0x... | null",
      "active": boolean,
      "tokenType": "ERC20 | ERC721 | ERC1155 | NATIVE",
      "tokenSymbol": "string",
      "tokenName": "string",
      "tokenDecimals": number,
      "valueFormatted": "string (human-readable)",
      "price_usd": number,
      "price_eur": number,
      "value_usd": "string",
      "value_eur": "string",
      "price_updated_at": "ISO-8601 timestamp",
      "price_source": "string",
      "timestamp": "ISO-8601 timestamp"
    }
  ],
  "aggregates": {
    "byToken": [
      {
        "tokenAddress": "0x...",
        "symbol": "string",
        "count": number,
        "sumValue": "string"
      }
    ]
  },
  "prices_available": boolean
}

Multi-Blockchain Response:

{
  "timestamp": "ISO-8601 timestamp",
  "transactions": {
    "blockchainId1": {
      "total": number,
      "page": number,
      "limit": number,
      "totalPages": number,
      "data": [...]
    },
    "blockchainId2": {
      "total": number,
      "page": number,
      "limit": number,
      "totalPages": number,
      "data": [...]
    }
  }
}

Filtering Options

Date Filters:

Direction Filter:

Token Type Filter:

Token Filters (v1.1):

Pagination

Pagination Methods:

Response Fields:

Price Integration

Price Data:

Transaction Aggregation

Aggregate by Token:

Integration Points

Sign-In Integration:

WebSocket Integration:

Error Handling

Key Implementation Files

Complete Flow - Technical Sequence

  1. Request transactions : GET /v1.1/bcreader/transactions?address=0x... or GET /v1.1/bcreader/v1.1/transactions?address=0x...
  2. Generic proxy routing : IBEx.Fi API routes via GET /v1.1/bcreader/:verb where verb=transactions
  3. Authenticate : IBEx.Fi API validates JWT token
  4. Resolve address : If address omitted (v1), IBEx.Fi API uses first Safe of authenticated user
  5. Forward to BCReader : IBEx.Fi API forwards all query parameters and headers to BCReader without modification
  6. BCReader processes : BCReader applies filters (date, direction, token) according to its own API
  7. BCReader queries : BCReader queries blockchain(s) for transactions
  8. Price lookup : If includePrices=true, BCReader fetches real-time prices
  9. Aggregate : If aggregateBy=token, BCReader calculates token-level statistics
  10. Format response : BCReader formats response with pagination metadata
  11. Return data : IBEx.Fi API returns BCReader response to client (transparent proxy)
  12. Process response : Client extracts transactions, metadata, and aggregates
  13. Handle pagination : Client uses page and totalPages to navigate
← Back to Main Guide