x402-trinity

Un reemplazo total de fetch que permite a un agente de IA pagar por las cosas por sí solo — con límites de gasto estrictos, sin servicio de cartera alojado y sin cambios en el código del propio agente.

Cero dependencias en tiempo de ejecución. 7 KB comprimidos con gzip. Comprador y vendedor en TypeScript; comprador en Python.

npm install x402-trinity

Por qué

Cuando un agente se topa con un recurso de pago recibe 402 Payment Required. Sin algo que lo gestione, la solicitud simplemente falla.

x402-trinity se encarga de ello: lee el desafío, lo verifica contra los límites que tú estableces, firma y reintenta. Todo de manera local — sin servicio de cartera alojado, sin API de terceros, y con la clave que nunca sale de tu proceso.

El gas existe, pero el pagador no lo paga: mediante EIP-3009, el facilitador presenta la transferencia, de modo que la cartera del agente solo necesita USDC.

Related MCP server: remit.md MCP Server

Compra (el agente paga por las cosas)

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

O parchea el ámbito global para que el código no modificado pague automáticamente:

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

Confirma qué cartera va a pagar antes de financiar nada:

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

Imprime la dirección y su saldo en cada cadena, y nunca imprime la clave. Si la dirección no es la cartera que querías, detente antes de enviar cualquier cosa.

Vender (cobra, por un recurso, y recibe el pago)

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) });

Los dos campos obligatorios son deliberados. No hay un facilitador por defecto porque la liquidación es el dinero real de alguien, y adivinar un endpoint no puede ser una opción por defecto. La protección contra ataques de repetición tiene además que sobrevivir al proceso: en memoria, olvida cada pago ya liquidado al reiniciar, así que el comprador podría volver a presentar una autorización ya gastada y llevarse el recurso otra vez gratis. Le constructor lanza una excepción en lugar de permitir que cualquiera de las dos cosas quede implícita.

Esta versión solo incluye Base + USDC. Cualquier otra cadena compatible con EVM funciona a través de customChains; tu dirección es la misma en todas.

Qué hace

Otra cadena

Base es la opción por defecto. La firma no depende de la cadena, así que añade todo lo que necesites — incluso una red de pruebas para ensayar:

const fetch2 = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,
  maxAmountPerRequest: '10000',
  totalBudget: '100000',
  customChains: {
    'base-sepolia': { id: 84532, asset: '0x036cbd53842c5426634e7929541ec2318f3dcf7e', name: 'USDC', version: '2' },
  },
});

Verifica antes la entrada contra el contrato ya desplegado: llama a DOMAIN_SEPARATOR() y comprueba que coincide con lo que esta biblioteca calcula. Un name o version erróneos producen una firma que parece válida… y el contrato la detecta.

Lo que deliberadamente no hará

Broadcast a una chain · dar un recibo · "gasless" por el gas (el retador vive en la red) · … no, mejor con texto plano: no va a retransmitir, no custodia fondos, no necesita gas mismo puede pedir, no acepta un bono… – qué será: no operar en cadenas externalizadas, pero sí: the sentence is:

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, or guess at a protocol it doesn't speak.

En español:

Deliberadamente no hará lo siguiente

Transmitir a una cadena · custodiar fondos · necesitar gas o un RPC · quedarse con una parte del e pago (estructuralmente imposible — EIP-3009 tiene un solo beneficiario) · exigir un firmante alojado ·osegurar pagos sin límites · adivinar un protocolo que se no hable.

Seguridad — lee esto antes de usar dinero real dinero

Los límites son obligatorios. maxAmountPerRequest y `totalBudgetirú no tienen valor por defecto; el wrapper se niega a construirse sin ellos. Un pagador automático sin limitaciones es una fuga de dinero a cargo de quien controle el servidor.

totalBudget solo vale por instancia. Es un contador en memoria que se resetea al reiniciar el proceso, al crearte un cliente nuevo y en cada aislado de Cloudflare Workers — unpoco de cada solicitud. En mainnet, eso convierte un límite de por vida en un límite por petición. Por eso, en mainnet se necesita un budgetStore persistente, o bien una aceptación explícita de acknowledgeEphemeralBudget: true:

import { createFileBudgetStore } from 'x402-trinity/budget-file';

createX402Fetch({
  ...,
  budgetStore: createFileBudgetStore('./.x402-budget.json'),   // survives restarts
});

**Custodia del pago.If the key is in the process, esa es la concesión de no tener un firmador alojado. Limitar los daños: usa una cartera dedicada que solo contenga lo que acepta perder, establece allowPayTo para que una clave exfiltrada no pueda pagar a un desconocido por este envoltorio, y remite a remoteSign si necesitas una custodia a nivel de recinto.

La arquitectura de tiempo es eso: una defensa, no es una herramienta. Los escalares secretos usan ofuscación y siempre suman dobles, lo que reduce la muestra de tiempo del 99.6% al 12% (Python, del 99.9% al 1.1%).t; but la aritmética BigInt es de por sí de tiempo variable.

Servidor MCP — dale un inicio a un agente un

MCP es la forma en que un asistente al

{
  "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"
      }
    }
  }
}

El modelo decide si se ejecutan con él. un supuesto presupuesto no se puede razonar: una web de pago puede declarar el precio que quiera. El límite, por tanto, no es son parámetros que the model set: provienen del entorno, y el servidor se niega a arrancar si no están X402_PRIVATE_KEY, X402_MAX_PER_REQUEST y no X402_TOTAL_BUDGET.

Configura también X402_BUDGET_FILE, o el límite de por vida se reiniciosobre cada reinicio. Definir un X402_ALLOW_HOSTS y nada más puede ser pagado:aunque el desafío provenga de qualquerón. Usa un el monedero dedicado.

Python

Mismo protocolo, solo biblioteca optimizada. Solo comprador — para cobrar por vender un recurso usa el vendedor TypeScript. Diseñado para procesos de larga vida: agentes personales, controladores de robótica, copias de seguridad.

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()

Para usarlo como decorador:

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()

La vía cálida es 1.1 µs — el controlador de un proceso de larga vida queda en forma desde la primera transacción.

Desarrollo

npm install
npm run build        # dist/*.js + *.min.js + *.d.ts

esbuild, typescript y wrangler son solo para extender el proyecto y no formas parte del entorno en tiempo de ejecución. El paquete resultante no tiene dependencias.

Licencia

MIT. Este software mueve dinero real, preste atención al aviso adicional LICENSE y define con dinero tus límites —tope máximo de validez**.