地址轉帳監聽 · 快速上手

快速開始

本節幫助你在約 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/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"
    }
  ]
}

---

可選：配置 Webhook 回呼

如果你的服務端更適合接收 HTTP 回呼，可以配置 Webhook。監聽地址命中新交易後，服務會向你的 webhook_url POST 一個 TransactionResult[] 陣列。

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 請求會帶上：

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

你的回呼介面在業務接收成功後返回任意 2xx 狀態碼即可。建議以 chainType + chainId + txHash 做冪等去重。

查看和處理 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。