Address transfer monitoring — Quick start

Quick start

This section helps you complete a basic integration in about 10 minutes, including real-time notifications and historical queries for monitored addresses.

Prerequisites

Before starting, prepare the following credential:

Credential	Purpose	Example
API key	API authentication, caller identification, and billing statistics.	sk-xxx

Store the service base URL. All examples below use BASE_URL.

BASE_URL=https://api.gelabs.org
API_KEY=your-api-key

---

Step 1: Add monitored addresses

Add wallet addresses that you want to monitor to your application's address list. The example below adds one Ethereum address:

curl -X POST "$BASE_URL/tx/api/v1/addresses" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "wallets": [
      {
        "chain_type": "ethereum",
        "address": ["0x1234567890abcdef1234567890abcdef12345678"]
      }
    ]
  }'

Expected response:

{
  "code": 0,
  "message": "ok",
  "data": "success"
}

You can add addresses for multiple chains in one request:

curl -X POST "$BASE_URL/tx/api/v1/addresses" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "wallets": [
      {
        "chain_type": "ethereum",
        "address": ["0xabc...001", "0xabc...002"]
      },
      {
        "chain_type": "solana",
        "address": ["So1ana...address"]
      }
    ]
  }'

---

Step 2: Configure Webhook callbacks and receive real-time pushes

After the address is added successfully, we recommend receiving server-to-server real-time pushes through Webhook. Provide a public HTTPS callback URL and configure it for the current application:

curl -X PUT "$BASE_URL/tx/api/v1/app/config" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "enable_webhook": true,
    "webhook_url": "https://example.com/tx-history/webhook",
    "webhook_secret": "replace-with-shared-secret"
  }'

When a monitored address matches a new transaction, the service POSTs a TransactionDetail[] array to your webhook_url. Webhook requests include:

Content-Type: application/json
Sign: replace-with-shared-secret

The callback body has no outer code, message, or data wrapper. It is the transaction array directly:

[
  {
    "chain_type": "ethereum",
    "chain_id": 1,
    "height": 21000000,
    "tx_hash": "0xabc123...",
    "tx_time": 1745000000,
    "sender": "0x1234...",
    "receiver": "0x5678...",
    "amount": "1000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "tx_status": "success",
    "transfer_type": "native",
    "token_transfers": [],
    "from_details": [],
    "to_details": [],
    "internal_transactions": []
  }
]

Return any 2xx status code after accepting the callback. Use chain_type + chain_id + tx_hash as your idempotency key.

View and handle Webhook retries

If your callback service is offline or returns a non-2xx response, the service stores pending transactions in a persistent queue and retries with a gradual interval from 1s to 36h. While retrying, later matched transactions are also queued. Each retry sends up to 100 transactions in one batch.

Query retry status:

curl "$BASE_URL/tx/api/v1/app/webhook/retry/status" \
  -H "X-API-Key: $API_KEY"

After your service is restored, trigger an immediate retry:

curl -X POST "$BASE_URL/tx/api/v1/app/webhook/retry" \
  -H "X-API-Key: $API_KEY"

If the same batch still cannot be delivered after 36h, the system automatically disables enable_webhook and records the failed transaction ID and the last failure reason in the application configuration. Re-enable Webhook after fixing the callback service.

---

Step 3: Query historical transactions

In addition to real-time pushes, you can query historical transactions for an address through HTTP:

curl -X POST "$BASE_URL/tx/api/v1/transfers/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "chain_type": "ethereum",
    "chain_id": 1,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "limit": 10
  }'

Expected response, shortened:

{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "chain_type": "ethereum",
      "chain_id": 1,
      "tx_hash": "0xabc123...",
      "sender": "0x1234...",
      "receiver": "0x5678...",
      "amount": "1000000000000000000",
      "symbol": "ETH",
      "tx_status": "success"
    }
  ]
}

---

Optional: use WebSocket pushes

If your use case needs a browser or long-lived connection, you can also establish a WebSocket connection to receive real-time transactions.

Quick test with wscat

# Install wscat if it is not installed yet.
npm install -g wscat

# Establish the connection.
wscat -c "$BASE_URL/tx/api/v1/transaction/ws" \
  -H "X-API-Key: $API_KEY"

After the connection succeeds, the server immediately sends a confirmation message:

{
  "id": "msg-xxx",
  "time": 1745000000000,
  "type": "connected",
  "code": 0,
  "data": {
    "clientId": "client-abc123",
    "appId": "current-business-identity"
  },
  "msg": "success"
}

Receive real-time transactions

When a monitored address has an on-chain transaction, the server pushes:

{
  "id": "msg-tx-001",
  "time": 1745000000000,
  "type": "transaction",
  "code": 0,
  "data": {
    "chain_type": "ethereum",
    "chain_id": 1,
    "height": 21000000,
    "tx_hash": "0xabc123...",
    "tx_time": 1745000000,
    "sender": "0x1234...",
    "receiver": "0x5678...",
    "amount": "1000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "tx_status": "success",
    "token_transfers": [],
    "listenAddress": ["0x1234..."],
    "is_reorg_resend": false
  },
  "msg": "success"
}

After receiving a transaction message, send an ACK to avoid server retries:

{
  "id": "ack-001",
  "type": "transactionACK",
  "data": {
    "chain_type": "ethereum",
    "chain_id": 1,
    "txHash": "0xabc123..."
  }
}