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 套餐上限。