Permet aux agents IA de payer de manière autonome les ressources HTTP 402 en utilisant l'USDC, avec des limites de dépenses strictes et une gestion de portefeuille locale.
Aussi connu sous devmster/x402-trinity, x402-trinity
- Étoiles
- 3
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- 0.2.4
- Dernier commit
- 27 sept. 2026
- Licence
- —
Qu'est-ce que x402 Trinity MCP ?
Permet aux agents IA de payer de manière autonome les ressources HTTP 402 en utilisant l'USDC, avec des limites de dépenses strictes et une gestion de portefeuille locale.
Résumé généré à partir du README du projet
À propos du MCP server x402 Trinity
x402 Trinity offre un moyen aux agents IA de gérer de manière autonome les réponses HTTP 402 Payment Required en payant les ressources en USDC. Il fonctionne comme un remplacement direct de fetch, permettant aux agents d'accéder à des API, des jeux de données ou des fichiers payants sans intervention manuelle. Le système est conçu pour une gestion de portefeuille locale, garantissant que les clés privées ne quittent jamais le processus local et qu'aucun service de portefeuille tiers hébergé n'est requis.
xLes développeurs peuvent configurer des limites de sécurité strictes via des plafonds de dépenses obligatoires, comprenant des montants maximums par requête et des budgets totaux sur la durée de vie du service. Le serveur prend en charge le réseau Base par défaut, mais peut être étendu à n'importe quelle chaîne EVM via des configurations personnalisées. Il inclut des outils spécifiques pour que les agents puissent vérifier les prix, exécuter des paiements et surveiller l'état du portefeuille. Comme l'agent contrôle le budget, le serveur nécessite des variables d'environnement telles que X402_PRIVATE_KEY et X402_TOTAL_BUDGET pour fonctionner, empêchant ainsi le modèle de contourner les contraintes financières.
Ce que vous pouvez faire avec
- 1Transactions locales sécuriséesLes utilisateurs peuvent gérer les paiements localement pour garantir que la clé privée n'est jamais exposée à une API tierce.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer x402 Trinity MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller x402 Trinity MCP dans Claude Code
$ claude mcp add --env 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' --env 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' --env 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' x402-trinity -- npx -y x402-trinityInstaller x402 Trinity MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"x402-trinity": {
"command": "npx",
"args": [
"-y",
"x402-trinity"
],
"env": {
"X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
"X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
"X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
}
}
}
}Installer x402 Trinity MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"x402-trinity": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"x402-trinity"
],
"env": {
"X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
"X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
"X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
}
}
}
}Installer x402 Trinity MCP dans VS Code CLI
$ code --add-mcp '{"name":"x402-trinity","type":"stdio","command":"npx","args":["-y","x402-trinity"],"env":{"X402_PRIVATE_KEY":"<YOUR_X402_PRIVATE_KEY>","X402_MAX_PER_REQUEST":"<X402_MAX_PER_REQUEST>","X402_TOTAL_BUDGET":"<X402_TOTAL_BUDGET>"}}'Installer x402 Trinity MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"x402-trinity": {
"command": "npx",
"args": [
"-y",
"x402-trinity"
],
"env": {
"X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
"X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
"X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
}
}
}
}Installer x402 Trinity MCP dans Codex
$ codex mcp add x402-trinity --env 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' --env 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' --env 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' -- npx -y x402-trinityInstaller x402 Trinity MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.x402-trinity] command = "npx" args = ["-y", "x402-trinity"] [mcp_servers.x402-trinity.env] X402_PRIVATE_KEY = "<YOUR_X402_PRIVATE_KEY>" X402_MAX_PER_REQUEST = "<X402_MAX_PER_REQUEST>" X402_TOTAL_BUDGET = "<X402_TOTAL_BUDGET>"
Installer x402 Trinity MCP dans Gemini CLI
$ gemini mcp add -s user -e 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' -e 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' -e 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' x402-trinity npx -- -y x402-trinityInstaller x402 Trinity MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"x402-trinity": {
"command": "npx",
"args": [
"-y",
"x402-trinity"
],
"env": {
"X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
"X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
"X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
}
}
}
}Configuration
X402_PRIVATE_KEYRequisSecretPrivate key of the wallet that pays. Use a dedicated wallet holding only what you would accept losing. The server refuses to start without it.
X402_MAX_PER_REQUESTRequisHard ceiling for a single payment, in atomic units (USDC has 6 decimals, so 50000 is $0.05). Required: a model decides when payments happen, so the cap cannot come from the model.
X402_TOTAL_BUDGETRequisLifetime ceiling across all payments, in atomic units. Required for the same reason as the per-request cap.
X402_ALLOW_HOSTSComma-separated hosts that may be paid. Anything else is refused however convincing the challenge looks.
X402_BUDGET_FILEPath to a file that makes the lifetime budget survive restarts. Without it the total resets every time the server starts.
X402_NETWORKSNetworks to accept. Defaults to base.
| Nom | Description | Type |
|---|---|---|
| X402_PRIVATE_KEY | Private key of the wallet that pays. Use a dedicated wallet holding only what you would accept losing. The server refuses to start without it. | RequisSecret |
| X402_MAX_PER_REQUEST | Hard ceiling for a single payment, in atomic units (USDC has 6 decimals, so 50000 is $0.05). Required: a model decides when payments happen, so the cap cannot come from the model. | Requis |
| X402_TOTAL_BUDGET | Lifetime ceiling across all payments, in atomic units. Required for the same reason as the per-request cap. | Requis |
| X402_ALLOW_HOSTS | Comma-separated hosts that may be paid. Anything else is refused however convincing the challenge looks. | |
| X402_BUDGET_FILE | Path to a file that makes the lifetime budget survive restarts. Without it the total resets every time the server starts. | |
| X402_NETWORKS | Networks to accept. Defaults to base. |
Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibledevmster/x402-trinity is public and reachablegithub.com/devmster/x402-trinity ↗Réussi
- Le nom du package correspond au dépôt sourcex402-trinity names devmster/x402-trinity as sourcenpmjs.com/package/x402-trinity ↗Réussi
- Provenance du build (attestation Sigstore)No build attestation published for this releaseNon vérifié
- Licence open source (OSI)No licenseFaille
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-09-27github.com/devmster/x402-trinity ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from x402-trinityRéussi
- Aucun avis critique dans le package ou ses dépendances1 resolved dependencies checked; no critical advisoryosv.dev ↗Réussi
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubx402-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
Copy-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.
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.
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
| 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 customChains |
| Networks | short names and CAIP-2 (eip155:8453) |
| Custody | privateKey, additive shards, or remoteSign (HSM/MPC) — your choice, not the architecture's |
| 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 | |
|---|---|
check_price |
what a resource costs, without paying |
pay_and_fetch |
fetch it, paying if it is within your limits |
wallet_status |
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.ts
esbuild, 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.
Questions sur x402 Trinity MCP
Comment ajouter x402 Trinity MCP à Claude Code ?
Exécutez claude mcp add --env 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' --env 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' --env 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' x402-trinity -- npx -y x402-trinity dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter x402 Trinity MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Comment l'agent paie-t-il les ressources ?
Le serveur gère les défis HTTP 402 Payment Required en lisant le défi, en le vérifiant par rapport aux limites définies par l'utilisateur, en signant la transaction et en réessayant la requête.
L'agent doit-il payer des frais de gaz ?
Non, l'agent a seulement besoin d'USDC car le facilitateur soumet le transfert via EIP-3009.
Puis-je limiter le montant dépensé par l'agent ?
Oui, vous devez configurer des plafonds de dépenses obligatoires, incluant un montant maximum par requête et un budget total cumulé.