x402 Trinity MCP server

x402-trinity

A drop-in fetch replacement that lets an AI agent pay for things by itself — with hard spending limits, no hosted wallet service, and no changes to the agent's own code.

Zero runtime dependencies. 7 KB gzipped. Buyer and seller in TypeScript; buyer in Python.

npm install x402-trinity

Why

When an agent hits a paid resource it gets 402 Payment Required. Without something to handle that, the request simply fails.

x402-trinity handles it: reads the challenge, checks it against limits you set, signs, retries. All of it locally — no hosted wallet service, no third-party API, and the key never leaves your process.

Gas exists but the payer doesn't pay it — under EIP-3009 the facilitator submits the transfer, so an agent's wallet only ever needs USDC.

Buy (agent pays for things)

import { createX402Fetch } from 'x402-trinity';

const x402Fetch = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,   // never hardcode
  policy: {
    maxAmountPerRequest: '5000',              // 0.005 USDC max per call  (REQUIRED)
    totalBudget: '1000000',                   // 1.00 USDC lifetime       (REQUIRED)
    allowHosts: ['api.example.com'],
    allowPayTo: ['0x...'],
  },
});

const r = await x402Fetch('https://api.example.com/data');   // 402 handled, returns 200

Or patch the global so unmodified code pays automatically:

import { installX402 } from 'x402-trinity';
const uninstall = installX402(cfg);   // globalThis.fetch now pays 402s

Confirm which wallet will pay before funding anything:

X402_PRIVATE_KEY=0x... npx x402-trinity-whoami

It prints the address and its balance on every chain, and never prints the key. If the address is not the wallet you meant, stop before sending anything.

Sell (charge for a resource, get paid)

import { createX402Seller } from 'x402-trinity/seller';
import { createFileNonceStore } from 'x402-trinity/budget-file';

const seller = createX402Seller({
  payTo: '0xYourWallet',      // 100% of every payment lands here
  price: '10000',             // 0.01 USDC, atomic units
  network: 'base',
  facilitator: 'https://your-facilitator.example',   // REQUIRED — no default exists
  nonceStore: createFileNonceStore('./.x402-nonces.json'),  // REQUIRED — see below
});

// in any fetch-style handler:
const gate = await seller.guard(request);
if (gate.response) return gate.response;          // unpaid or refused — hand back the 402
return new Response(yourData, { headers: seller.receiptHeader(gate.settlement) });

Both required fields are deliberate. There is no default facilitator because settling is someone's real money and guessing an endpoint is not a default. And the replay guard has to outlive the process: an in-memory one forgets every settled payment on restart, so a buyer could re-present a spent authorization and get the resource again for free. The constructor throws rather than let either be implicit.

The seller never holds a private key and never touches funds. It quotes a price and asks a facilitator to verify and settle; money moves buyer → you directly on-chain.

This release ships Base + USDC only. Any other EVM chain works through customChains;

your address is the same on all of them.

What it does

Shortened. The full README is on GitHub.