加密貨幣充值監控：交易平台如何安全入帳鏈上充值

加密貨幣充值監控看起來與電商收款相似，但兩者的帳務風險不同。商店在固定金額的發票付款後交付一件商品；交易平台允許客戶選擇網路，增加其內部餘額，並立即對這筆餘額承擔兌付責任。如果同一筆轉帳被重複入帳、記到錯誤客戶名下，或者客戶提現後鏈上交易又發生回滾，平台就會損失真實資金。

安全的設計是把每次充值嘗試轉化為一個短期付款訂單。先儲存本地充值記錄，再建立包含精確金額和允許鏈與資產組合的訂單，為每條候選網路分配單次使用地址，並且只在收到已經驗籤、去重的 payment.finalized 事件後增加內部帳本餘額。最後用每日對帳任務發現 Webhook 事件流與帳本之間的任何缺口。

這種訂單化模型讓交易平台、場外交易櫃檯、經紀商、遊戲餘額等帳戶充值產品可以共用一套歸一化流程，不必為每條鏈分別搭建掃描器。

充值產生的是負債，不只是一次結帳付款

客戶看到的流程可能只是“選擇網路、傳送穩定幣、檢視餘額”，但後端需要回答的問題比結帳頁面更多。

“金額可變”絕不應表示“可以向這個地址傳送任意金額”。客戶必須在建立充值請求前選擇金額；此後，鏈、資產、收款地址和最小單位金額都必須精確匹配。如果客戶改變主意，應建立新的充值嘗試，而不是等轉帳到達後再重新解釋它。

為什麼看似直接的監聽方案會失敗

輪詢錢包餘額無法識別具體轉帳

餘額是某個時點的存量，不是事件日誌。兩名客戶可能在兩次輪詢之間充值，資金歸集程式可能轉出資產，退款可能減少餘額，一個交易也可能產生多條代幣轉帳。餘額差無法可靠說明應該給哪位客戶入帳。

自建索引器不只是一個遠端過程呼叫迴圈

讀取代幣轉帳日誌只是最容易的部分。生產級索引器還需要持久化掃描游標、重疊掃描、重複抑制、各鏈的地址與代幣歸一化、失敗回執處理、節點故障切換、確認閾值以及鏈重組檢查。每增加一條鏈，就會引入不同的事件模型與最終確定機制。即使索引器完全正確，它仍然沒有提供把轉帳連線到某一個有效充值請求的業務規則。

每名使用者一個永久地址也不能消除全部歧義

永久使用者地址雖然更容易歸屬，卻會形成長期營運身份：團隊需要跨多條鏈、託管遷移、地址洩漏、不支援資產以及多年的交易歷史持續維護它。共用資金地址更棘手，它依賴備註欄位或精確的唯一金額，也更難處理遲到和錯誤轉帳。

對於按充值意圖建立的流程，單次使用的候選地址可以形成更小的歸屬邊界。地址只為一個有效訂單保留，並在訂單進入終態後釋放。它不是永久客戶標識，因此記錄之間仍應透過充值編號、付款訂單號與交易引用連線，不能只靠地址。

訂單化的加密貨幣充值監控流程

客戶選擇金額與網路
        │
        ▼
交易平台儲存充值意圖
        │
        ▼
StableOps 建立訂單並分配候選地址
        │
        ▼
客戶獲得精確金額、鏈、資產與地址
        │
        ▼
客戶在鏈上傳送穩定幣
        │
        ▼
StableOps 檢測、確認並最終確定轉帳
        │
        ▼
簽名 payment.finalized Webhook 到達交易平台
        │
        ▼
平台原子寫入事件與帳本餘額
        │
        ▼
客戶餘額可用

平台擁有業務帳本和收款地址。StableOps 分配平台匯入的地址、監控支援的鏈、把轉帳匹配到有效訂單、跟蹤確認與最終確定，並投遞簽名事件。資金直接進入私鑰仍由平台控制的地址。

1. 建立訂單前先儲存充值意圖

先建立本地記錄，讓每次重試都有穩定的業務鍵：

import { StableOps } from '@stableops/api-sdk'

const client = new StableOps({
  apiKey: process.env.STABLEOPS_API_KEY!,
})

export async function createDeposit(userId: string, amount: string) {
  const deposit = await db.deposits.create({
    data: { userId, requestedAmount: amount, status: 'creating' },
  })

  const order = await client.paymentOrders.create(
    {
      merchantOrderId: deposit.id,
      amount,
      acceptedAssets: [
        { chain: 'base', asset: 'USDC' },
        { chain: 'ethereum', asset: 'USDC' },
        { chain: 'arbitrum', asset: 'USDC' },
        { chain: 'tron', asset: 'USDT' },
      ],
      expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
      metadata: {
        kind: 'deposit',
        user_id: userId,
        deposit_id: deposit.id,
      },
    },
    { idempotencyKey: `deposit:${deposit.id}:create` },
  )

  await db.deposits.update({
    where: { id: deposit.id },
    data: {
      stableopsOrderId: order.id,
      payableAmount: order.amount,
      expiresAt: order.expiresAt,
      status: 'pending',
    },
  })

  return {
    depositId: deposit.id,
    amount: order.amount,
    expiresAt: order.expiresAt,
    paymentInstructions: order.paymentInstructions,
  }
}

merchantOrderId 把遠端訂單連線到本地充值記錄，並且在組織與環境範圍內唯一。冪等鍵保護請求重試；同一筆充值的每次重試都必須複用相同的鍵和相同的請求正文。

返回的每條 paymentInstructions 都提供一種允許的鏈、資產與地址。展示時，應把客戶選中的指令與訂單頂層的 order.amount 和 order.expiresAt 放在一起。不要硬編碼收款地址，不要根據地址猜測網路，也不要允許錢包靜默修改金額。StableOps 會精確匹配組織、環境、鏈、資產、地址與最小單位金額。

2. 把早期狀態當作進度，不要當作可用餘額

所有支援的鏈都使用同一套歸一化生命週期：

created -> detected -> confirmed -> finalized
   |          |            |
expired    reverted     reverted

可以用 payment.detected 顯示“已收到充值”，用 payment.confirmed 顯示“確認中”，但兩種狀態都不應增加可提現或可交易餘額。失敗回執或鏈重組仍可能使已經檢測或確認的付款進入 reverted。

只有 payment.finalized 到達建議的不可逆邊界。StableOps 會按鏈應用對應的確認與最終確定規則，因此帳本服務不需要為每條網路編寫硬編碼區塊數的條件分支。穩定幣支付確認指南解釋了為什麼確認深度與最終確定是兩個不同的業務決策。

3. 在同一事務中完成驗籤、去重和入帳

一次成功的網路投遞本身不能證明客戶餘額已經更新。處理程序應使用未經修改的原始請求正文驗籤，要求存在 X-Event-Id，並在同一個資料庫事務中提交事件收件記錄和帳本分錄。

type FinalizedDeposit = {
  eventId: string
  paymentOrderId: string
  depositId: string
  userId: string
  amount: string
  asset: string
}

async function creditFinalizedDeposit(input: FinalizedDeposit) {
  await db.$transaction(async (tx) => {
    const accepted = await tx.processedEvents.createMany({
      data: { eventId: input.eventId, eventType: 'payment.finalized' },
      skipDuplicates: true,
    })

    if (accepted.count === 0) return

    const deposit = await tx.deposits.findUniqueOrThrow({
      where: { id: input.depositId },
    })

    if (deposit.stableopsOrderId !== input.paymentOrderId) {
      throw new Error('付款訂單不屬於這筆充值')
    }

    await tx.ledgerEntries.create({
      data: {
        uniqueKey: `deposit:${input.depositId}`,
        userId: input.userId,
        asset: input.asset,
        amount: input.amount,
        direction: 'credit',
      },
    })

    await tx.deposits.update({
      where: { id: input.depositId },
      data: { status: 'credited', creditedAt: new Date() },
    })
  })
}

事件號防止網路重試或人工重放的投遞被處理兩次。帳本分錄上獨立的 uniqueKey 則保護最終資金結果，即使兩條不同的應用路徑都嘗試給同一筆充值入帳，也只能成功一次。兩項約束都應位於資料庫中；記憶體裡的“已經處理”判斷既保護不了多個程序，也無法跨越程序崩潰。

真實的處理程序應根據已儲存的付款訂單號或經過驗籤的事件欄位找到充值記錄，並在入帳前把使用者、充值編號、金額和資產與已儲存的意圖逐一比較。metadata 適合提供路由上下文，但不能成為唯一的資金控制條件。

過期與遲到充值需要獨立的異常通道

如果 expiresAt 之前沒有檢測到精確匹配的轉帳，訂單會進入 expired，候選地址也會被釋放。介面應關閉這次嘗試並提供新的充值入口，不要繼續展示舊地址。

過期後到達的轉帳不能讓原訂單復活。因為地址可能已經被複用，營運人員必須結合交易雜湊、鏈、資產、金額、時間戳與地址分配歷史進行調查。如果資金真實存在且受平台控制，應把人工入帳或退款記錄成一筆獨立、經過審批的帳本操作；不要把過期訂單改寫成已經最終完成。

同一條異常通道還應處理錯誤金額、錯誤資產與不支援的網路。少付、多付或轉錯網路提供了這些場景的營運決策表。

每天核對事件流與帳本

Webhook 是低延遲路徑，但不應是唯一審計路徑。網路超時可能觸發投遞重試，端點可能暫時不可用，任務也可能在事件收件事務提交後失敗。每天執行一次任務，比較以下記錄：

1. 本地充值意圖與已經入帳的帳本分錄；
2. StableOps 付款訂單及其終態；
3. 已驗籤的 payment.finalized 收件事件與投遞歷史；
4. 調查異常時，把儲存的交易引用與規範鏈記錄核對。

每個遠端最終完成訂單都應該對應一筆本地充值、一條已接受事件和一筆帳本入帳。每筆帳本入帳都應該能夠追溯到本地充值、StableOps 訂單、事件號、資產與金額。異常必須持續保持待處理狀態，直到指定營運人員記錄解決結果。

這條恢復路徑對充值尤其重要，因為“Webhook 端點返回了 2xx”並不是帳本斷言。完整的加密貨幣支付對帳流程包含每日核對、月末控制、投遞重放與轉帳證據儲存。

上線核對清單

• 要求客戶在建立付款訂單前選擇充值金額。
• 儲存本地充值編號，並由它派生 merchantOrderId 和冪等鍵。
• 為每條鏈匯入足以覆蓋峰值有效充值的單次使用地址，並監控儲備水位。
• 原樣展示 order.amount、order.expiresAt 以及客戶選中的鏈、資產和地址。
• 在 detected 和 confirmed 階段禁止交易與提現，只在驗籤後的 payment.finalized 入帳。
• 分別對 X-Event-Id 和充值帳本分錄施加唯一約束。
• 關閉過期嘗試，停止展示已經釋放的地址，把遲到或不匹配轉帳送入人工複核。
• 每天核對最終完成訂單、已接受事件與帳本入帳。
• 私鑰只儲存在平台的錢包或託管系統中，絕不寫入 StableOps 後設資料或應用日誌。

常見問題

交易平台應該為每名使用者還是每筆充值分配一個地址？

按充值意圖建立的流程，適合為每個有效付款訂單使用單次地址候選。這樣可以給每次嘗試提供明確的歸屬視窗，又不會讓地址成為永久使用者身份。如果託管架構必須使用永久使用者地址，仍然需要鏈上監控、最終確定、重複保護和對帳；地址本身不能代替這些控制。

什麼時候可以讓客戶使用充值餘額？

後端驗籤並去重 payment.finalized，再以原子方式寫入帳本後。payment.detected 和 payment.confirmed 適合展示進度，但在這兩個狀態開放交易或提現，就意味著平台主動承擔鏈重組風險，而這種風險對交易產品尤其昂貴。

客戶在訂單過期後充值怎麼辦？

舊訂單應繼續保持過期狀態，地址也可能已經被釋放。任何新付款都應先建立新的充值請求，再單獨調查遲到轉帳。如果決定人工入帳或退款，應保留原訂單，並新增可審計的異常分錄，不要修改支付歷史。

建置第一條充值鏈路

先按照交易充值監控指南完成端到端接入，再閱讀付款訂單瞭解精確匹配與地址分配。在沙盒中讓一筆充值走到 finalized，重放它的 Webhook，並證明客戶帳本只增加一次餘額，然後再增加下一條網路。