Agent Commerce Gateway

Альфа. v0.1.0-alpha — экспериментальная версия. Не используйте её с реальными средствами без независимого аудита. См. SECURITY.md.

Что это такое, за десять секунд

У вас уже есть HTTP API. ИИ-агенты хотят находить его, вызывать и платить за него — через протоколы, которые вы не писали и не хотите поддерживать.

Agent Commerce Gateway встаёт перед вашим существующим API, в вашей инфраструктуре, и делает это за вас. Вы описываете эндпоинт в YAML-файле; агенты получают MCP-инструмент и x402-пейволл. Деньги идут напрямую в ваш кошелёк — шлюз никогда не держит их у себя и не хранит ваши ключи.

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

Related MCP server: opendexter

Демо

[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

Дашборд на http://localhost:5173 показывает тот же запрос в реальном времени. Он опрашивает аутентифицированный маршрут событий с коротким интервалом, а не через стриминг: браузерный EventSource не может отправить админ-токен, а операторские маршруты без него закрыты — поэтому SSE-эндпоинт доступен клиенту, умеющему отправлять заголовки, но никогда браузеру. Опрос — это штатный путь дашборда, а не ухудшенный режим.

Установка

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

Требуется Node >= 22. Один пакет содержит две вещи: CLI agent-commerce (init, validate, doctor, demo) и библиотеку для встраивания шлюза в ваш собственный процесс. Стандартная установка — ~49 МБ и не тянет никаких блокчейн- или кошельковых зависимостей.

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;

Опциональные пиры — ставьте только нужные рельсы

MCP-адаптер и x402-провайдер живут на собственных подпутях, потому что каждому нужна зависимость, которой нет в остальном пакете. Один x402 тянет браузерный кошелёчный стек (wagmi, WalletConnect, Reown) примерно на ~572 МБ, который шлюзу, обслуживающему бесплатный HTTP-ресурс, устанавливать незачем.

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

Пиры закреплены точно: схемы x402 и EIP-712-домены пересекают эту границу, поэтому расхождение версий — это проблема корректности, а не удобства. Импортируете подпуть без установленного пира — и Node падает при загрузке, называя недостающий пакет, — намеренно, а не запускает шлюз, который молча ничего не обслуживает.

Быстрый старт

Требования: Node >= 22, npm 10, Docker. Больше ничего — никаких API-ключей, реальных денег или ручной настройки блокчейна.

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

Затем, во втором терминале:

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

Только Linux, и только если ваш пользователь не UID/GID 1000 (проверьте через id -u && id -g): экспортируйте DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) перед docker compose up. Шаг развёртывания цепочки выполняется от этого пользователя, чтобы создаваемый им манифест развёртывания оставался доступным хосту на запись, а не принадлежал root. Docker Desktop на macOS и Windows транслирует права через свою VM, и это не требуется.

Вот и всё. Стек — это приватная цепочка Anvil, мок-токен USDC, демо-мерчант API, шлюз и дашборд — всё локальное и одноразовое.

Чтобы остановить и стереть состояние: docker compose down -v.

Как это работает

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

Каждый протокольный адаптер сходится к одному конвейеру исполнения. Именно это делает принудительную оплату свойством системы, а не тем, о чём должен помнить каждый адаптер. Подробности в docs/architecture.md.

Настройка ресурса

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]

Вот и вся интеграция. Никакого SDK в вашем бэкенде, никакого переписывания.

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

См. docs/configuration.md.

Поддержка протоколов

«Запланировано» означает никакого кода для этого не поставляется. Каждый адаптер сообщает собственные supportedSpec, capabilities и список unsupported в рантайме через GET /.well-known/agent-commerce и agent-commerce doctor — так что утверждение проверяемо, а не маркетинг. Подробности: docs/protocols.md.

Модель оплаты

• Без кастодиального хранения. Шлюз никогда не держит средства и никогда не запрашивает приватный ключ мерчанта или покупателя. payTo — это ваш адрес.

• Fail closed. Отсутствующие, повреждённые, истёкшие, повторные, неверной суммы, неверному получателю, неверной сети и неверного актива платежи — все отклоняются, у каждого есть тест.

• Двойная защита от повторов. EIP-3009 останавливает двойное списание в цепочке; шлюз дополнительно резервирует replayKey, производный от авторизации, до того как что-либо расчехлит.

• Реальное расчехление в CI. Сквозной тест проверяет, что баланс покупателя падает, а баланс мерчанта растёт ровно на цену, с реальным хэшем транзакции в чеке. Строка в логе «платёж успешен» не засчиталась бы.

Подробности: docs/payment-flow.md.

Диагностика

$ 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

Это реальный вывод, а не иллюстрация. doctor также перекрёстно проверяет живую конфигурацию расчехления шлюза против того, во что резолвится ваш локальный конфиг, и падает, если они расходятся — диагностика, которая проходит, пока система неправильно сконфигурирована, хуже, чем её отсутствие.

Возвращает ненулевой код, если что-то не так. --json — для машин.

Доступ и открытость

Демо привязывает всё к 127.0.0.1. Прежде чем выставлять шлюз туда, где его может достичь кто-то ещё, знайте разделение:

• Агентские маршруты (/api/resources/:id/invoke, /mcp) не аутентифицированы по замыслу — платные ресурсы защищены оплатой, а не паролем.

• Операторские маршруты (/api/receipts, /api/events, /api/events/stream) — это коммерческий реестр мерчанта: адреса плательщиков, суммы, хэши расчехления. Они требуют server.adminToken и возвращают 404, если он не настроен.

• Браузеры управляются через server.allowedOrigins — явный белый список, по умолчанию пустой.

• Ограничения скорости нет. Бесплатный ресурс — это неаутентифицированный прокси к вашему бэкенду с любой скоростью, которую выберет вызывающий. Квоты и защита от злоупотреблений — дело вашего API или вашего edge.

SECURITY.md прямо говорит, что это защищает, а что нет.

Живое расчехление — не в этом релизе

v0.1.0-alpha расчехляет только против локальной детерминированной цепочки (Anvil + MockUSDC). Нет живого режима, нет флага для его включения и нет частичного пути к нему: facilitator.mode: "remote" отклоняется при загрузке конфига, а проверка здоровья x402-провайдера требует RPC-метод, доступный только в Anvil, поэтому /ready возвращает 503 против реальной сети. Расчехление реальной ценности запланировано, а не поставляется — см. docs/payment-flow.md.

Разработка

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

Для работы с цепочкой нужен Foundry (anvil, forge, cast). См. CONTRIBUTING.md.

Дорожная карта

Сейчас (v0.1.0-alpha) — MCP, x402, чеки, doctor, детерминированное демо.

Далее — импорт OpenAPI · более строгий набор тестов на соответствие · GitHub Action для doctor · UCP · MPP · ACP · A2A · AP2 · примеры для Shopify и WooCommerce · PostgreSQL · более богатая наблюдаемость.

Новые протоколы появляются только после того, как модель адаптеров переживёт реальное использование. Дисциплина объёма — требование релиза, а не настроение.

Документация

Лицензия

Apache-2.0.