快速開始

用十分鐘完成第一筆 StableOps 穩定幣測試支付：建立冪等付款訂單，讀取可接受的網路與資產，透過錢包傳送測試網代幣，驗證簽名 Webhook 並查詢最終狀態；同時瞭解託管結帳頁和自建支付頁面兩種接入路徑。

還有一種更簡單的整合方法

本快速開始用錢包 SDK 自己搭建支付體驗。如果你不想自建支付頁，可以用託管 結帳頁：在後端建立會話，把付款方跳轉到 StableOps 託管頁面，錢包支付、手動/自動選網、即時狀態跟蹤都已內建。兩條路徑都走同一套訂單與 Webhook。

1. 安裝 SDK

pnpm add @stableops/api-sdk @stableops/wallet-sdk

API SDK 純 TypeScript 實現，執行時只依賴 Node crypto。錢包 SDK 用於瀏覽器端呼叫使用者的錢包發起鏈上轉帳。

2. 設定伺服器端用戶端

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

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

不要把 STABLEOPS_API_KEY 暴露給瀏覽器。建立付款單、查詢訂單等商戶 API 呼叫應放在你的伺服器端完成。

3. 在 Dashboard 完成準備

建立第一筆訂單前，先在 Dashboard 裡完成兩件事：

匯入收款地址：匯入你接受的鏈上收款地址。StableOps 會從地址池分配一個地址給付款單。
註冊 Webhook 端點：填寫你的回呼 URL，例如 https://your-app.example.com/hooks/stableops。

Webhook secret 只會在建立或輪換時展示，請儲存到伺服器端環境變數，例如 STABLEOPS_WEBHOOK_SECRET。需要自動化時，也可以使用收款地址 API 與 Webhook 端點 API。

4. 建立付款單

const order = await client.paymentOrders.create(
  {
    merchantOrderId: 'sub_89231_2026_06',
    amount: '49.00',
    acceptedAssets: [
      { chain: 'base-sepolia', asset: 'USDC' },
      { chain: 'ethereum-sepolia', asset: 'USDC' },
    ],
    // 30 分鐘後未支付自動過期，訂單狀態推進到 expired 並釋放收款地址。
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    metadata: { customerId: 'cus_9821', plan: 'pro_monthly' },
  },
  { idempotencyKey: crypto.randomUUID() },
)

console.log(order.paymentInstructions)
// [
//   { chain: 'base-sepolia', asset: 'USDC', address: '0x...' },
//   { chain: 'ethereum-sepolia', asset: 'USDC', address: '0x...' },
// ]

把訂單 id、金額和 paymentInstructions 返回給你的前端即可；不要把 API key 一起下發。

5. 呼叫錢包 SDK 支付

前端拿到伺服器端建立的訂單後，用錢包 SDK 呼叫瀏覽器錢包發起鏈上轉帳：

import {
  getInjectedWalletProviders,
  selectWalletPaymentInstruction,
  sendWalletPayment,
} from '@stableops/wallet-sdk'

const { instruction, provider } = selectWalletPaymentInstruction(
  order.paymentInstructions,
  getInjectedWalletProviders(),
)

const sent = await sendWalletPayment({
  provider,
  amount: order.amount,
  instruction,
})

console.log(sent.txHash)

上面的例子會按目前瀏覽器已有的錢包，從候選鏈中選出一條可支付指令。TRON、Solana 或自定義多鏈選擇器可以參考錢包 SDK。轉帳上鍊後，StableOps 的 scanner 會按訂單收款地址匹配入金，並在狀態變化時投遞 Webhook。

錢包 SDK 只是為了方便，並非必須。付款方可以用任意方式完成這筆轉帳：手動從MetaMask / Phantom / TronLink 等錢包傳送、從交易所提幣、或用其他後端指令碼，只要把訂單金額（order.amount）轉到對應鏈的 paymentInstructions[].address 即可。scanner 一律按 (鏈, 收款地址) 匹配入金，與資金來源無關。

6. 驗證簽名

每一次投遞都帶 X-Product-Signature: t=…,v1=…。在解析 body 之前呼叫 SDK 的常量時間驗籤助手：

import { verifySignature } from '@stableops/api-sdk/webhooks'

export async function POST(req: Request) {
  const rawBody = await req.text()
  const result = verifySignature({
    secrets: [process.env.STABLEOPS_WEBHOOK_SECRET!],
    header: req.headers.get('x-product-signature') ?? undefined,
    rawBody,
  })
  if (!result.ok) {
    return new Response(`invalid: ${result.reason}`, { status: 400 })
  }
  const event = JSON.parse(rawBody)
  // 用 event.data.payment_order_id 與自家帳本對帳即可。
  return new Response('ok')
}

你剛剛完成

在 Dashboard 匯入了收款地址並註冊了 Webhook 端點。
建立了一筆帶具體收款地址的訂單。
透過錢包 SDK 發起了一筆鏈上支付。
端到端驗證了一次簽名的 Webhook 投遞。

下一步：閱讀概念 → 確認理解狀態機；或跳轉到 API 參考。