转账监听 · 接口

前缀 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​

请求头​

请求体​

你的响应​

地址