Credits 与充值

使用 write Token 请求一份充值草稿。付款前先从 pricing 读取当前最低金额、各资产汇率、可用性、奖励和上限。示例金额至少为 10,000 Credits，且绝不低于本实例配置的最低值。Credits 以 USD 锚定；资产金额是报价，不是固定值。草稿是一条支付指令，不是 Credits 入账。

curl -X POST 'https://ftso.app/api/x402/topup' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: topup_20260930_001' \
  -d '{"credits":10000,"asset":"FBEST"}'
# asset: FBEST | WFLR | FXRP | FLR | XRP

草稿返回 PaymentRouter 地址、asset、amountRaw、deadline、signedBy、typedData 和 signature。FXRP 使用六位小数；不要把它当作 18 位小数的代币处理。根据公开配置核对预期的 Router 和 Treasury，读取 settlementSigner()，并以密码学方式验证 EIP-712 签名。仅比较 signedBy 并不能验证签名。在批准并调用 pay() 之前，确认 buyer、asset、amount、链、deadline、feeBps=0 和 mode=0。

// draft is response.topup; router and token are viem contract instances.
// Verify the complete authorization before approval or payment.
const m = draft.typedData.message;
await token.write.approve([draft.routerAddress, BigInt(draft.amountRaw)]);
const txHash = await router.write.pay([
  { ...m, amount: BigInt(m.amount), deadline: BigInt(m.deadline), nonce: m.nonce },
  draft.signature,
]);

curl -X POST 'https://ftso.app/api/x402/topup/HANDLE/confirm' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"txHash":"0xPAY_TRANSACTION_HASH"}'

确认会在入账前验证付款。仅凭交易哈希不能证明充值已付款。Router 转移已授权的金额；重复确认不会两次授予 Credits。

在链 14 上将草稿中的 amountWei 发送到 payTo，并携带其精确的 32 字节 dataHex handle。无需代币授权。然后确认交易哈希。Credits 取决于实际到账价值，向下取整并受配置的上限限制。

await wallet.sendTransaction({
  to: draft.payTo,
  value: BigInt(draft.amountWei),
  data: draft.dataHex,
  chainId: 14,
});

使用返回的 XRPL 地址和 destinationTag，以及 amountDrops。Destination Tag 将付款分配到正确的充值。使用 read Token 轮询状态端点；Worker 会异步为经过验证的到账付款入账。没有保证的完成时间。可选的 FDC 认证在入账之后进行，不是入账的前提。verifiedByFdc 可能保持为 false。

curl 'https://ftso.app/api/x402/topup/HANDLE' \
  -H 'authorization: Bearer fbx_READ_TOKEN'

遵守草稿的 deadline。逾期的按比例 FLR/XRP 付款使用冻结汇率与当前汇率中较低者；没有当前价格时 Worker 会等待。每笔充值的上限限制超额付款的入账；超过某资产的持仓上限会暂停新的草稿。切勿在没有 Router 订单、dataHex 或 destinationTag 的情况下付款：应用无法可靠地归属这样的付款。

使用 Bearer 的订阅购买需要一个由 8–128 个字母、数字、下划线或连字符组成的 Idempotency-Key。该请求头也支持用于创建 Watch、充值草稿、创建收件人和通道 PUT。超时后请使用相同的 key 和请求体重试。最终响应保留 24 小时；更改的请求体返回 409 idempotency_key_reused。活跃的租约返回 409 idempotency_in_progress 并带有 Retry-After。可重试的失败会释放该 key；过期的草稿返回 410 draft_expired。重放计入速率限制。返回的密钥可在 24 小时内通过同一钱包的重放恢复。

赚取的 Credits 与购买的 Credits 分开核算。现有的 FBEST 兑换使用申请、管理员审批以及在 ConversionVault 上的钱包 Claim；自动支付尚未实现。用户流程参见 Credits。

当前生效的汇率、可用性和配置请使用 /api/x402/pricing。本部分读取本应用实例的配置；它不会查询 Treasury 或远程服务器。

• 最低充值 Credits: 10000
• 每 1,000 Credits 的 USD: 1

• FBEST: 每笔充值上限: 未配置上限; Treasury 持仓阈值: 未配置上限.
• WFLR: 每笔充值上限: 未配置上限; Treasury 持仓阈值: 未配置上限.
• FXRP: 每笔充值上限: 1000; Treasury 持仓阈值: 5000.
• FLR: 每笔充值上限: 未配置上限; Treasury 持仓阈值: 未配置上限.
• XRP: 每笔充值上限: 1000; Treasury 持仓阈值: 5000.