如何通过 Webhook 与 RPC 监听 USDT / USDC 收款
用 Webhook 或 eth_getLogs 轮询监听 EVM 链上的稳定币收款,按交易哈希与日志序号去重,按单次区块跨度上限分段补扫并处理重组,验签失败返回 401,接收成功返回 204,入账前按确认策略核对。
稳定币收款监控或交易所充值检测可通过 Webhook、WebSocket 日志或 HTTP 轮询监听 EVM 链上的 ERC-20 USDT / USDC 转账。开发者与 AI Agent 使用同一套接口;处理收款前先确定链、代币合约、收款地址与确认深度。在 USDT / USDC 转账监控方案 中选择充值核验、商户收款通知或出款追踪工作流。
- 第一步:先准备 API key 与自有 HTTPS 接收端,再按创建订阅并关注收款地址操作。
- 完成标准:匹配转账通过验签及链、代币、收款地址与整数金额校验,作为收款候选记录去重保存,接收端返回 HTTP
204;入账前仍需按自己的确认策略完成链上核验。
基础转账监控已可用。金额与代币筛选在你的接收端执行。服务端条件、多阶段确认与 IM 提醒即将推出。
面向开发者与 AI Agent:先准备 API key 与自有 HTTPS 接收端,在应用中筛选代币合约与金额。复制 Webhook 配置。
这篇帮你完成什么任务
- 接收 USDT / USDC 到账通知:先核对所选链的 Push 支持,再将事件发送到自己的 HTTPS 接收端。
- 校验转账候选记录:核对链、代币合约、收款地址与整数金额,再按自己的链上核验与确认策略处理。
- 补扫缺失的转账日志:按有界区块窗口调用
eth_getLogs并保存游标。
选择 Webhook、WebSocket 或轮询
| 方式 | 适用场景 | 恢复路径 |
|---|---|---|
| Webhook | 在 HTTPS 接收端获取地址活动,包括代币转入 | 验签、按事件 ID 去重,处理 subscription.gap / chain.reorg,重放保留的已匹配事件 |
| WebSocket | 通过长连接获取过滤后的 logs | 重连、重新订阅并补扫缺失区块 |
| HTTP 轮询 | 定时监听,或用自己的游标补扫历史日志 | 分段查询 eth_getLogs 并持久保存进度 |
选择 WebSocket 前读取公开 GET /v1/chains 的 ws 与 subscriptions。Push 支持需另行携带 API key 查询 GET /v1/push/chains;没有 WebSocket 的链,只要出现在该列表,仍可使用地址 Webhook。扫描更早的区块或不适合维持长连接时使用轮询。
用 Webhook 接收到账
创建订阅并关注收款地址
先获取 API key,部署端口 443 的 HTTPS 接收端。从带 key 的 Push 链列表选择 CHAIN,将 RECIPIENT 设为收款地址,RECEIVER_URL 设为接收 URL。下面的 shell 示例需要 jq;{} 使用该链默认确认数。自定义确认数前先读取 min_confirmations、default_confirmations 与 max_confirmations。请求定义见 Push OpenAPI。
set -eu
umask 077
: "${BLOCKVECTRA_API_KEY:?Set your API key}"
: "${CHAIN:?Select a chain from the Push chain list}"
: "${RECIPIENT:?Set the watched EVM recipient address}"
: "${RECEIVER_URL:?Set your HTTPS receiver URL}"
PUSH_URL='https://api.blockvectra.com/v1/push'
curl --fail-with-body -sS "$PUSH_URL/chains" \
-H "x-api-key: $BLOCKVECTRA_API_KEY" > push-chains.json
jq -e --arg chain "$CHAIN" 'any(.chains[]; .chain == $chain)' push-chains.json
jq -n --arg url "$RECEIVER_URL" --arg chain "$CHAIN" \
'{url: $url, chains: {($chain): {}}}' > create.json
curl --fail-with-body -sS "$PUSH_URL/subscriptions" \
-H "x-api-key: $BLOCKVECTRA_API_KEY" \
-H 'Content-Type: application/json' -d @create.json > subscription.json
SUBSCRIPTION_ID=$(jq -er '.id' subscription.json)
jq -n --arg recipient "$RECIPIENT" '{addresses: [$recipient]}' > addresses.json
curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID/addresses/add" \
-H "x-api-key: $BLOCKVECTRA_API_KEY" \
-H 'Content-Type: application/json' -d @addresses.json > address-change.json
curl --fail-with-body -sS "$PUSH_URL/subscriptions/$SUBSCRIPTION_ID" \
-H "x-api-key: $BLOCKVECTRA_API_KEY"创建返回 id 与 secret。安全保存密钥供接收端验签;subscription.json 含凭据。轮询订阅,直到 applied_version >= address-change.json 中的 change_version,记录 chains[CHAIN].applied_from_block。新地址从该块开始匹配,此前的收款区间仍需轮询补齐。
验签、去重与收款校验
将原始正文验签函数保存为 verify-push.js。下面的接收函数在 Node.js 中接收 Web API Request,先读取原始字节,验签后再解析 JSON。secrets 为订阅 ID 字符串到已保存密钥的 Map。expected 来自可信配置,格式为 { chain, token, recipient, amountUnits }:token 是已核实的该链稳定币合约,amountUnits 是以最小单位表示的预期正整数金额。用 BigInt 比较金额,不用浮点数或代币符号判断到账。
import { verifyPush } from './verify-push.js';
export function selectPayment(data, event, expected) {
if (data.chain !== expected.chain || event.type !== 'token.transfer' ||
event.standard !== 'erc20') return null;
const address = value => typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value);
if (![event.token, event.to, expected.token, expected.recipient].every(address)) return null;
if (event.token.toLowerCase() !== expected.token.toLowerCase() ||
event.to.toLowerCase() !== expected.recipient.toLowerCase()) return null;
const integer = value => typeof value === 'string' && /^[1-9][0-9]{0,77}$/.test(value);
if (!integer(event.amount) || !integer(expected.amountUnits)) return null;
const amount = BigInt(event.amount);
if (amount >= (1n << 256n) || amount !== BigInt(expected.amountUnits)) return null;
if (typeof event.id !== 'string' || typeof event.ref !== 'string' ||
!/^0x[0-9a-f]{64}$/.test(event.tx_hash) ||
!/^0x[0-9a-f]{64}$/.test(event.block_hash) ||
!Number.isSafeInteger(event.log_index) || event.log_index < 0 ||
!Number.isSafeInteger(event.block_number) || event.block_number < 0) return null;
return {
eventId: event.id, ref: event.ref, chain: data.chain,
token: event.token, recipient: event.to, amountUnits: event.amount,
txHash: event.tx_hash, logIndex: event.log_index,
blockHash: event.block_hash, blockNumber: event.block_number,
};
}
export async function receivePayments(request, expected, secrets, store) {
const rawBody = Buffer.from(await request.arrayBuffer());
const headers = Object.fromEntries(request.headers);
if (!verifyPush(rawBody, headers, secrets)) return new Response(null, { status: 401 });
let message;
try { message = JSON.parse(rawBody.toString('utf8')); }
catch { return new Response(null, { status: 400 }); }
const data = message?.data;
if (message?.type !== 'push.events' ||
!Number.isSafeInteger(data?.subscription_id) || data.subscription_id <= 0 ||
String(data.subscription_id) !== headers['bv-subscription-id'] ||
data.chain !== expected.chain || !Array.isArray(data.events)) {
return new Response(null, { status: 400 });
}
try {
await store.transaction(async tx => {
for (const event of data.events) {
if (!event || typeof event.id !== 'string') continue;
const recovery = event.type === 'subscription.gap' || event.type === 'chain.reorg';
const payment = selectPayment(data, event, expected);
if (!recovery && !payment) continue;
if (!await tx.insertEventOnce(data.subscription_id, event)) continue;
if (recovery) await tx.enqueueRecovery(data.chain, event);
else await tx.recordPaymentCandidate(payment);
}
});
} catch {
return new Response(null, { status: 503 });
}
return new Response(null, { status: 204 });
}用持久存储实现 store.transaction。在同一事务内,insertEventOnce 按唯一键 (subscription_id, event.id) 插入事件,重复时返回 false;与 recordPaymentCandidate 或 enqueueRecovery 一起提交。失败时回滚全部写入,让重试可以继续处理;恢复任务也需幂等。提交后才在 10 秒内返回 2xx;HTTP 服务需限制正文为 1 MiB。
示例校验一笔预期金额。多订单场景按链、代币合约与收款地址查找可信订单配置,自行处理部分付款或超额付款。候选收款仍需核验链上事实并满足自己的确认策略,之后才入账。跨订阅或同时使用轮询时,按链、交易哈希与日志索引核对同一转账,避免两个投递路径重复入账;保留区块哈希以追踪被替换的区块。
恢复缺失或被替换的区块
收到 subscription.gap 后,将 from_block 到 to_block 区间加入补扫任务,使用下文轮询路径或该链可用的 Data API 数据集。chain.reorg 是已投递区块被替换的免费通知,不表示投递缺口。按 ref 标记或丢弃该区间的旧事件,按 ref 与 tx_hash 对照规范链核对已记录的入账,再处理自动重投、具有新 ID 的规范链事件,并按 id 去重。重组通知不推进完成进度;按链记录 complete_through_block,不要用最大事件块号推断整块完成。
重放接收 chain 与 from_block,起点需在当前 replayable_from_block 边界内。它只重投保留的已匹配事件,不扫描地址或链加入前、订阅离线期间的数据。保留轮询游标补齐这些区间及过期缺口。请求失败与重放范围错误见错误参考,投递、历史查询与地址日费用见计费规则。
下文给出 ERC-20 日志过滤与游标轮询的实现,供收款监听和恢复补扫使用。
Transfer 事件与过滤参数
ERC-20 标准代币合约在发生转账时会抛出如下事件:
event Transfer(address indexed from, address indexed to, uint256 value);调用 eth_getLogs 时,通过传入代币合约地址与 topics 数组进行精准过滤:
| 参数 | 取值 | 说明 |
|---|---|---|
address | 代币合约地址(或地址数组) | 目标稳定币合约地址。可传入单个地址(如 BSC USDT 合约 0x55d398326f99059fF775485246999027B3197955、Base USDC 合约 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913),也可传入数组同时匹配多个代币合约 |
topics[0] | 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef | keccak256("Transfer(address,address,uint256)") 的事件签名哈希 |
topics[1] | null | 付款方地址(from)。监听充值时通常允许任意外部账户付款,传 null 表示通配任意发送方 |
topics[2] | 填充为 32 字节的收款地址 | 接收方地址(to)。在 EVM 事件日志规范中,indexed 的地址类型占用 32 字节(64 位十六进制字符),在 20 字节的目标地址左侧补齐 12 个零字节(24 个十六进制 0 字符)构成 32 字节 topic |
fromBlock | 起始区块(十六进制) | 查询闭区间的起始高度 |
toBlock | 结束区块(十六进制) | 查询闭区间的结束高度 |
未被索引的 value(转账金额)存放在日志对象的 data 字段中,为 32 字节十六进制编码的 uint256。解析时需除以代币对应的精度位数(例如 BSC USDT 为 18 位小数,Base / 以太坊 USDC 为 6 位小数)。
游标轮询与单次区间上限
监听服务通常以固定的时间间隔(例如 3~5 秒)拉取新区块的日志。
游标推进机制
客户端在数据库或本地持久化存储中维护一个游标 last_polled_block(已处理完毕的最高区块号):
- 每次轮询时,将起始高度设为
fromBlock = last_polled_block + 1。 - 通过
eth_blockNumber获取链头当前高度,并结合确认深度计算目标高度safe_head。 - 若
fromBlock <= safe_head,则分段查询日志;处理成功后将游标推进至该次查询的结束高度。
单次区块跨度限制
单次 eth_getLogs 请求的区块跨度按照 toBlock − fromBlock + 1 计算,不能超过目标链在 GET /v1/chains 中公布的 max_logs_block_range。
若请求的区块跨度超过该上限,服务端会直接拒绝请求并返回错误:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "eth_getLogs block range too large: max 1000 blocks",
"data": {
"reason": "logs_range_too_large",
"docs_url": "https://docs.blockvectra.com/en/errors/#logs_range_too_large",
"retryable": false
}
}
}超出跨度返回 JSON-RPC 错误 -32602(不计费)。在程序实现中,应先从 GET /v1/chains 读取 max_logs_block_range,在追块或处理大跨度区间时将区间拆分为不超过上限的小段:chunk_end = min(fromBlock + max_logs_block_range - 1, safe_head)。
处理区块重组与确认深度
公链节点在链头附近可能出现短暂分叉与区块重组(Reorganization)。若直接查询 latest 并在第一时间入账,当该区块因重组被废弃时,可能发生入账资金落空的问题。
为保证记账安全,需采取以下防范措施:
确认深度(Confirmation Depth)
不要直接将查询区间推进到链头 latest,而是在链头高度之后保留足够的确认深度:
safe_head = current_head - CONFIRMATION_DEPTH
根据业务风控要求设置 CONFIRMATION_DEPTH。仅查询至 safe_head 即可保证只处理获得充分确认的区块。
轮询中的区块重组
标准以太坊 JSON-RPC 规范仅在 WebSocket logs 订阅推送中、当先前发出的事件因链重组被回滚时将日志对象的 removed 设为 true。通过 HTTP 使用 eth_getLogs 轮询时,查询只返回规范链上的日志;重组掉的日志不会在后续查询中出现。只要在 safe_head 范围内轮询,即可保证只处理获得充分确认的区块。
按 (transactionHash, logIndex) 去重
构建充值监听时,必须具备严格的幂等去重能力:
- 同交易多转账:单一交易哈希可能包含多笔向同一收款地址的转账(例如路由合约的拆单兑换、聚合支付或批量分发)。因此不能仅用
transactionHash作为去重键。 - 重叠轮询与重试:当服务发生重启、异常重试,或为了防范浅层重组而在回退数个区块后重新轮询时,同一区块的日志会被多次拉取。
- logIndex 的唯一性:
logIndex是该事件在该区块内的日志索引号。标准 EVM 中,同一笔转账日志在链上的天然唯一标识为复合键(transactionHash, logIndex)。
在业务数据库中,应为充值入账记录表建立唯一联合索引:
CREATE UNIQUE INDEX idx_transfers_tx_log ON deposit_records (transaction_hash, log_index);在写入入账流水前,依据 (transactionHash, logIndex) 判定该事件是否已处理,确保同一笔链上转账不会被重复入账。
完整代码示例
以下示例演示连接目标链、读取 /v1/chains 配置、按安全深度和单次区间上限分段拉取稳定币 Transfer 日志并进行去重处理的完整流程。
import { createPublicClient, formatUnits, http, parseAbiItem } from "viem";
const apiKey = process.env.BLOCKVECTRA_API_KEY;
if (!apiKey) {
throw new Error("请设置环境变量 BLOCKVECTRA_API_KEY");
}
const CHAIN = "bsc_mainnet";
const RPC_URL = "https://api.blockvectra.com/v1/bsc_mainnet";
const CHAINS_URL = "https://api.blockvectra.com/v1/chains";
// 目标稳定币合约地址(此处以 BSC USDT 为例)
const TOKEN_CONTRACT = "0x55d398326f99059fF775485246999027B3197955" as const;
const TOKEN_DECIMALS = 18;
// 监听的专属收款地址
const RECIPIENT_ADDRESS = "0xdded13D555B6DA811103cC1794D3d4330F69632C" as const;
// 防范区块重组的安全确认深度(区块数)
const CONFIRMATION_DEPTH = 15n;
// 1. 从公开元数据接口读取目标链的能力配置(免鉴权、不计费)
const chainsRes = await fetch(CHAINS_URL);
const { chains } = (await chainsRes.json()) as {
chains: Array<{
chain: string;
ws: boolean;
subscriptions: string[];
max_logs_block_range: number;
}>;
};
const chainConfig = chains.find((c) => c.chain === CHAIN);
if (!chainConfig) {
throw new Error(`未在 /v1/chains 中找到链 ${CHAIN}`);
}
const maxLogsRange = BigInt(chainConfig.max_logs_block_range || 1000);
console.log(`链: ${CHAIN} | WebSocket 支持: ${chainConfig.ws} | 单次日志跨度上限: ${maxLogsRange}`);
// 2. 初始化 viem 客户端
const client = createPublicClient({
transport: http(RPC_URL, {
fetchOptions: {
headers: { "x-api-key": apiKey },
},
}),
});
// 本地去重集合,以 (transactionHash, logIndex) 为复合主键
const processedLogs = new Set<string>();
// 3. 计算查询区间:从当前链头扣除确认深度得到 safeHead
const currentHead = await client.getBlockNumber();
const safeHead = currentHead - CONFIRMATION_DEPTH;
// 演示:从 safeHead 前 10 个区块作为游标起点
let cursor = safeHead > 10n ? safeHead - 10n : 0n;
console.log(`当前链头: ${currentHead} | 安全链头: ${safeHead} | 轮询起始游标: ${cursor}`);
while (cursor <= safeHead) {
const chunkEnd = cursor + maxLogsRange - 1n < safeHead ? cursor + maxLogsRange - 1n : safeHead;
const logs = await client.getLogs({
address: TOKEN_CONTRACT,
event: parseAbiItem(
"event Transfer(address indexed from, address indexed to, uint256 value)"
),
args: {
to: RECIPIENT_ADDRESS,
},
fromBlock: cursor,
toBlock: chunkEnd,
});
for (const log of logs) {
const dedupKey = `${log.transactionHash}-${log.logIndex}`;
if (processedLogs.has(dedupKey)) {
continue;
}
processedLogs.add(dedupKey);
const tokenAmount = formatUnits(log.args.value ?? 0n, TOKEN_DECIMALS);
console.log(
`[收款到账] 金额: ${tokenAmount} | ` +
`交易: ${log.transactionHash} | 索引: ${log.logIndex} | 区块: ${log.blockNumber}`
);
}
cursor = chunkEnd + 1n;
}
// 运行方式:npx tsx example.mts计费规则与相关参考
- 关于调用计费、CU 消耗规则与各类错误码计费判定的说明,请参阅哪些请求不计费:错误码与计费规则。
- 关于
eth_getLogs单次区块跨度限制的详细机制与分段逻辑,请参阅 eth_getLogs 区块跨度上限与分段查询。 - 关于实时节点查询与 Data API 已索引历史转账的数据差异,请参阅节点近况与已索引历史:什么时候用 eth_getLogs,什么时候用转账接口。
下一步
最后更新: