Skip to main content

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:

CredentialPurposeExample
API keyAPI 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: Establish a WebSocket connection and receive real-time pushes​

After the address is added successfully, 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,
    "txhash": "0xabc123...",
    "sender": "0x1234...",
    "receiver": "0x5678...",
    "amount": "1000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "txStatus": "success",
    "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..."
  }
}

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/query" \
  -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"
    }
  ]
}