如何通过 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 配置。

这篇帮你完成什么任务

选择 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]0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3efkeccak256("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(已处理完毕的最高区块号):

  1. 每次轮询时,将起始高度设为 fromBlock = last_polled_block + 1。
  2. 通过 eth_blockNumber 获取链头当前高度,并结合确认深度计算目标高度 safe_head。
  3. 若 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) 去重

构建充值监听时,必须具备严格的幂等去重能力:

  1. 同交易多转账:单一交易哈希可能包含多笔向同一收款地址的转账(例如路由合约的拆单兑换、聚合支付或批量分发)。因此不能仅用 transactionHash 作为去重键。
  2. 重叠轮询与重试:当服务发生重启、异常重试,或为了防范浅层重组而在回退数个区块后重新轮询时,同一区块的日志会被多次拉取。
  3. 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

计费规则与相关参考

下一步

最后更新:

本页目录