Agent Commerce Gateway

알파. v0.1.0-alpha는 실험 단계입니다. 독립적인 검토 없이 운영 자금에 사용하지 마십시오. SECURITY.md를 참조하세요.

10초 요약

이미 HTTP API를 보유하고 있습니다. AI 에이전트는 여러분이 작성하지 않았고 유지보수하고 싶지 않은 프로토콜을 통해 이를 발견하고, 호출하고, 결제하기를 원합니다.

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이 필요합니다. 하나의 패키지에 두 가지가 포함됩니다: agent-commerce CLI(init, validate, doctor, demo)와 게이트웨이를 자체 프로세스에 내장하기 위한 라이브러리. 기본 설치는 약 49MB이며 블록체인이나 지갑 의존성을 전혀 포함하지 않습니다.

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)을 끌어오며 약 572MB에 달합니다. 무료 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 compose up 전에 DOCKER_UID=$(id -u) DOCKER_GID=$(id -g)를 내보내세요. 체인 배포 단계가 해당 사용자로 실행되어 생성된 배포 매니페스트가 root 소유가 아닌 호스트에서 쓰기 가능한 상태로 유지됩니다. macOS와 Windows의 Docker Desktop은 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는 여러분의 주소입니다.

• 실패 시 폐쇄. 누락, 잘못된 형식, 만료, 재사용, 잘못된 금액, 잘못된 수신자, 잘못된 네트워크, 잘못된 자산 결제는 모두 실패합니다 — 각각 테스트가 있습니다.

• 이중으로 재사용 방지. 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는 또한 게이트웨이의 실시간 정산 구성을 로컬 구성이 해석하는 값과 교차 검증하고, 불일치하면 실패합니다 — 시스템이 잘못 구성된 상태에서 통과하는 진단은 없는 것보다 나쁩니다.

실패 시 0이 아닌 종료 코드를 반환합니다. 머신용 --json 옵션도 있습니다.

노출 및 접근

데모는 모든 것을 127.0.0.1에 바인딩합니다. 게이트웨이를 다른 사람이 접근할 수 있는 곳에 두기 전에 다음 구분을 알아야 합니다:

• 에이전트 라우트(/api/resources/:id/invoke, /mcp)는 설계상 인증이 없습니다 — 유료 리소스는 비밀번호가 아닌 결제로 보호됩니다.

• 운영자 라우트(/api/receipts, /api/events, /api/events/stream)는 판매자의 커머스 원장입니다: 결제자 주소, 금액, 정산 해시가 포함됩니다. server.adminToken이 필요하며, 구성되지 않은 경우 404를 반환합니다.

• 브라우저는 server.allowedOrigins에 의해 제어되며, 기본값이 빈 명시적 허용 목록입니다.

• 속도 제한이 없습니다. 무료 리소스는 호출자가 선택한 속도로 백엔드에 대한 인증 없는 프록시입니다. 할당량과 남용 방지 기능은 API 또는 엣지에 있어야 합니다.

SECURITY.md는 이것이 보호하는 것과 보호하지 않는 것을 명확히 명시합니다.

실시간 정산 — 이번 릴리스에는 없음

v0.1.0-alpha는 로컬 결정적 체인(Anvil + MockUSDC)에 대해서만 정산합니다. 라이브 모드도, 활성화 플래그도, 그 방향의 부분적 경로도 없습니다: facilitator.mode: "remote"는 구성 로드 시 거부되고, x402 프로바이더의 헬스 체크는 Anvil 전용 RPC 메서드를 요구하므로 실제 네트워크에서는 /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 임포트 · 더 강력한 적합성 테스트 스위트 · doctor GitHub Action · UCP · MPP · ACP · A2A · AP2 · Shopify 및 WooCommerce 예제 · PostgreSQL · 더 풍부한 관찰 가능성.

새 프로토콜은 어댑터 모델이 실제 사용에서 검증된 후에만 추가됩니다. 범위 규율은 분위기가 아니라 릴리스 요구 사항입니다.

문서

라이선스

Apache-2.0.