x402-trinity-mcp
This server is an MCP tool server that gives an AI agent a wallet to interact with paid HTTP resources. It can check prices without paying, fetch resources while automatically paying if required (within operator-set limits), and report wallet status.
check_price: Inspect a URL to see if it is paywalled; if it returns HTTP 402, report the price, recipient, chain, and whether it is within configured spending limits — without spending money.
pay_and_fetch: Fetch any http(s) URL; if the resource demands payment, automatically pay from the configured wallet, but only when the payment is within the per-request cap, remaining lifetime budget, allowed hosts, and allowed chains. Non-paywalled resources are fetched for free. Supports custom HTTP method and response truncation.
wallet_status: Read-only status of the paying wallet: address, on-chain USDC balance, total spent, and remaining budget. Never moves money and never reveals the private key.
Safety constraints: The server refuses to start without required environment variables (private key, per-request max, total budget); limits are operator-set and cannot be raised by the model.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@x402-trinity-mcp Check the price of the paywalled report at api.example.com/report and fetch it if it's under my budget."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-trinityCopy-paste setup
A ready-made brief for your coding agent. Paste it in and it does the install, the wallet, your spending limits, the price check and the purchase — you just say what you are buying and what it may spend.
→ Standard Purchase Harness
Buying from a paid API, a dataset, a file, or another agent's service — anything that answers HTTP 402.
More setups, and a marketplace for you to earn for your products or buy from the marketplace, at x402trinity.com.
Related MCP server: agent-x402-paywall-mcp
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 200Or patch the global so unmodified code pays automatically:
import { installX402 } from 'x402-trinity';
const uninstall = installX402(cfg); // globalThis.fetch now pays 402sConfirm which wallet will pay before funding anything:
X402_PRIVATE_KEY=0x... npx x402-trinity-whoamiIt 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
Protocols | x402 v1 and v2, detected per response. Unknown versions and MPP challenges declined with a clear reason, never guessed |
Chains | Base mainnet + USDC, shipped as the default. Any other EVM chain via |
Networks | short names and CAIP-2 ( |
Custody |
|
Speed | 3.2 µs warm / 1.0 ms cold (TypeScript); 1.2 µs / 1.7 ms (Python) |
Runtime | auto-detects Cloudflare Workers and changes strategy; also Node, Bun, Deno |
Safety | mandatory caps, allowlists, never-pay-twice reconciliation, timing-hardened signing |
Another chain
Base is the default. The signing is chain-agnostic, so add whatever you need — including a testnet to rehearse on:
const fetch2 = createX402Fetch({
privateKey: process.env.X402_PRIVATE_KEY,
maxAmountPerRequest: '10000',
totalBudget: '100000',
customChains: {
'base-sepolia': { id: 84532, asset: '0x036cbd53842c5426634e7929541ec2318f3dcf7e', name: 'USDC', version: '2' },
},
});Verify the entry against the deployed contract first: call DOMAIN_SEPARATOR() and check it
equals what this library computes. A wrong name or version produces a signature that looks
valid and the contract rejects.
It deliberately will not
Broadcast to a chain · hold funds · need gas or an RPC · take a cut of a payment (structurally impossible — EIP-3009 has one recipient) · require a hosted signer · pay without limits · guess at a protocol it doesn't speak.
Safety — read this before real money
Caps are mandatory. maxAmountPerRequest and totalBudget have no defaults; the wrapper
refuses to construct without them. An auto-payer without limits is a money leak controlled by
whoever runs the server.
totalBudget alone is per-instance. It is an in-memory counter that resets on restart, on
a new client, and on every Cloudflare Worker isolate — which is per request. On mainnet that
turns a lifetime cap into a per-request cap. Mainnet therefore requires a durable
budgetStore, or an explicit acknowledgeEphemeralBudget: true:
import { createFileBudgetStore } from 'x402-trinity/budget-file';
createX402Fetch({
...,
budgetStore: createFileBudgetStore('./.x402-budget.json'), // survives restarts
});The key is in the process. That is the trade for having no hosted signer. Bound it:
use a dedicated wallet holding only what you would accept losing, set allowPayTo so an
exfiltrated key still cannot pay a stranger through this wrapper, and use remoteSign if you
need enclave-grade custody.
Timing hardening is hardening, not a proof. Secret scalars use blinding plus always-add-and-double, which cut the timing spread from 99.6% to 12% (Python: 99.9% → 1.1%). BigInt arithmetic is itself variable-time and no pure-JS implementation removes that.
MCP server — give an agent a wallet
MCP is how an assistant gets tools. This exposes three:
tool | |
| what a resource costs, without paying |
| fetch it, paying if it is within your limits |
| address, balance, spent, remaining |
{
"mcpServers": {
"x402-trinity": {
"command": "npx",
"args": ["-y", "x402-trinity-mcp"],
"env": {
"X402_PRIVATE_KEY": "0x...",
"X402_MAX_PER_REQUEST": "50000",
"X402_TOTAL_BUDGET": "1000000",
"X402_BUDGET_FILE": "./.x402-budget.json",
"X402_ALLOW_HOSTS": "api.example.com",
"X402_NETWORKS": "base"
}
}
}
}A model decides when these run. It cannot be reasoned with about budgets, and a
paywalled page can claim any price it likes. So the limits are not parameters the model can
set — they come from the environment, and the server refuses to start without
X402_PRIVATE_KEY, X402_MAX_PER_REQUEST and X402_TOTAL_BUDGET.
Set X402_BUDGET_FILE too, or the lifetime ceiling resets every restart. Set
X402_ALLOW_HOSTS and nothing else can be paid, however convincing the challenge looks.
Use a wallet holding only what you would accept losing.
Python
Same protocol, standard library only. Buyer only — to charge for a resource, use the TypeScript seller. Aimed at long-lived processes: on-body agents, robotics controllers, harvesting scripts.
from x402_trinity import X402Client, Policy
client = X402Client(
private_key=os.environ["X402_PRIVATE_KEY"],
policy=Policy(max_amount_per_request=5000, total_budget=1_000_000,
allow_hosts=["api.example.com"]),
)
body = client.urlopen("https://api.example.com/data").read()Or as a decorator, so payment-unaware code just works:
from x402_trinity import x402_telemetry
@x402_telemetry(private_key=KEY, policy=Policy(...))
def harvest():
return urllib.request.urlopen("https://sensor.local/v1/lidar").read()The warm path is 1.1 µs — a long-lived controller is warm after its first payment.
Development
npm install
npm run build # dist/*.js + *.min.js + *.d.tsesbuild, typescript and wrangler are dev dependencies only, used for building.
The shipped package has zero runtime dependencies.
License
Business Source License 1.1. The source is open to read, modify and use non-commercially; production use is granted except as a hosted or managed service offering its functionality to third parties. It converts to MIT on 2029-08-25. See LICENSE.
This software moves money — read the additional notice there, and set your spending caps.
Convenience fee: 0.1% per transaction and 1 cent every 100 transactions.
Available Tools
3 toolscheck_priceA
Look at what a paid resource costs WITHOUT paying for it. Fetches the URL, and if it answers 402 Payment Required, reports the price, recipient, chain and whether it falls within the configured spending limits. Use this before pay_and_fetch when the cost matters, or to check whether a URL is paywalled at all.
Inputs: url (required).
pay_and_fetchA
Fetch a resource, paying automatically if it answers 402 Payment Required. THIS SPENDS REAL MONEY from the configured wallet. The payment is refused unless it is within the per-request cap, the remaining lifetime budget, the allowed hosts and the allowed chains - those limits are set by the operator and cannot be raised from here. If a resource is not paywalled it is simply fetched, costing nothing.
Inputs: url (required), method, max_response_chars.
wallet_statusA
Report the paying wallet: its address, its on-chain USDC balance, how much has been spent so far and how much of the budget remains. Reads only - never moves money and never reveals the private key.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: check_price only reads cost, pay_and_fetch performs payment, wallet_status reports wallet state. Descriptions explicitly cross-reference (use check_price before pay_and_fetch) and there is no overlap.
All three names use a consistent snake_case verb_noun pattern (check_price, pay_and_fetch, wallet_status) that reads naturally and follows one convention throughout.
Three tools is a tight, well-scoped surface for a pay-per-fetch wallet server, with each tool earning its place. It is on the lean side but nothing is missing that would bloat the scope.
The core lifecycle is covered: inspect price, authorize/pay, and check wallet budget/balance. Minor gaps exist, such as viewing payment history or a dry-run of a specific payment, but agents can work around these.
Maintenance
Related MCP Connectors
Let your AI assistant pay for web content in USDC (x402) within a budget you set.
Attribution and settlement infrastructure for AI agent content access over HTTP 402 and MCP.
Wallets and rails that let AI agents spend money safely.
Wallets and rails that let AI agents spend money safely.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to discover, inspect, and pay for paid HTTP and MCP services using USDC on Solana with a self-custodial wallet.49Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables pay-per-call access control for AI agents using HTTP 402 and on-chain settlement, allowing microtransactions for API usage.79 PyPIMIT

PayAgents MCP Serverofficial
AlicenseAqualityDmaintenanceEnables AI agents to autonomously make policy-controlled payments for APIs and tools via Bitcoin Lightning (L402) and Base USDC (x402), including paying paywalled endpoints, checking balances, and reviewing transactions.321 npm1MIT- AlicenseNot gradedqualityCmaintenanceEnables AI agents to autonomously pay for metered web APIs on a per-call basis, settling x402 v2 USDC micropayments via EIP-3009 authorization on Base Sepolia without human involvement. Spending is bounded by configurable per-call caps and host restrictions, and exposes tools to fetch paywalled URLs and inspect the agent wallet's address and balance.MIT