TypeScript API SDK

安装

pnpm add @stableops/api-sdk

默认 API Client 面向 Node 18+ 与提供全局 fetch、AbortController、 crypto.randomUUID 的 Edge Runtime。Webhook 验签与 Mock Server 是 Node.js 专用入口。

想看可运行的完整示例？

Playground 在浏览器里串起「建单 → 钱包支付 → 确认 → finalized」全流程，并附带可阅读的源码。

配置

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

const client = new StableOps({
  apiKey: process.env.STABLEOPS_API_KEY!,
  // 可选。注入自定义 fetch（msw、undici、edge fetch 等）。
  fetch: globalThis.fetch,
})

支付订单

const order = await client.paymentOrders.create(
  {
    merchantOrderId: 'sub_89231_2026_06',
    amount: '49.00',
    acceptedAssets: [
      { chain: 'base', asset: 'USDC' },
      { chain: 'tron', asset: 'USDT' },
    ],
    // 30 分钟后未支付自动过期，订单进入 expired 并释放地址。
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
  },
  { idempotencyKey: crypto.randomUUID() },
)

await client.paymentOrders.retrieve(order.id)
await client.paymentOrders.list({ status: 'detected', limit: 50 })
await client.paymentOrders.cancel(order.id)

paymentOrders.create 始终需要 idempotencyKey。建议用订单 id 派生的 UUID， worker 重试时落到同一记录。amount 是人类可读的十进制字符串（例如 "49.00"），应保持字符串形式或使用十进制定点库处理，不要直接用 Number(amount)。

可选 amountMode: 'auto' 让服务端把金额微调到唯一（SHARED 地址免手动错开金额）。 settlementAsset 由服务端按 acceptedAssets 推导，创建时无需传入。

Checkout Sessions（托管收银台）

checkoutSessions.create 返回一个托管支付页（WalletConnect），把用户跳转到 session.url 即可。

const session = await client.checkoutSessions.create(
  {
    merchantOrderId: 'sub_89231_2026_06',
    amount: '49.00',
    acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
    title: 'Pro 套餐',
    successUrl: 'https://your-app.example.com/pay/success',
    cancelUrl: 'https://your-app.example.com/pay/cancel',
  },
  { idempotencyKey: crypto.randomUUID() },
)

console.log(session.url) // 跳转用户到此链接完成支付

Webhook 端点

const endpoint = await client.webhooks.createEndpoint({
  url: 'https://your-app.example.com/hooks/stableops',
  enabledEvents: ['payment.detected', 'payment.confirmed', 'payment.finalized'],
})

// endpoint.secret 只在创建/轮换时出现一次，请妥善保存。
await client.webhooks.rotateSecret(endpoint.id)

投递与重放：client.webhooks.listDeliveries(...)、replay(endpointId, eventId)、 replayDelivery(deliveryId)、replayDeadLetters({ endpointId, limit })。

错误

所有非 2xx 都会抛 StableOpsError，带 .status / .code / .message / .details。

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

try {
  await client.paymentOrders.create(input, { idempotencyKey: key })
} catch (err) {
  if (err instanceof StableOpsError && err.status === 409) {
    // Idempotency-key 被相同 key 不同 body 复用
  }
  throw err
}

本地 Mock 服务

SDK 自带一个进程内 Mock，适合契约测试与文档示例：

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

const mock = new MockServer()
const { url } = await mock.listen()

const client = new StableOps({ baseUrl: url })
const order = await client.paymentOrders.create(
  {
    merchantOrderId: 'mock-order-1',
    amount: '49.00',
    acceptedAssets: [{ chain: 'base', asset: 'USDC' }],
    expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
  },
  { idempotencyKey: 'mock-order-1' },
)

const endpoint = await client.webhooks.createEndpoint({
  url: 'https://example.com/webhooks/stableops',
  enabledEvents: ['payment.detected'],
})

const fixture = mock.buildSignedFixture(endpoint.id, 'payment.detected', {
  id: order.id,
})
verifySignature({
  secret: fixture.secret,
  header: fixture.header,
  rawBody: fixture.rawBody,
})

await mock.close()

Mock 只实现 SDK 契约测试所需的最小接口：payment orders、webhook endpoints、以及签名 fixture 构造。

安装

配置

支付订单

Checkout Sessions（托管收银台）

Webhook 端点

错误

本地 Mock 服务

本页内容