PolyPay logoPolyPay.ai
初级5 分钟阅读

钱包监控

监控公开链上地址的转入与转出，无需将地址设置为 PolyPay 收款钱包。

收款钱包与监控地址

收款钱包参与支付路由；监控地址只记录链上活动并触发提醒。同一网络和地址可以同时拥有两种角色，但禁用或删除任一角色都不会改变另一角色。

配置钱包监控

在地址列表点击编辑，会进入与添加地址共用的表单页，标题变为编辑并回填已有设置；保存后返回地址列表。

  1. 在钱包监控中选择添加监控地址，进入 /wallet-monitoring/add，点击地址右侧的“从商户收款导入”按钮后打开选择面板，再选择商户和收款钱包。从 Getting Started 进入时，保存、取消或返回均回到 Getting Started；从地址列表进入时，则回到地址列表。
  2. 从区块链配置中选择已启用的链和一个或多个币种/合约，再确认地址格式与所选链一致；无效的 Tron 地址会被拒绝。PolyPay 不会要求私钥。
  3. 打开地址开关后开始监控。钱包监控模板独立于通知渠道和事件管理。请选择已配置的渠道和一条可复用模板；同一渠道或模板可以重复选择。
  4. 可选：创建独立的钱包监控 Webhook。新端点默认禁用，保存的配置完成签名测试并通过后才能启用。

通知与模板

在地址表单的齿轮入口配置模板和渠道。管理列表使用面板，新增与编辑使用弹窗并保留地址草稿。每行“发送测试”仅使用该行已保存的渠道和选中模板，不保存地址，也不代表已监测到真实转账。 监控地址禁用、删除或因计费暂停后，失败的渠道提醒停止重试，手动重发也会被拦截；已经发送的消息不会撤回。

钱包监控仅通知链上发生时间距今不超过 72 小时的交易。首次扫描、补发及重试均受此限制；超过 72 小时的交易仍可保留在交易记录中，但不再发送站内、外部渠道或 Webhook 通知。

配置自定义合约

自定义合约仅限有效的钱包监控付费套餐使用，包含按量付费。 网络及 RPC 启用后，可为 Ethereum、BSC、Polygon、Base、Arbitrum、Optimism 配置自定义合约。仅支持 0—18 位精度的 ERC-20 转账。资产以网络和合约地址区分，同名代币不会合并；元数据必须通过链上验证。修改或删除前须解除所有监控地址的引用。记录和通知包含实际合约地址。 在「钱包监控 → 自定义合约」页面选择网络，新增、编辑或删除合约。地址表单的配置入口会在当前页面打开右侧栏，保存后自动刷新可选合约。 新增和编辑合约均在右侧栏中完成。 套餐到期或失效后，自定义合约监控及通知暂停，合约记录保留。 免费套餐可查看自定义合约页面；点击添加时会提示开通高级套餐。 列表默认显示全部网络，也可按网络筛选。新增时选择网络并填写合约地址，点击识别后保存；编辑时自动带入合约所属网络。 识别后可修改名称、符号和精度（0–18 的整数），保存后仅对当前用户的合约记录生效；共享扫链仍使用链上原始元数据。

钱包监控快速入门

钱包监控“快速入门”读取已保存的地址、可选通知路由及实际交易。测试成功只验证消息投递，结果仅保留在当前会话；监测到真实转账后才确认监听结果。时间按账号时区展示。

独立 Webhook

钱包监控在“通知设置”的模板下方管理一个 Webhook，不复用支付 Webhook 配置，也不使用通知渠道中的旧通用 Webhook。该配置拥有独立事件与地址范围、密钥、HMAC-SHA256 签名、重试状态和固定版本 JSON。修改 URL、范围、事件或密钥后会保持禁用，直到重新测试通过。旧通用 Webhook 只读保留，请通过迁移操作创建并测试该配置。

验签方式

验签时请在解析 JSON 前读取原始请求体。读取 X-PolyPay-Timestamp 和 X-PolyPay-Signature（格式为 t=<timestamp>,v1=<hex>），使用完整的 whsec_... 密钥对 <timestamp>.<raw body> 计算 HMAC-SHA256，并使用常量时间比较签名。拒绝时间戳与当前时间相差超过 5 分钟的请求，并按 payload 的 id 只处理一次。每次测试请求都会使用唯一的测试事件 ID。

import { createHmac, timingSafeEqual } from 'node:crypto';

const rawBody = await request.text();
const timestamp = request.headers.get('x-polypay-timestamp') ?? '';
const signature = request.headers.get('x-polypay-signature') ?? '';
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signature);
if (!match || match[1] !== timestamp) throw new Error('Invalid signature header');

if (Math.abs(Date.now() / 1000 - Number(match[1])) > 300) {
  throw new Error('Stale webhook');
}

const expected = createHmac('sha256', process.env.WALLET_WEBHOOK_SECRET!)
  .update(match[1] + '.' + rawBody)
  .digest();
const received = Buffer.from(match[2], 'hex');
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
  throw new Error('Invalid signature');
}

const event = JSON.parse(rawBody);
// Store event.id before applying the event so retries are processed once.

账号邮件通知

套餐开通、续费结果、到期和监控中断会发送账号邮件与站内信，不消耗监控通知额度。到期前 7、3、1 天内分别提醒；邮件遵循账号邮件语言偏好，到期时间按账号时区展示。

通知投递用量达到 UTC 自然月额度的 80% 和 100% 时发送预警。支持按量付费的套餐在额度用尽且余额充足时继续扣费发送；余额不足时提醒。地址暂停与恢复按账号和原因在五分钟窗口内聚合，链服务同步成功后才通知恢复。套餐到期后按免费权益提供服务，自定义合约监控需要有效付费套餐。 以上额度仅用于人工通知渠道；独立的钱包监控 Webhook 仍不限次数。

套餐与用量

支付通知和钱包监控 Webhook 不限次数。只有钱包监控人工渠道成功投递时，才会按目标消耗账号级通知额度；失败投递和没有人工渠道投递的监控不扣额度。套餐在独立的“钱包监控套餐”页管理，共享资金和流水仍在独立的账户余额页管理。 钱包监控付费套餐支持月付、季付、半年付和年付。季付为月价的 3 倍，半年付为月价的 6 倍，年付按标示年价计算。自动续费沿用已购周期，从账号余额扣款。 购买确认中的自动续费默认开启，可在确认购买前手动关闭。

Pay as you go

$0.50/地址/月 · $0.002/次通知成功投递

每个已启用地址预付一个日历月费用。已付周期内重新启用不重复收费，停用后不续扣。余额不足时暂停对应地址；充值后自动恢复，每分钟检查一次。人工渠道通知按每个目标的成功投递收取 $0.002，失败释放预占，重试不重复扣款。 停用按量套餐前，请先将已启用地址减少到 Free 套餐上限。