An x402 client SDK + middleware for Sui (testnet, feedback wanted)

SDK
,
1

Stripe shipped Machine Payments in Feb 2026. AWS made CloudFront/WAF x402-aware in June. Both use the same open Linux Foundation spec, x402. Sui already has an exact scheme in that spec and one solid open-source facilitator (DrVelvetFog/sui-x402-facilitator, non-custodial, live on mainnet and testnet).

There’s already a marketplace-specific SDK on Sui: @t2000/sui-x402 and @t2000/serve (github.com/mission69b/t2000), live on Sui mainnet, 23 stars, about 10k npm downloads a month. It’s a different design: v1-style X-PAYMENT/X-PAYMENT-RESPONSE headers with a custom extra.suimpp extension, the seller verifies and settles payments itself with no facilitator, the handler runs before settlement, it’s Next.js first, and it’s tied to their marketplace with a 5% fee on jobs. (There’s also @altaga/x402-sui, sponsored transactions, about 145 downloads a month.) What’s been missing is the standards-track option: the actual x402 v2 wire format and facilitator model the spec, and the foundation’s own EVM implementations, use. That’s what I built. One thing they have that I don’t yet: gasless payments. Planned.

What’s here today

  • @sui-x402/core: Zod schemas derived from captured facilitator traffic, the header codec, reason codes with retry hints, and the seller core every adapter wraps.
  • @sui-x402/payer-sui: the agent side. A fetch() that handles a 402 itself: gRPC coin discovery, transaction build with a simulated gas budget, a self-check on the simulated balance change, signing, and a strict no-double-pay rule. Testnet only by default, per-asset spend caps.
  • @sui-x402/hono, @sui-x402/express, @sui-x402/next: seller middleware. Strict mode settles before your handler runs; a facilitator outage is a 503 with Retry-After, never free content. One conformance suite runs against all three adapters.
  • Runnable examples for each framework, a Dockerfile plus Fly and Railway config for self-hosting the facilitator, and 349 tests.

It has moved real money on testnet: ten $0.01 USDC payments settled end to end through the reference facilitator (every push to the repo settles another through CI), verified on chain (for example digest GE85dg3wNUdfRKJpFW9bBz2qkk4qgvgihWxMrFzDfc4T, checkable on SuiVision).

A paid route, as shipped:

import { Hono } from "hono";
import { x402 } from "@sui-x402/hono";

const app = new Hono();
app.use("/paid/*", x402({
  payTo: "0xYOUR_SUI_ADDRESS",
  amount: "10000",                                                                          // 0.01 USDC
  asset: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC", // testnet USDC
  network: "sui:testnet",
  facilitator: "https://your-facilitator.example",
}));
app.get("/paid/quote", (c) => c.json({ symbol: "SUI", quote: "1.00" }));

And the paying side:

const payer = new SuiX402Payer({ client, signer: ed25519SignerFromEnv() });
const { response, receipt } = await payer.fetchWithReceipt("https://api.example/paid/quote");

What it settles through: the existing open-source reference facilitator, self-hosted (Fly/Railway config and a runbook are in the repo). This SDK doesn’t run its own facilitator and never touches custody: it only builds and signs the payer’s transaction and relays bytes unmodified.

Status: testnet only, v0.1.0 on npm. Nothing has touched mainnet; mainnet is behind explicit opt-ins on both sides.

Three asks

  1. Feedback on the API shape (payer.fetch(), middleware config) while it’s early enough to change. Repo: github.com/yannickrocks/sui-x402.
  2. Sellers willing to pilot a paid endpoint on testnet now. Ten lines and a funded test wallet are all it takes.
  3. The testnet network id. The x402 Sui scheme spec only shows sui:mainnet in its example payload; no testnet identifier is defined. The reference facilitator and this SDK have both independently landed on sui:testnet (CAIP-2-style) as a stopgap. I’d like to propose formalizing it upstream. Does anyone know if there’s an existing spec issue tracking this, or should I open one?

Repo: github.com/yannickrocks/sui-x402 · npm org: sui-x402 · facilitator (testnet): facilitator-production-1e79.up.railway.app

1 Like