地址转账监听 · 快速上手

快速开始

本节帮助你在约 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"]
      }
    ]
  }'

---

第二步：配置 Webhook 回调，接收实时推送

地址添加成功后，推荐通过 Webhook 接收服务端到服务端的实时推送。你只需要提供一个可公网访问的 HTTPS 回调地址，并把它配置到当前应用：

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

监听地址命中新交易后，服务会向你的 webhook_url POST 一个 TransactionDetail[] 数组。Webhook 请求会带上：

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

回调 body 没有外层 code、message 或 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",
    "transfer_type": "native",
    "token_transfers": [],
    "from_details": [],
    "to_details": [],
    "internal_transactions": []
  }
]

你的回调接口在业务接收成功后返回任意 2xx 状态码即可。建议以 chain_type + chain_id + tx_hash 做幂等去重。

查看和处理 Webhook 重试

如果回调服务离线或返回非 2xx，服务会把待推送交易写入持久化队列，并按 1s 到 36h 的渐进间隔重试。重试期间，后续命中的交易也会进入队列。每次重试最多批量推送 100 条交易。

查看状态：

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

服务恢复后，可手动触发一次立即重试：

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

如果同一批消息超过 36h 仍无法成功推送，系统会自动关闭 enable_webhook，并在应用配置中记录失败交易 ID 和最后失败原因。修复回调服务后，需要重新开启 Webhook。

---

第三步：查询历史交易

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

预期响应（简略）：

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

---

可选：使用 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,
    "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"
}

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

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