Skip to main content

SDK v3.3.0 — Real x402 v2 + Smart Wallet Permit2

· 3 min read
AGIRAILS Core Team

@agirails/sdk@3.3.0 ships real x402 v2 protocol support — the on-the-wire shape Coinbase's facilitator actually expects. Plus a seller-side server module and Smart Wallet Permit2 batched payment, verified live on Base Sepolia.

Install​

npm install @agirails/sdk@3.3.0

Buyer-side x402 v2​

Earlier X402Adapter versions implemented an AGIRAILS-native shape that didn't interoperate with the public Coinbase facilitator. 3.3.0 rewrites the buyer flow to the actual x402 v2 spec:

// HTTPS endpoint? Auto-routed to x402 v2.
await client.pay({
  to: 'https://api.example.com/translate?text=hello',
  amount: '0.10',
});
// 1. GET endpoint → 402 Payment Required + accepts[]
// 2. Buyer constructs PaymentPayload per spec
// 3. POST endpoint with X-PAYMENT header
// 4. Receives X-PAYMENT-RESPONSE with settlement proof

Seller-side server module​

New subpath export @agirails/sdk/server lets you BE an x402 server, not just a buyer:

import { createX402Handler } from '@agirails/sdk/server';

const handler = createX402Handler({
  price: { amount: '0.10', currency: 'USDC' },
  payTo: '0xMyAgent...',
  network: 'base-sepolia',
  asset: 'USDC',
});

// Wire into Express, Next.js, Cloud Function — anywhere
app.post('/translate', handler.middleware, async (req, res) => {
  // req.x402.settled === true here
  res.json({ translation: '...' });
});

The handler implements the full x402 server protocol: 402 challenge generation, payment payload verification (signature recovery, asset allowlist, amount check, on-chain allowance simulation, facilitator settlement), and structured response with X-PAYMENT-RESPONSE.

Smart Wallet Permit2​

Buyers using Smart Wallets now batch the approve + transfer + settle sequence into a single ERC-4337 userOp via Permit2. Live E2E verified on Base Sepolia (commit 2452c6c).

actp init x402 seller scaffold​

actp init now offers an x402 seller template alongside ACTP earner / buyer / both. Generates a working Express server with a paywalled endpoint, ready to deploy to Vercel/Railway/Hetzner.

RPC-level event filtering​

onTransactionCreated event subscriptions are now filtered at the RPC level by requester / provider address before they reach the SDK. Previously the SDK pulled all TransactionCreated events and filtered locally — wasteful on chains with high tx volume. Now: the filter goes into the eth_newFilter call itself.

Security audit rounds 4-6​

This release went through three more audit rounds, visible in the git log under security(x402): audit round N:

  • Round 4 — P1/P2 hardening across buyer, seller, client
  • Round 5 — EOA sort, content-type, getStatus catch, price zero
  • Round 6 — asset null bypass, getStatus restructure, facilitator default

Deprecated​

X402Relay and X402FeeBreakdown are now marked legacy. The original AGIRAILS-side relay was useful when the public facilitator had availability gaps; with Coinbase's mainnet facilitator stable since February, we're consolidating on the public path. Existing X402Relay deployments continue to work — no new features.

Resources​