We Built @ai-sdk/x402 — A Community Package That Lets Vercel AI SDK Agents Pay for API Calls in USDC

"We won't publish an @ai-sdk/x402 package at this point, but it would make a great community package! Happy to list it in our docs once you build it." — gr2m, Vercel

That was the reply on vercel/ai#18293 when the community asked whether the Vercel AI SDK would natively support x402 — the HTTP 402 Payment Required protocol that lets AI agents pay for API calls in USDC at request time.

So we built it.

ai-sdk-x402 is a community npm package that wraps any x402-protected API endpoint as a Vercel AI SDK tool. An agent using generateText() or streamText() can call x402 endpoints the same way it calls any other tool — and payment is handled transparently.

What It Looks Like

Wrap an x402 endpoint as an AI SDK tool in three lines:

import { x402Tool } from 'ai-sdk-x402';
import { generateText } from 'ai';

const tools = {
  getTime: x402Tool({
    endpoint: 'https://minia2a.uk/x402/time',
    description: 'Get the current UTC time with millisecond precision',
  }),
};

const { text } = await generateText({
  model,
  tools,
  prompt: 'What time is it?',
});

That's it. No API key. No subscription. No wallet setup required for the first 5 calls — x402 endpoints support anonymous trials. When trials run out, the package handles the 402 → pay → retry flow automatically.

The 402 Flow, Handled

The magic of x402 is its simplicity: when an agent calls an endpoint without sufficient payment, the server returns HTTP 402 with payment details in the response body. The client pays and retries. The whole cycle takes under 2 seconds on Base L2.

Our package handles this transparently:

Agent calls endpoint
     │
     ▼
GET /x402/endpoint
     │
┌────┴────┐
│         │
200       402 Payment Required
│         │
▼         ▼
Return   Extract payment details
result   from 402 response
         │
         ▼
     POST /api/v1/pay
     (USDC on Base, ~$0.0001 gas)
         │
         ▼
     Retry GET with wallet
         │
         ▼
       200 → Return result

// Zero config — just set your wallet in env
// X402_WALLET=0xYourAddress

import { x402 } from 'ai-sdk-x402';

const time = await x402.call('https://minia2a.uk/x402/time');
console.log(time.result.utc);  // "2026-08-09T13:25:59.881Z"
console.log(time.trial);        // { remaining: 4, max: 5 }

Why This Matters

The agent economy has a bootstrap problem: agents need pre-funded wallets, but funding wallets requires humans (captcha + gas fees). This breaks the "fully autonomous agent" vision.

Trial-first discovery solves this: an agent can evaluate a service without a wallet, using anonymous IP-based trials. If the service is useful, the developer registers and gets credits. Payment only kicks in after the agent proves the service is worth paying for.

This is the opposite of the pay-first model that most agent marketplaces use — and it's why free trials are the missing layer in the agent API economy.

What's in the Box

The package ships with:

• x402Tool(config) — wrap any x402 endpoint as an AI SDK tool
• x402Tools(definitions) — batch-create multiple tools at once
• X402Client — standalone client with full payment flow
• x402.call() — one-liner convenience with default config
• x402.discover() — list available services from a marketplace
• Full TypeScript types — including X402Response<T>, X402Error with structured error codes
• Zod parameter support — define typed tool parameters that map to query params

Multiple Tools, One Declaration

import { x402Tools } from 'ai-sdk-x402';

const tools = x402Tools({
  getTime:   { endpoint: 'https://minia2a.uk/x402/time', description: 'Get UTC time' },
  searchWeb: { endpoint: 'https://minia2a.uk/x402/web-search', description: 'Search the web' },
  getGas:    { endpoint: 'https://minia2a.uk/x402/gas', description: 'Get Ethereum gas price' },
  getPrice:  { endpoint: 'https://minia2a.uk/x402/crypto-price', description: 'Get crypto price' },
});

// 4 x402-backed tools, zero API keys, zero subscriptions
const { text } = await generateText({ model, tools, prompt: '...' });

Error Handling That Makes Sense

import { X402Error } from 'ai-sdk-x402';

try {
  await x402.call('https://minia2a.uk/x402/some-endpoint');
} catch (err) {
  if (err instanceof X402Error) {
    // err.code: 'TRIALS_EXHAUSTED' | 'WALLET_REQUIRED' | 'PAYMENT_FAILED' | ...
    // err.retryable: true for timeout/network, false for terminal
    if (err.code === 'TRIALS_EXHAUSTED') {
      // Prompt user to register
    }
  }
}

What This Means for the Ecosystem

Vercel's AI SDK is one of the most widely used agent frameworks. Adding x402 payment support as a community package means:

1. Agent developers can monetize their tools without building payment infrastructure themselves. Wrap your API in x402, publish it to a marketplace, and agents pay per call in USDC.
2. Tool discovery becomes commerce. Instead of hoping someone finds your API, list it where agents can discover it, try it for free, and pay when it's useful.
3. The M2M economy gets a distribution channel. Every Vercel AI SDK user is now one npm install away from calling x402-protected APIs.

What's Next

The package is functional today with any x402-compatible marketplace. We're working on:

• Multi-facilitator support — route payments through Coinbase CDP, Cloudflare Wallets, or OSL AgentPay
• Receipt verification — on-chain proof that a payment was settled before calling the endpoint
• Auto-discovery — x402.discover() returns live, verified endpoints with uptime and latency stats
• Streaming support — for x402 endpoints that return streaming responses (LLM inference, real-time data)

The package is MIT-licensed and open for contributions at github.com/minia2a/ai-sdk-x402.