La primera compra de tu agente

1. Descubre qué puedes comprar

La lista máquina trae cada producto con precio, red y esquema de entrada.

curl -s https://a-upgradenet.com/.well-known/x402

2. Lee el precio

Un POST sin pago responde 402 con el header PAYMENT-REQUIRED. Nada se cobra.

curl -i -X POST https://a-upgradenet.com/x402/web-read \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}'

# HTTP/2 402
# payment-required: <base64 JSON: price, payTo, network eip155:8453, USDC, input schema>
# {"x402Version":2,"error":"Pay 0.005 USDC on Base with x402. No account needed.", ...}

3. Paga y recibe el resultado

Firma exactamente ese precio con un cliente x402 y repite la misma petición con PAYMENT-SIGNATURE. Usa una wallet con saldo pequeño.

npm install @x402/core @x402/evm viem

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const url = "https://a-upgradenet.com/x402/web-read";
const headers = { "content-type": "application/json" };
const body = JSON.stringify({ url: "https://example.com" });

// 1) Ask for the price: unpaid POST answers 402 + PAYMENT-REQUIRED
const quote = await fetch(url, { method: "POST", headers, body });
if (quote.status !== 402) throw new Error(`expected 402, got ${quote.status}`);
const required = JSON.parse(
  Buffer.from(quote.headers.get("PAYMENT-REQUIRED")!, "base64").toString("utf8")
);

// 2) Sign exactly that price (EIP-3009, USDC on Base) with the agent's own wallet
const account = privateKeyToAccount(process.env.AGENT_WALLET_KEY as `0x${string}`);
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account));
const payload = await client.createPaymentPayload(required);
const signature = Buffer.from(JSON.stringify(payload)).toString("base64");

// 3) Repeat the same request with PAYMENT-SIGNATURE
const res = await fetch(url, {
  method: "POST",
  headers: { ...headers, "PAYMENT-SIGNATURE": signature },
  body
});
const result = await res.json();
if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.status, result.transaction); // "completed", 0x... settlement tx

4. Reintenta sin cobrar dos veces

Si la respuesta dice retryable, espera Retry-After y repite con la misma firma. Recibes el resultado guardado.

// Same request + same PAYMENT-SIGNATURE = stored result, never a second charge.
async function buyWithRetry(send: () => Promise<Response>, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await send();
    if (res.ok) return res.json();
    const { error } = await res.json();
    if (!error?.retryable) throw new Error(`${error?.code}: ${error?.message}`);
    const wait = Number(res.headers.get("Retry-After") ?? 5);
    await new Promise(r => setTimeout(r, wait * 1000));
  }
  throw new Error("still not completed; retry later with the same signature");
}

5. Maneja errores por código

Todos los errores son JSON con un código estable. Decide con error.code y error.retryable, nunca con el texto.

{"error":{"code":"INVALID_INPUT","message":"... Nothing was charged.","retryable":false,"request_id":"req_..."}}

Productos por llamada

POST /x402/tool-call-audit        0.1     USDC  Tool-Call Audit
POST /x402/tool-call-audit-pro    0.15    USDC  Tool-Call Audit Pro
POST /x402/tool-call-audit-max    0.2     USDC  Tool-Call Audit Max
POST /x402/planning-benchmark     0.1     USDC  Planning Benchmark
POST /x402/memory-health          0.05    USDC  Memory Health Check
POST /x402/web-read               0.005   USDC  Web Page Reader
POST /x402/base-balance           0.001   USDC  Base Wallet Balance
POST /x402/base-tx                0.002   USDC  Base Transaction Lookup
POST /x402/base-token             0.002   USDC  Base Token Info
POST /x402/base-block             0.001   USDC  Base Latest Block

Siguiente

GET https://a-upgradenet.com/AGENTS.md          AGENTS.md: reglas completas para agentes
GET https://a-upgradenet.com/openapi.json       OpenAPI 3.1: esquemas, ejemplos y límites
GET https://a-upgradenet.com/changelog.md       Changelog de la API