地址转账监听 · 简介

产品概述

简介

地址转账监听服务面向需要跟进钱包地址在链上转账行为的业务场景：服务持续接收并解析多链交易数据，将相关转账结构化后落库，并通过 HTTP 与 WebSocket 将结果推送给已订阅的应用。

设计目标：接入方无需自建节点或自研解析流水线，只需维护监听地址与连接，即可感知指定地址的链上转账与相关交易信息。

---

核心能力

能力	说明
多链交易监听	统一接入 EVM 系、Solana、Tron、Bitcoin 等多条链
实时推送	通过 WebSocket 将链上交易实时推送给订阅方
历史查询	通过 HTTP 接口查询地址的历史交易记录
地址订阅管理	动态增删监听地址，支持多应用隔离
Webhook 通知	将交易数据推送到接入方配置的 HTTP 回调地址

---

支持的链

EVM 兼容链

链	chain_type	主网 chain_id
Ethereum	ethereum	1
BNB Smart Chain	bsc	56
Polygon	polygon	137
Arbitrum One	arbitrum	42161
Optimism	optimism	10
Base	base	8453

非 EVM 链

链	chain_type	主网 chain_id
Solana	solana	1
Tron	tron	1
Bitcoin	bitcoin	1

说明：chain_type 在请求时大小写不敏感，服务端会自动归一化为小写。

---

核心概念

链标识：chain_type 与 chain_id

每条链通过两个字段唯一标识：

• chain_type：链的类型名称，例如 ethereum、solana、tron
• chain_id：链 ID，区分主网与测试网，例如以太坊主网为 1，Sepolia 测试网为 11155111

这两个字段在所有涉及链的接口中均会用到。

公共鉴权：X-API-Key

当前对外提供的接口统一通过公共请求头 X-API-Key 进行接口鉴权和计费识别。地址管理、交易查询和 WebSocket 连接都应携带该请求头。

X-API-Key: your-api-key

统一响应格式

大多数接口的响应遵循以下 JSON 结构：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

字段	类型	说明
code	integer	业务状态码，0 表示成功
message	string	响应消息，成功时通常为 ok
data	any	业务数据，失败时为 null

注意：部分历史接口的消息字段名为 msg 而非 message，接入时请以具体接口文档为准。

错误响应格式

请求失败时，响应结构如下：

{
  "code": 400,
  "msg": "Invalid request",
  "data": null
}

常见 HTTP 状态码：

状态码	含义
400	请求参数校验失败
401	鉴权失败（推流密钥错误）
403	无权限（API Key错误）
504	请求超时（超过 15 秒）
500	服务内部错误

---

鉴权方式

对外 API 统一使用 X-API-Key 请求头。该 Key 同时用于接口鉴权、调用方识别和计费统计。

公共 API Key（X-API-Key）

所有对外接口请求都应携带：

X-API-Key: your-api-key