de en es ja ko ru zh

Agent Commerce Gateway

Name: Agent Commerce Gateway
Author: devlab-group

by devlab-group

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Alpha。 v0.1.0-alpha 是实验性的。未经独立审查，请勿将其用于生产资金。参见 SECURITY.md。

十秒钟了解它是什么

你已经有了一个 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）和一个用于将网关嵌入到你自己进程中的库。默认安装约为 ~49 MB，完全不拉取任何区块链或钱包依赖。

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 就会拉取约 ~572 MB 的浏览器钱包栈（wagmi、WalletConnect、Reown），而一个服务免费 HTTP 资源的网关没有理由安装这些。

你想要	安装	导入
网关、配置、收据、CLI	`@devlab.group/agent-commerce`	`from '@devlab.group/agent-commerce'`
将资源暴露为 MCP 工具	`+ @modelcontextprotocol/sdk`	`from '@devlab.group/agent-commerce/mcp'`
接受 x402 支付	`+ x402 viem`	`from '@devlab.group/agent-commerce/x402'`

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。

协议支持

协议	状态	锁定版本
MCP	已支持	`@modelcontextprotocol/sdk@1.30.0`
x402	已支持	`x402@1.2.0`, scheme `exact`, EVM
HTTP	已支持	原生路由
UCP	计划中	—
ACP · MPP · A2A · AP2	计划中	—

"计划中"意味着不会为其发布代码。每个适配器在运行时通过 GET /.well-known/agent-commerce 和 agent-commerce doctor 报告自己的 supportedSpec、capabilities 和 unsupported 列表——因此这一声明是可验证的，而非营销话术。详情：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 还会将网关的实时结算配置与你的本地配置解析结果进行交叉检查，如果不一致则失败——在系统配置错误时仍然通过的诊断比没有更糟。

任何失败都会以非零退出码退出。--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 · 更丰富的可观测性。

新协议只有在适配器模型经受住真实使用考验后才会落地。范围纪律是发布要求，而非一时情绪。

文档


架构	各部分如何配合
支付流程	付费往返流程，以及所有失败方式
协议	精确说明支持和不支持的内容
配置	`config.yaml` 参考
安全模型	信任边界，以及我们不防御的内容
契约	冻结的跨包契约
适配器指南	添加协议或支付轨道

许可证

Apache-2.0。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive

ResponsivenessWithin a week

Resources

Need Help?

Related Servers

Related MCP Connectors

WORKMINE A
io.github.Tamerlan0606
x402 pay-per-call APIs over MCP, settled in USDC on Base for autonomous agents and developers.
Blockchain Cryptocurrency Payments & Billing
81
agent-x402-paywall-mcp
io.github.CSOAI-ORG
Agent x402 Paywall MCP — Coinbase HTTP 402 protocol + on-chain settlement. Agents pay per-call
Blockchain Cryptocurrency Payments & Billing
2
AIPP Monetize A
dev.aipp
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
Payments & Billing Cryptocurrency Blockchain
31
PayGate MCP — Monetization Gateway for AI Agents A
io.github.geoacpfilho
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Payments & Billing Cryptocurrency Blockchain
61

Related MCP Servers

gatefareio/mcp-serverofficial
Payments & Billing Cryptocurrency
gatefareio
A
license
A
quality
D
maintenance
Marketplace MCP for paid HTTP APIs. Pay per call in USDC on Base via the open x402 standard — non-custodial. 13 tools for discovery, buying, and publishing APIs.
Updated 4 months ago (2026-05-31 04:13 UTC)
7
39 npm
2
MIT
opendexterofficial
Payments & Billing Cryptocurrency
Dexter-DAO
A
license
Not graded
quality
C
maintenance
An MCP server that enables AI agents to search, pay for, and call paid APIs using the x402 protocol, with automatic USDC settlement.
Updated 15 days ago (2026-09-28 21:15 UTC)
2
MIT
x402-mcp
merkleworks
A
license
Not graded
quality
D
maintenance
MCP server for the x402 protocol that lets AI agents discover and call payment-gated HTTP APIs automatically.
Updated 7 months ago (2026-03-15 22:03 UTC)
144 npm
Apache 2.0
CryptoAPIs x402 Pay MCPofficial
Blockchain Cryptocurrency Payments & Billing
CryptoAPIs-io
A
license
A
quality
C
maintenance
Enables AI agents to discover and pay for x402-gated HTTP APIs, handling 402 Payment Required flows with local signing. Supports EVM and Solana with non-custodial wallet management.
Updated 15 days ago (2026-09-28 11:48 UTC)
3
127 npm
MIT