轉帳監聽 · 接口

前綴 https://gateway.gelabs.org。一律 X-API-Key。

HTTP 查詢包在 {code,message,data} 裡，成功 code 為 0。WebSocket 幀和 Webhook 請求體不套這層信封。

地址

方法	路徑	說明
GET	`/tx/api/v1/addresses`	名單（`page`、`pageSize`、`chain_type`）
POST	`/tx/api/v1/addresses`	增加。`wallets[]`: `chain_type`、`chain_id`、`address[]`
POST	`/tx/api/v1/addresses/batch-delete`	按同樣結構刪除
PATCH	`/tx/api/v1/addresses`	`add` / `remove`
POST	`/tx/api/v1/addresses/contains`	是否已訂閱

HTTP 名單是持久訂閱。即時推送還要打開 enable_ws / enable_webhook。

排除推送

監聽訂閱與歷史查詢保持不變。同一 chain_type 下，發送方、接收方，或代幣轉帳的 from / to / 合約命中排除名單時，該筆不進 WebSocket 與 Webhook。

方法	路徑	說明
GET	`/tx/api/v1/addresses/exclusions`	名單（`page`、`pageSize`、`chain_type`）
POST	`/tx/api/v1/addresses/exclusions`	增加。`wallets[]` 與監聽地址相同
POST	`/tx/api/v1/addresses/exclusions/batch-delete`	按同樣結構移除

交易查詢

方法	路徑	說明
POST	`/tx/api/v1/transfers/search`	單地址歷史。遊標 `id`，過濾 `tx_type`（`native` / `token` / `other`）、`token`
POST	`/tx/api/v1/transfers/multi-chain`	多鏈多地址
POST	`/tx/api/v1/transactions/batch-get`	按 `tx_hash` 批次
GET	`/tx/api/v1/transactions/{tx_hash}`	單筆，query 需 `chain_type`、`chain_id`

search 示例：

{
  "address": "0x...",
  "chain_type": "evm",
  "chain_id": 1,
  "limit": 20
}

推送設定

方法	路徑	說明
GET	`/tx/api/v1/app/config`	目前 WS / Webhook 開關
PUT	`/tx/api/v1/app/config`	`enable_ws`、`enable_webhook`、`webhook_url`、`webhook_secret`
POST	`/tx/api/v1/app/webhook/retry`	重試失敗投遞

開 Webhook 時必須帶公網 webhook_url。webhook_secret 可選；設了之後，每次 POST 都會帶請求頭 Sign。

{
  "enable_ws": true,
  "enable_webhook": true,
  "webhook_url": "https://your-server.example/hooks/tx",
  "webhook_secret": "your-secret"
}

轉帳物件

WebSocket type: transaction 的 data，以及 Webhook 陣列裡的每一項，都描述同一筆轉帳，但 JSON 形狀不完全相同（見下方 Webhook 一節）。

推送裡的鏈族是 evm / tvm / svm / utxo。已支持網路與 chain_id 見簡介。

camelCase 主字段（新接入建議優先讀這組）：

欄位	類型	說明
`chainType`	string	鏈族，如 `evm`、`tvm`
`chainId`	integer	鏈 ID，如以太坊主網 `1`
`txHash`	string	交易哈希
`txTime`	integer	交易時間，毫秒 Unix
`height`	integer	區塊高度
`sender`	string	發送方
`receiver`	string	接收方
`feePayer`	string	手續費支付方
`amount`	string	主幣金額（字串，不要當 JS number）
`symbol`	string	主幣符號
`decimals`	integer	主幣精度
`txStatus`	string	鏈上狀態，如 `success`
`gasLimit` / `gasUsed` / `gasPrice` / `txFee`	string	Gas 與手續費（字串）
`nonce`	string	交易 nonce
`transferType`	string	`NativeCoin` / `Token` / `Other`，見下表
`methodId` / `methodCall`	string	合約方法
`l1OriginHash`	string	L1 原交易哈希（L2 等）
`listenAddress`	string[]	命中的監聽地址；無命中為 `[]`
`tokenTransferDetails`	array	代幣轉帳（camelCase 明細）
`fromDetails`	array	多輸入明細（camelCase）
`toDetails`	array	多輸出明細（camelCase）
`internalTransactionDetails`	array	內部呼叫 / 指令（camelCase）

tokenTransferDetails[] 常用：from、to、tokenContractAddress、symbol、amount、decimals、mint。

transferType

服務端對一筆交易的主轉帳語意分類，各鏈（EVM / TVM / SVM / UTXO）共用同一套取值：

值	含義
`NativeCoin`	主幣直轉。例如 EVM 純 ETH 轉帳、TVM `TransferContract`（TRX）、Bitcoin UTXO。主欄位 `amount` / `symbol` / `decimals` 通常有值。
`Token`	代幣轉帳。例如 ERC-20 / TRC-20 直接 `transfer` 合約呼叫。主幣 `amount` 常為 `"0"`，代幣明細看 `tokenTransferDetails`。
`Other`	其餘合約互動：批量轉帳、非直接 token 呼叫、質押 / 凍結等。若有代幣變動，仍看 `tokenTransferDetails`；主欄位不一定代表實際資產流動。

Webhook 的 snake_case transfer_type 為庫表 Raw 形態，歷史資料可能出現小寫 token；camelCase transferType 一律 PascalCase。

查詢 /tx/api/v1/transfers/search 時，tx_type 過濾大小寫不敏感：native / nativecoin → NativeCoin，token → Token，other → Other。

Webhook 額外帶 snake_case（與上表同義或為庫表 Raw 形態，供舊下游兼容）：

snake_case 鍵	對應 camelCase / 說明
`chain_type`、`chain_id`、`tx_hash`、`tx_time`、`tx_status`	同 `chainType`、`chainId`、`txHash`、`txTime`、`txStatus`
`token_transfers`、`from_details`、`to_details`	與 `tokenTransferDetails` 等同族不同形態（庫表字段名）
`internal_transactions`	與 `internalTransactionDetails` 同族不同形態
`tx_version`、`fee_payer`、`transfer_type`	原始指標形態，可能為 `null`
`max_fee_per_gas`、`max_priority_fee_per_gas`	EIP-1559，可能為 `null`
`gas_limit`、`gas_used`、`gas_price`、`tx_fee`	同 `gasLimit` 等，Raw 指標形態
`method_id`、`method_call`、`l1_origin_hash`	同 `methodId` 等，Raw 指標形態

WebSocket data 與 webhook 業務字段一致，另有 is_reorg_resend（true 表示重組後重推）。沒有舊別名 txhash；請讀 txHash / tx_hash。ACK 請用 chain_type + txHash。

WebSocket

GET wss://gateway.gelabs.org/tx/ws

請求頭 X-API-Key。要收到 transaction 推送，先 PUT /tx/api/v1/app/config 把 enable_ws 設為 true，並用 HTTP 把地址加進名單。

每條幀：

欄位	類型	說明
`id`	string	幀 ID。ACK 時可當作 `messageId`
`time`	integer	毫秒 Unix
`type`	string	見下表
`code`	integer	`0` 成功；非 0 為錯誤
`data`	object / null	依 `type` 而變
`message`	string	說明文字。是 `message`，不是 `msg`

`type`	方向	說明
`connected`	下行	握手成功
`transaction`	下行	命中轉帳，`data` 即轉帳物件
`transactionACK`	上行	確認已收到，停止重發
`ping` / `pong`	雙向	JSON 心跳；也可直接發文字 `ping`
`subscribe` / `unsubscribe`	上行	增刪該 App 的持久監聽地址
`getTxHash`	上行	按哈希查一筆

connected

{
  "id": "c1",
  "time": 1710000000000,
  "type": "connected",
  "code": 0,
  "data": {
    "clientId": "client-uuid",
    "appId": "your-app-id"
  },
  "message": "success"
}

transaction

{
  "id": "msg-1",
  "time": 1710000000000,
  "type": "transaction",
  "code": 0,
  "data": {
    "chain_type": "evm",
    "chain_id": 1,
    "tx_hash": "0xabc...",
    "txHash": "0xabc...",
    "tx_time": 1710000000000,
    "txTime": 1710000000000,
    "height": 12345678,
    "sender": "0x1111...",
    "receiver": "0x2222...",
    "amount": "1000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "tx_status": "success",
    "listenAddress": ["0x1111..."],
    "token_transfers": [],
    "from_details": [],
    "to_details": [],
    "is_reorg_resend": false
  },
  "message": "success"
}

收到後立刻 ACK，否則服務端會重推：

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

chain_type 必填。txHash（或 tx_hash）與 messageId（或 message_id，即下行幀的 id）至少填一個。服務端回同一 type，code 為 0 即確認成功。

{
  "id": "sub-1",
  "type": "subscribe",
  "data": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "chain_type": "evm",
    "chain_id": 1
  }
}

成功時 data 為 {app_id, address, chain_type}。unsubscribe 結構相同，成功時 data 為 {address, chainType}。名單管理建議走 HTTP，避免連線斷開後狀態不好對。

Webhook

服務端向你設定的 webhook_url 發 POST，不是你來拉。

請求頭

頭	說明
`Content-Type`	`application/json`
`Sign`	等於你在 config 裡設的 `webhook_secret`。未設則為空字串

請用明文比對 Sign，它不是 HMAC 簽名。

請求體

根是 JSON 陣列，每項同時帶 camelCase 主字段與 snake_case 兼容鍵（見上方「轉帳物件」）。示例已省略部分可為 null 的 Raw 字段：

[
  {
    "chain_type": "evm",
    "chain_id": 1,
    "tx_time": 1710000000000,
    "tx_hash": "0xabc...",
    "tx_status": "success",
    "gas_limit": "21000",
    "gas_used": "21000",
    "gas_price": "1000000000",
    "tx_fee": "21000000000000",
    "token_transfers": [],
    "from_details": [],
    "to_details": [],
    "internal_transactions": [],
    "chainType": "evm",
    "chainId": 1,
    "txTime": 1710000000000,
    "txHash": "0xabc...",
    "height": 12345678,
    "sender": "0x1111...",
    "receiver": "0x2222...",
    "feePayer": "0x1111...",
    "amount": "1000000000000000000",
    "symbol": "ETH",
    "decimals": 18,
    "txStatus": "success",
    "gasLimit": "21000",
    "gasUsed": "21000",
    "gasPrice": "1000000000",
    "txFee": "21000000000000",
    "nonce": "7",
    "listenAddress": ["0x1111..."],
    "tokenTransferDetails": [],
    "fromDetails": [],
    "toDetails": [],
    "internalTransactionDetails": []
  }
]

舊集成可繼續讀 chain_type / tx_hash；新集成建議讀 camelCase 主字段。

你的回應

返回 HTTP 2xx（body 可空）。非 2xx 或超時會重試；可用 POST /tx/api/v1/app/webhook/retry 手動重投失敗單。

地址​

排除推送​

交易查詢​

推送設定​

轉帳物件​

transferType​

WebSocket​

connected​

transaction​

subscribe​

Webhook​

請求頭​

請求體​

你的回應​

地址