跳到主要内容

地址转账监听 · 快速上手

快速开始​

本节帮助你在约 10 分钟内完成基本接入，实现针对监听地址的链上交易实时通知与查询。

接入前准备​

在开始之前，请准备以下凭证：

凭证用途示例
API Key用于接口鉴权、调用方识别和计费统计sk-xxx

将服务的 基础 URL 记录好，后续所有示例中用 BASE_URL 代替。

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

第一步：添加监听地址​

将需要监听的钱包地址添加到你的应用地址名单。以下示例添加一个以太坊地址：

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"]
      }
    ]
  }'

预期响应：

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

可以同时添加多条链的地址：

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"]
      }
    ]
  }'

第二步：建立 WebSocket 连接，接收实时推送​

地址添加成功后，即可建立 WebSocket 连接开始接收实时交易：

使用 wscat 快速测试​

# 安装 wscat（如果尚未安装）
npm install -g wscat

# 建立连接
wscat -c "$BASE_URL/tx/api/v1/transaction/ws" \
  -H "X-API-Key: $API_KEY"

连接成功后，服务端会立即发送一条确认消息：

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

接收实时交易​

当监听的地址产生链上交易时，服务端会主动推送：

{
  "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"
}

收到交易消息后，建议发送 ACK 确认，以避免服务端重发：

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

第三步：查询历史交易​

除实时推送外，也可以通过 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
  }'

预期响应（简略）：

{
  "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"
    }
  ]
}