转账监听 · 快速上手

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

1. 加监听地址

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

2. 打开推送

curl -X PUT "$BASE_URL/tx/api/v1/app/config" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"enable_ws":true,"enable_webhook":true,"webhook_url":"https://your-server.example/hooks/tx","webhook_secret":"your-secret"}'

webhook_url 必须公网可达。只要 WebSocket 可把 enable_webhook 设成 false。

3. 连 WebSocket

npx wscat -c "wss://gateway.gelabs.org/tx/ws" -H "X-API-Key: $API_KEY"

连上后先收到 type: connected。命中转账时是 type: transaction，data 里有 tx_hash / txHash：

{
  "id": "msg-1",
  "time": 1710000000000,
  "type": "transaction",
  "code": 0,
  "data": {
    "chain_type": "evm",
    "chain_id": 1,
    "tx_hash": "0xabc...",
    "txHash": "0xabc...",
    "sender": "0x1111...",
    "receiver": "0x2222...",
    "amount": "1000000000000000000",
    "listenAddress": ["0x1111..."]
  },
  "message": "success"
}

立刻回 ACK，否则会重推。帧字段是 message，不是 msg：

{
  "id": "ack-1",
  "type": "transactionACK",
  "data": {"chain_type": "evm", "txHash": "0xabc...", "messageId": "msg-1"}
}

4. 收 Webhook

服务端会 POST 到你的 webhook_url，请求头带 Content-Type: application/json 和 Sign: your-secret。本体是裸数组；每项同时有 camelCase（chainType、txHash）与 snake_case 兼容键（chain_type、tx_hash 等）：

[
  {
    "chain_type": "evm",
    "chain_id": 1,
    "tx_hash": "0xabc...",
    "chainType": "evm",
    "chainId": 1,
    "txHash": "0xabc...",
    "sender": "0x1111...",
    "receiver": "0x2222...",
    "amount": "1000000000000000000",
    "listenAddress": ["0x1111..."]
  }
]

你的接口返回 HTTP 2xx 即可。完整字段见 接口。

5. 查历史

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