Agent Commerce Gateway

Alfa. v0.1.0-alpha es experimental. No lo uses con fondos de producción sin una revisión independiente. Consulta SECURITY.md.

Qué es, en diez segundos

Ya tienes una API HTTP. Los agentes de IA quieren descubrirla, llamarla y pagarla — mediante protocolos que no escribiste y que no quieres mantener.

Agent Commerce Gateway se sitúa delante de tu API existente, en tu infraestructura, y hace eso por ti. Describes un endpoint en un archivo YAML; los agentes obtienen una herramienta MCP y un muro de pago x402. El dinero va directamente a tu cartera — el gateway nunca lo retiene, y nunca retiene tus claves.

Your existing API → Agent Commerce Gateway → AI Agent
                        MCP · x402 · receipts · doctor

Related MCP server: opendexter

Demo

[agent] Discovering resources over MCP...
[agent] Found: market_report — Premium Market Report (0.01 USDC)
[agent] Requesting resource...

[gateway] Payment required: 0.01 USDC → 0x7099…79C8
[buyer] Signing x402 authorisation...
[gateway] Payment verified
[gateway] Payment settled tx 0x4f2c…9ab1
[gateway] Calling merchant backend...
[gateway] Resource delivered

[receipt] payment: settled
[receipt] amount: 0.01 USDC
[receipt] merchant: 0x7099…79C8
[receipt] buyer balance 100.00 → 99.99 mUSDC
[receipt] merchant balance 0.00 → 0.01 mUSDC

El panel en http://localhost:5173 muestra la misma solicitud a medida que ocurre. Consulta la ruta de eventos autenticados en un intervalo corto en lugar de transmitir en streaming: un EventSource del navegador no puede enviar el token de administrador, y las rutas de operador están cerradas sin uno — por lo que el endpoint SSE es alcanzable por un cliente capaz de enviar cabeceras, nunca por un navegador. La consulta periódica es la vía prevista para el panel, no un modo degradado.

Instalación

npx @devlab.group/agent-commerce --help # no install needed
npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
agent-commerce doctor

Requiere Node >= 22. Un paquete incluye dos cosas: la CLI agent-commerce (init, validate, doctor, demo) y una biblioteca para integrar el gateway en tu propio proceso. Una instalación predeterminada es de ~49 MB y no incluye dependencias de blockchain ni de carteras en absoluto.

import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';

const config = await loadConfig({ path: 'config.yaml' });
const gateway = await createGateway({
  config,
  store: receipts({ path: './receipts.sqlite' }),
  paymentProviders: [],
  protocolAdapters: [],
});
const { url } = await gateway.listen;

Pares opcionales — instala solo los raíles que uses

El adaptador MCP y el proveedor x402 viven en sus propias subrutas, porque cada uno necesita una dependencia que el resto del paquete no tiene. Solo x402 incorpora una pila de cartera de navegador (wagmi, WalletConnect, Reown) de ~572 MB, que un gateway que sirve un recurso HTTP gratuito no tiene por qué instalar.

npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk x402 viem

import { mcp } from '@devlab.group/agent-commerce/mcp';
import { x402 } from '@devlab.group/agent-commerce/x402';

Los pares están fijados exactamente: los esquemas de x402 y los dominios EIP-712 cruzan este límite, por lo que un desajuste de versiones es un problema de corrección más que de conveniencia. Importar una subruta sin su par instalado hace que Node falle al cargar nombrando el paquete faltante — deliberadamente, en lugar de iniciar un gateway que silenciosamente no sirve nada.

Inicio rápido

Requisitos: Node >= 22, npm 10, Docker. Nada más — sin claves de API, sin dinero real, sin configuración manual de blockchain.

git clone <repo> && cd agent-commerce
npm install
docker compose up

Luego, en una segunda terminal:

npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole stack
npm run demo:agent # watch an agent buy something

Solo Linux, y solo si tu usuario no tiene UID/GID 1000 (compruébalo con id -u && id -g): exporta DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) antes de docker compose up. El paso de despliegue de la cadena se ejecuta como ese usuario para que el manifiesto de despliegue que escribe siga siendo escribible por el host en lugar de propiedad de root. Docker Desktop en macOS y Windows traduce los permisos a través de su VM y no necesita esto.

Eso es todo. La pila es una cadena Anvil privada, un token USDC simulado, una API de comerciante de demostración, el gateway y un panel — todo local y desechable.

Para detener y borrar el estado: docker compose down -v.

Cómo funciona

        ┌──────────────────────────────────────────────────────┐
        │ AI Agent │
        └──────────────┬───────────────────────────────────────┘
                       │ MCP · HTTP + X-PAYMENT
        ┌──────────────▼───────────────────────────────────────┐
        │ Agent Commerce Gateway (yours) │
        │ │
        │ protocol adapters → ExecutionPipeline → … │
        │ │ │
        │ ┌─────────────────────┼──────────────┐ │
        │ ▼ ▼ ▼ │
        │ PaymentProvider BackendExecutor ReceiptStore │
        │ (x402) (bounded HTTP) (SQLite) │
        └────────┬─────────────────────┬───────────────────────┘
                 │ │
        buyer → merchant ┌──────▼───────────────┐
        (never through us) │ Your backend API │
                                └───────────────────────┘

Cada adaptador de protocolo converge en un único pipeline de ejecución. Eso es lo que hace que la aplicación del pago sea una propiedad del sistema en lugar de algo que cada adaptador tenga que recordar. Detalle completo en docs/architecture.md.

Configurar un recurso

resources:
  market_report:
    name: Premium Market Report
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

Esa es la integración. Sin SDK en tu backend, sin reescritura.

npm run agent-commerce -- init # generate a config interactively
npm run agent-commerce -- validate # fails loudly, exits non-zero

Consulta docs/configuration.md.

Soporte de protocolos

"Planificado" significa que no se envía código para ello. Cada adaptador informa su propio soportedSpec, capabilities y lista unsupported en tiempo de ejecución mediante GET /.well-known/agent-commerce y agent-commerce doctor — para que la afirmación sea comprobable, no marketing. Detalle: docs/protocols.md.

Modelo de pago

• Sin custodia. El gateway nunca retiene fondos, y nunca pide una clave privada de comerciante o comprador. payTo es tu dirección.

• Cierre ante fallos. Los pagos faltantes, malformados, caducados, repetidos, con importe incorrecto, destinatario incorrecto, red incorrecta y activo incorrecto fallan — cada uno con una prueba.

• Seguro contra repetición dos veces. EIP-3009 detiene un doble gasto en la cadena; el gateway además reserva una replayKey derivada de la autorización antes de liquidar cualquier cosa.

• Liquidación real en CI. La prueba de extremo a extremo verifica que el saldo del comprador baja y el del comerciante sube exactamente por el precio, con un hash de transacción real en el recibo. Una línea de registro que diga "pago exitoso" no contaría.

Detalle: docs/payment-flow.md.

Diagnóstico

$ npm run agent-commerce -- doctor --config config-demo.yaml

PASS Config valid — 2 resource(s), merchant "Demo Data Store"
PASS Gateway healthy and ready at http://127.0.0.1:8080
PASS Backend 2/2 backend host(s) reachable
PASS Protocols http=on mcp=on (/mcp)
PASS Payments x402 enabled — network=base-sepolia, destination=0x7099…79C8, facilitator=local
INFO Payments (MPP) planned — not implemented in v0.1
PASS Storage sqlite schema v1 writable; receipts=2
PASS Protocol versions reported by gateway /.well-known/agent-commerce

Score: 7/7 checks passed

Esa es salida real, no una ilustración. doctor también contrasta la configuración de liquidación en vivo del gateway contra lo que tu configuración local resuelve, y falla si no coinciden — un diagnóstico que pasa mientras el sistema está mal configurado es peor que ninguno.

Sale con código distinto de cero si algo falla. --json para máquinas.

Exposición y acceso

La demo vincula todo a 127.0.0.1. Antes de poner el gateway en cualquier lugar alcanzable por cualquier otra persona, conoce la división:

• Rutas de agente (/api/resources/:id/invoke, /mcp) no están autenticadas por diseño — los recursos de pago están protegidos por el pago, no por una contraseña.

• Rutas de operador (/api/receipts, /api/events, /api/events/stream) son el libro de comercio del comerciante: direcciones de pagadores, importes, hashes de liquidación. Requieren server.adminToken, y devuelven 404 si no hay ninguno configurado.

• Los navegadores se rigen por server.allowedOrigins, una lista de permitidos explícita que por defecto está vacía.

• No hay limitación de velocidad. Un recurso gratuito es un proxy no autenticado hacia tu backend a la velocidad que un llamador elija. Las cuotas y los controles de abuso pertenecen a tu API o a tu borde.

SECURITY.md establece claramente qué protege y qué no.

Liquidación en vivo — no en esta versión

v0.1.0-alpha liquida solo contra la cadena determinista local (Anvil + MockUSDC). No hay modo en vivo, ni bandera para habilitarlo, ni camino parcial hacia uno: facilitator.mode: "remote" se rechaza al cargar la configuración, y la verificación de salud del proveedor x402 requiere un método RPC solo de Anvil, por lo que /ready devuelve 503 contra una red real. Liquidar valor real está planificado, no enviado — consulta docs/payment-flow.md.

Desarrollo

npm run verify # contract + lint + typecheck + test
npm run test:e2e # deterministic end-to-end, boots its own chain

Foundry (anvil, forge, cast) es necesario para el trabajo de cadena. Consulta CONTRIBUTING.md.

Hoja de ruta

Ahora (v0.1.0-alpha) — MCP, x402, recibos, doctor, demo determinista.

Siguiente — Importación OpenAPI · una suite de conformidad más sólida · una GitHub Action de doctor · UCP · MPP · ACP · A2A · AP2 · ejemplos de Shopify y WooCommerce · PostgreSQL · observabilidad más rica.

Los nuevos protocolos llegan solo después de que el modelo de adaptador sobreviva al uso real. La disciplina de alcance es un requisito de versión, no un estado de ánimo.

Documentación

Licencia

Apache-2.0.