🔒 local402

Barrera de pago local en un solo comando para agentes de IA

Convierte cualquier servidor local en un recurso de pago en segundos. Perfecto para probar agentes que necesitan pagar antes de acceder a tu API o herramienta MCP.

npx local402 --target http://localhost:3000 --price 0.001

¿Qué es esto?

local402 coloca una barrera de pago HTTP 402 Payment Required al estilo x402 frente a cualquier servidor HTTP local o herramienta MCP — con un solo comando, sin configuración y sin blockchain.

Las solicitudes sin pago reciben un 402 limpio. Las solicitudes que "pagan" se redirigen directamente a tu servidor real. Eso es todo.

Funciona en modo completamente simulado por defecto: sin carteras, sin gas, sin servicios externos, sin esperas. Solo 402 instantáneos y deterministas que puedes construir y probar localmente.

agent ──▶  local402 (402 paywall)  ──▶  your server
             │
             └── no payment? → 402 Payment Required
                 paid?       → proxied response ✅

Related MCP server: 402-mcp

💸 ¿Por qué local402?

Los agentes están aprendiendo a pagar por cosas — llamadas a API, invocaciones de herramientas, datos, cómputo. El protocolo x402 hace realidad los pagos nativos de HTTP. Pero hay una brecha:

¿Cómo pruebas un agente que paga sin gastar dinero real, configurar una cartera o cablear todo un stack de pagos — cada vez?

No quieres desplegar un facilitador y financiar una cartera de testnet solo para comprobar que tu agente nota un 402 y reintenta con pago. Quieres una barrera de pago que puedas levantar en un comando y derribar igual de rápido.

Eso es local402.

Úsalo para:

• ✅ Probar que tu agente de IA maneja 402 y reintenta con un encabezado x-payment

• ✅ Demostrar una API o herramienta MCP de "pago por llamada" sin tocar una cadena

• ✅ Desarrollar lógica de cliente x402 sin conexión, en un avión, en CI

• ✅ Prototipar precios antes de comprometerte con una liquidación real

⚡ Inicio rápido

Ni siquiera necesitas instalarlo.

# 1. Have any local server running (your API, MCP tool, whatever)
#    e.g. something on http://localhost:3000

# 2. Put a paywall in front of it
npx local402 --target http://localhost:3000 --price 0.001

local402 ahora está escuchando en http://localhost:4020 y protegiendo tu servidor.

# ❌ No payment → 402 Payment Required
curl -i http://localhost:4020/

# ✅ "Pay" → request is proxied to your real server
curl -i http://localhost:4020/ -H "x-payment: simulated"

Apunta tu agente a http://localhost:4020 en lugar de tu servidor real, y míralo aprender a pagar. 🎉

🛠 Uso

local402 --target <url> [options]

La regla

• Sin encabezado x-payment → 402 Payment Required (con un cuerpo JSON útil + encabezados).

• Tiene x-payment: simulated (o paid) → la solicitud se redirige a --target, y la respuesta real regresa sin cambios.

En modo simulado, se acepta cualquier valor x-payment no vacío — simulated y paid son solo los canónicos.

Ejemplos

# Guard an MCP tool on a custom port, charge 0.01
local402 --target http://localhost:8787 --port 9000 --price 0.01

# Free status check — always open, never paywalled
curl http://localhost:4020/__local402

🔍 Cómo funciona

local402 es un pequeño proxy inverso con una opinión: paga primero, luego pasa.

                        ┌──────────────────────────────┐
                        │           local402            │
                        │        :4020 (paywall)        │
   ┌─────────┐          │                               │          ┌──────────────┐
   │  agent  │ ───────▶ │  x-payment header present?    │          │ your server  │
   │ / curl  │          │                               │          │  :3000       │
   └─────────┘          │   NO  ─▶ 402 Payment Required │          └──────────────┘
        ▲               │                               │                 ▲
        │               │   YES ─▶ proxy the request  ──┼─────────────────┘
        │               │         return real response  │                 │
        └───────────────┤◀──────────────────────────────┼─────────────────┘
              402 or proxied response                    │
                        └──────────────────────────────┘

La respuesta no pagada (HTTP 402):

{
  "x402Version": 1,
  "error": "Payment Required",
  "message": "This resource costs 0.001 USD. Retry with header 'x-payment: simulated'.",
  "accepts": [
    {
      "scheme": "simulated",
      "network": "local",
      "maxAmountRequired": "0.001",
      "asset": "USD",
      "payTo": "local402-simulated",
      "resource": "/",
      "description": "local402 simulated paywall",
      "mimeType": "application/json"
    }
  ],
  "hint": "x-payment: simulated"
}

Encabezados de respuesta en un 402:

HTTP/1.1 402 Payment Required
x-payment-required: true
x-payment-amount: 0.001
x-payment-asset: USD
x-payment-network: local
accept-payment: x-payment: simulated

En una solicitud pagada, local402 adjunta un recibo de liquidación simulado para que tu cliente pueda verificar el flujo de extremo a extremo:

x-payment-response: <base64 JSON receipt with a sim txHash>

🗺 Hoja de ruta

local402 comienza simple a propósito. El plan:

• v0.1 — Modo simulado. Barrera de pago 402 instantánea, local y sin blockchain. (estás aquí)

• v0.2 — Liquidación real x402. Verificar cargas útiles reales de X-PAYMENT a través de un facilitador conectable.

• v0.3 — Modo nativo MCP. Barrera de pago de primera clase para herramientas/recursos MCP, no solo HTTP.

• v0.4 — Precios por ruta. Diferentes precios para diferentes rutas y métodos.

• v0.5 — Panel de uso. TUI en vivo de solicitudes, pagos e ingresos.

¿Quieres darle forma? Abre un issue.

🤝 Contribuciones

Las contribuciones, ideas e informes de errores son bienvenidos — esta herramienta pretende ser amigable y pequeña.

git clone https://github.com/wushu75/local402.git
cd local402
npm install
npm run dev -- --target http://localhost:3000   # run from source
npm run build                                    # compile to dist/

1. Haz un fork 🍴

2. Crea una rama (git checkout -b feat/amazing-thing)

3. Confirma tus cambios (git commit -m 'feat: amazing thing')

4. Haz push y abre un PR

Ninguna contribución es demasiado pequeña — incluso corregir un error tipográfico ayuda.

📄 Licencia

MIT © los contribuyentes de local402. Haz lo que quieras con ello.

⭐ Dale estrella al repositorio si es útil

Si local402 te salvó de levantar un stack de pagos solo para probar un agente, dale una estrella — realmente ayuda a que otras personas lo encuentren.

⭐ Dale estrella a local402 en GitHub

Construido para los agentes que pagan su camino. 🔒