Agent Commerce Gateway

Alpha. v0.1.0-alpha ist experimentell. Verwenden Sie es nicht mit Produktionsgeldern, ohne eine unabhängige Überprüfung. Siehe SECURITY.md.

Was es ist, in zehn Sekunden

Sie haben bereits eine HTTP-API. KI-Agenten möchten sie entdecken, aufrufen und bezahlen – über Protokolle, die Sie nicht geschrieben haben und nicht warten möchten.

Agent Commerce Gateway sitzt vor Ihrer bestehenden API, in Ihrer Infrastruktur, und erledigt das für Sie. Sie beschreiben einen Endpunkt in einer YAML-Datei; Agenten erhalten ein MCP-Tool und eine x402-Paywall. Das Geld geht direkt an Ihre Wallet – das Gateway verwahrt es nie und hält nie Ihre Schlüssel.

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

Das Dashboard unter http://localhost:5173 zeigt dieselbe Anfrage in Echtzeit. Es fragt die authentifizierte Events-Route in kurzen Intervallen ab, statt zu streamen: Ein Browser-EventSource kann das Admin-Token nicht senden, und die Operator-Routen sind ohne eines geschlossen – daher ist der SSE-Endpunkt für einen header-fähigen Client erreichbar, nie für einen Browser. Polling ist der vorgesehene Weg des Dashboards, kein degradierter Modus.

Installation

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

Erfordert Node >= 22. Ein Paket liefert zwei Dinge: die agent-commerce-CLI (init, validate, doctor, demo) und eine Bibliothek zum Einbetten des Gateways in Ihren eigenen Prozess. Eine Standardinstallation ist ~49 MB groß und zieht überhaupt keine Blockchain- oder Wallet-Abhängigkeiten.

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;

Optionale Peers – installieren Sie nur die Schienen, die Sie nutzen

Der MCP-Adapter und der x402-Anbieter liegen auf eigenen Unterpfaden, weil jeder eine Abhängigkeit benötigt, die der Rest des Pakets nicht hat. Allein x402 zieht einen Browser-Wallet-Stack (wagmi, WalletConnect, Reown) in Höhe von ~572 MB, den ein Gateway, das eine kostenlose HTTP-Ressource bereitstellt, nicht installieren sollte.

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';

Peers sind exakt gepinnt: Die Schemata von x402 und EIP-712-Domains überschreiten diese Grenze, daher ist eine Versionsabweichung eher ein Korrektheits- als ein Komfortproblem. Importieren Sie einen Unterpfad ohne installierten Peer, schlägt Node beim Laden fehl und nennt das fehlende Paket – bewusst, statt ein Gateway zu starten, das still nichts ausliefert.

Schnellstart

Voraussetzungen: Node >= 22, npm 10, Docker. Sonst nichts – keine API-Schlüssel, kein echtes Geld, kein manuelles Blockchain-Setup.

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

Dann, in einem zweiten Terminal:

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

Nur Linux, und nur, wenn Ihr Benutzer nicht UID/GID 1000 ist (prüfen mit id -u && id -g): exportieren Sie DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) vor docker compose up. Der Chain-Deploy-Schritt läuft als dieser Benutzer, damit das Deployment-Manifest, das er schreibt, host-schreibbar bleibt und nicht Root gehört. Docker Desktop unter macOS und Windows übersetzt Berechtigungen über seine VM und benötigt dies nicht.

Das ist alles. Der Stack besteht aus einer privaten Anvil-Chain, einem Mock-USDC-Token, einer Demo-Merchant-API, dem Gateway und einem Dashboard – alles lokal und wegwerfbar.

Zum Stoppen und Löschen des Zustands: docker compose down -v.

So funktioniert es

        ┌──────────────────────────────────────────────────────┐
        │ 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 │
                                └───────────────────────┘

Jeder Protokoll-Adapter konvergiert auf eine Ausführungspipeline. Genau das macht die Durchsetzung von Zahlungen zu einer Eigenschaft des Systems und nicht zu etwas, an das sich jeder Adapter erinnern muss. Ausführliche Details in docs/architecture.md.

Eine Ressource konfigurieren

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]

Das ist die Integration. Kein SDK in Ihrem Backend, kein Umschreiben.

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

Siehe docs/configuration.md.

Protokollunterstützung

„Geplant“ bedeutet, dass kein Code dafür ausgeliefert wird. Jeder Adapter meldet zur Laufzeit seine eigene Liste aus supportedSpec, capabilities und unsupported über GET /.well-known/agent-commerce und agent-commerce doctor – die Behauptung ist also überprüfbar, kein Marketing. Details: docs/protocols.md.

Zahlungsmodell

• Nicht-verwahrend. Das Gateway verwahrt nie Gelder und fragt nie nach einem privaten Schlüssel von Händler oder Käufer. payTo ist Ihre Adresse.

• Fail closed. Fehlende, fehlerhafte, abgelaufene, erneut gesendete, betragsfalsche, empfängerfalsche, netzwerkfalsche und assetfalsche Zahlungen schlagen alle fehl – jede mit einem Test.

• Doppelt replay-sicher. EIP-3009 stoppt eine Doppelausgabe auf der Chain; das Gateway reserviert zusätzlich einen replayKey, der aus der Autorisierung abgeleitet wird, bevor es irgendetwas abrechnet.

• Echte Abrechnung in CI. Der End-to-End-Test prüft, dass das Guthaben des Käufers sinkt und das des Händlers um genau den Preis steigt, mit einem echten Transaktions-Hash im Receipt. Eine Protokollzeile mit dem Inhalt „Zahlung erfolgreich“ würde nicht zählen.

Details: docs/payment-flow.md.

Diagnose

$ 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

Das ist echte Ausgabe, keine Illustration. doctor gleicht außerdem die Live-Abrechnungs- konfiguration des Gateways mit dem ab, was Ihre lokale Konfiguration ergibt, und schlägt fehl, wenn sie nicht übereinstimmen – eine Diagnose, die besteht, während das System falsch konfiguriert ist, ist schlechter als keine.

Beendet sich mit einem Exit-Code ungleich Null, wenn irgendetwas fehlschlägt. --json für Maschinen.

Erreichbarkeit und Zugriff

Die Demo bindet alles an 127.0.0.1. Bevor Sie das Gateway an einen Ort bringen, der für andere erreichbar ist, sollten Sie die Aufteilung kennen:

• Agent-Routen (/api/resources/:id/invoke, /mcp) sind bewusst nicht authentifiziert – kostenpflichtige Ressourcen sind durch Zahlung geschützt, nicht durch ein Passwort.

• Operator-Routen (/api/receipts, /api/events, /api/events/stream) sind das Handelsledger des Händlers: Absenderadressen, Beträge, Abrechnungshashes. Sie erfordern server.adminToken und geben 404 zurück, wenn keiner konfiguriert ist.

• Browser werden von server.allowedOrigins gesteuert, einer expliziten Zulassungsliste, die standardmäßig leer ist.

• Es gibt kein Rate Limiting. Eine kostenlose Ressource ist ein nicht authentifizierter Proxy zu Ihrem Backend, und zwar mit der Rate, die ein Aufrufer wählt. Quoten und Missbrauchskontrolle gehören in Ihre API oder an Ihren Edge.

SECURITY.md erklärt klar, was dies schützt und was nicht.

Live-Abrechnung – nicht in dieser Version

v0.1.0-alpha rechnet nur gegen die lokale deterministische Chain ab (Anvil + MockUSDC). Es gibt keinen Live-Modus, kein Flag, um einen zu aktivieren, und keinen Teillösungsweg dorthin: facilitator.mode: "remote" wird beim Laden der Konfiguration abgelehnt, und der Health-Check des x402-Anbieters erfordert eine Nur-Anvil-RPC-Methode, sodass /ready gegen ein echtes Netzwerk 503 zurückgibt. Echte Werte abzurechnen ist geplant, nicht ausgeliefert – siehe docs/payment-flow.md.

Entwicklung

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

Foundry (anvil, forge, cast) wird für die Chain-Arbeit benötigt. Siehe CONTRIBUTING.md.

Roadmap

Jetzt (v0.1.0-alpha) – MCP, x402, Receipts, doctor, deterministische Demo.

Als Nächstes – OpenAPI-Import · eine stärkere Konformitätssuite · eine doctor-GitHub-Action · UCP · MPP · ACP · A2A · AP2 · Shopify- und WooCommerce-Beispiele · PostgreSQL · reichhaltigere Observability.

Neue Protokolle kommen nur hinzu, nachdem das Adaptermodell den Praxiseinsatz übersteht. Scope-Disziplin ist eine Release-Anforderung, keine Stimmung.

Dokumentation

Lizenz

Apache-2.0.