Credits and topups

Use a write token to request a topup draft. Read current minimum, per-asset rates, availability, bonus and caps from pricing before paying. The example amount is at least 10,000 credits and never below this instance’s configured minimum. Credits are USD-anchored; asset amounts are quoted, not fixed. A draft is an instruction, not a credit booking.

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

The draft returns the PaymentRouter address, asset, amountRaw, deadline, signedBy, typedData and signature. FXRP uses six decimals; do not treat it as an 18-decimal token. Verify the expected router and treasury against public configuration, read settlementSigner() and cryptographically verify the EIP-712 signature. Comparing signedBy alone does not verify a signature. Confirm buyer, asset, amount, chain, deadline, feeBps=0 and mode=0 before approving and calling pay().

// 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"}'

Confirmation verifies the payment before crediting. A transaction hash alone is not proof of a paid topup. The router transfers the authorized amount; a duplicate confirmation cannot grant credits twice.

Send the draft’s amountWei to payTo on chain 14, carrying its exact 32-byte dataHex handle. No token approval is needed. Then confirm the transaction hash. Credits depend on delivered value, rounded down and limited by configured caps.

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

Use the returned XRPL address and destinationTag, together with amountDrops. The destination tag assigns the payment to the correct topup. Poll the status endpoint with a read token; the worker credits a verified delivered payment asynchronously. There is no guaranteed completion time. Optional FDC attestation follows crediting and does not gate it. verifiedByFdc may remain false.

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

Respect the draft deadline. Late proportional FLR/XRP payments use the lower of the frozen and current rate; without a current price the worker waits. Per-topup caps limit credited overpayments; exceeding an asset holdings cap pauses new drafts. Never send without the router order, dataHex or destinationTag: the application cannot reliably attribute such a payment.

Bearer subscription purchases require an Idempotency-Key of 8–128 letters, digits, underscores or hyphens. The header is also supported for watch creation, topup drafts, recipient creation and channel PUT. Reuse the same key and body after a timeout. Final responses are retained for 24 hours; changed bodies return 409 idempotency_key_reused. An active lease returns 409 idempotency_in_progress with Retry-After. Retryable failures release the key; expired drafts return 410 draft_expired. Replays count toward rate limits. Returned secrets may be recoverable from a same-wallet replay for 24 hours.

Earned credits are accounted separately from purchased credits. The existing FBEST conversion uses a request, admin approval and a wallet claim on the ConversionVault; automated payout is not implemented. See Credits for the user workflow.

For currently active rates, availability and configuration use /api/x402/pricing. This section reads this application instance’s configuration; it does not query the treasury or a remote server.

• Minimum topup credits: 10000
• USD per 1,000 credits: 1

• FBEST: Per-topup maximum: No configured cap; Treasury holdings threshold: No configured cap.
• WFLR: Per-topup maximum: No configured cap; Treasury holdings threshold: No configured cap.
• FXRP: Per-topup maximum: 1000; Treasury holdings threshold: 5000.
• FLR: Per-topup maximum: No configured cap; Treasury holdings threshold: No configured cap.
• XRP: Per-topup maximum: 1000; Treasury holdings threshold: 5000.