@shroud-fi/x402

Stealth-addressed HTTP 402 payments for AI agents. EIP-3009 settlement into one-time addresses.

npm i @shroud-fi/x402 viem

What it does

@shroud-fi/x402 wraps the HTTP 402 protocol with ShroudFi's stealth-address layer. Any endpoint can issue a 402 challenge, and any agent can pay it — but the EIP-3009 settlement lands at a fresh, one-time stealth address derived from the seller's meta-address.

Call the same /pay/signal URL ten times — get ten unlinkable destinations. The customer graph never forms on-chain.

Supported assets

| Asset | Chain | Decimals | Why | |---|---|---|---| | USDC | Base mainnet | 6 | Circle-issued, EIP-3009 native | | EURC | Base mainnet | 6 | Circle-issued (EUR), EIP-3009 native | | USDC | Base Sepolia | 6 | testnet |

USDT and DAI are deliberately not supported at the x402 layer — they don't implement EIP-3009 transferWithAuthorization. Adding them would require a separate settlement primitive (USDT: plain approve+transferFrom; DAI: DAI-style permit). Tracked for a later release.

Why it matters

A naive agent-to-agent payment exposes the buyer's main wallet, the seller's main wallet, and a verifiable on-chain link between them. After enough calls, the entire customer graph of an agentic service is publicly reconstructable. Stealth-addressed x402 closes that.

Quick start (client)

import { payX402 } from '@shroud-fi/x402';

const signal = await payX402({
  agent,                                            // a ShroudAgent from @shroud-fi/agent-runtime
  url: 'https://api.alpha.xyz/signal',
  maxPriceUsdcAtomic: 10_000n,                      // 0.01 USDC
});

console.log(signal); // unlocked response body

Quick start (server)

import { createX402Server } from '@shroud-fi/x402';

const x402 = createX402Server({
  resource: 'https://api.alpha.xyz/signal',
  priceUsdcAtomic: 10_000n,
  recipientMeta: 'st:base:0x024fa9bb…',
});

// In your Fastify / Express handler:
const payment = req.headers['x-payment'];
if (!payment) {
  return reply.code(402).send(await x402.challenge());
}
const verified = await x402.verify(payment);
if (!verified.ok) return reply.code(402).send({ error: verified.reason });
// payment OK — settle + serve content

Exports

| Symbol | Purpose | |---|---| | payX402(args) | One-shot client. Calls a URL, signs USDC if a 402 lands, retries with X-PAYMENT, returns the unlocked body. | | createX402Server(cfg) | Server-side primitives. Mint a 402 challenge or verify a payment payload. | | buildX402Payment(args) | Lower-level sign-only flow for custom HTTP machinery. |

Full API reference: shroudfi.live/sdk#x402

Facilitators

Settlement can run through an external x402 facilitator (which broadcasts the EIP-3009 tx and pays gas) or via your own settler EOA (skipFacilitator: true).

PayAI facilitator is supported out of the box (v0.1.2). The SDK speaks x402 v2 / CAIP-2 internally and translates to the facilitator's v1 / legacy-network wire format at the boundary via toFacilitatorRequest. Proven end-to-end on Base mainnet — a 0.01 USDC agent-to-agent payment settled to a one-time stealth address (tx 0x57d84d53…). PayAI pays the gas; the buyer needs only USDC, no ETH.

const x402 = createX402Server({
  transport, recipientMetaAddress, asset: USDC, chainId: 8453,
  defaultPriceAtomic: 10_000n,
  // facilitator defaults to PayAI free tier; omit to use it.
});
const v = await x402.verify({ signedPayload, challenge }); // verifies + settles via PayAI

Standards used

• HTTP 402 Payment Required + x402 extension (x402.org)
• EIP-3009 transferWithAuthorization for USDC + EURC settlement
• EIP-5564 / 6538 for stealth-address derivation

License

MIT — see LICENSE.

Part of the ShroudFi privacy SDK for AI agents on Base.