DebitMyData Agentic Superhighway

DebitMyData Agent Gateway

状态：开发中。 目前尚不支持真实支付，所有支付渠道默认关闭。完整流程在测试网络上运行（私有 DebitMyData regtest 链，以及通过 x402 使用 USDC 的 Base Sepolia）。请参阅状态。

Agent Gateway 正在开发中，旨在成为一个公开集成入口，让自主 Agent、机器人、数字孪生、个人和组织能够发现 DebitMyData、获取报价、通过获准的支付渠道付款、证明对其钱包或密钥的控制权，并获得 DebitMyData DID-LLM、签名凭证和权益。

该网关位于 DebitMyData 工作量证明链的外围。它不会更改 DebitMyData 共识，也绝不会向调用方公开节点 RPC、私钥或金库控制权限。

命名。 DMD 是 DebitMyData 币的代码，也是 DebitMyData 工作量证明链的原生币（地址以 dm1 开头）；每个 DebitMyData 钱包都显示它。它不是 Ethereum 或 Base 上的代币，也与使用相同代码的其他代币无关。因此，金额和价格以 DMD 为单位，支付选项名为 DebitMyData 币（原生 PoW 链），而该项目、其链、节点和区块浏览器均称为 DebitMyData。

Agent wallet (Coinbase / AWS / DMD / other approved)
        │
        ▼
Discovery: REST / MCP / x402 Bazaar
        │
        ▼
Agent Gateway ── quote + payment intent + policy
        │
        ├── Native DMD adapter ──► private DebitMyData nodes (watch-only)
        ├── x402 / USDC Base adapter ──► facilitator
        ├── Card adapter ──► Stripe Checkout (payment page hosted by Stripe)
        └── future approved rails (disabled until reviewed)
        │
        ▼
Settlement & finality ──► DID-LLM + receipt + credential + entitlements ──► append-only audit

状态

这是一个早期开发版本（0.36.3）。整个注册流程（报价、支付、控制者证明、DID-LLM 和签名凭证）均可通过 REST 和 MCP，在测试网络上端到端运行；支付方式可以是原生 DMD（私有 regtest 链），也可以是通过 x402 使用 USDC（Base Sepolia）。目前尚不支持真实支付：

区域	状态
FastAPI 服务、设置、结构化 JSON 日志、请求关联 ID	完成
/healthz、/readyz、/v1/discovery、/v1/payment-options、位于 /docs/advanced 的 OpenAPI	完成
面向用户的 /get-did 页面“获取 DID-LLM”（生产环境的 /docs 会跳转至此）：报价、付款、由其钱包签名的消息、DID-LLM	完成（DMD；通过 API 使用 USDC）
所有面向用户的页面均采用 debitmydata.com 的样式（顶部栏、页脚、颜色、字体）：“获取 DID-LLM”、高级 API 文档、政策、暂存环境的引导式测试	完成
以引导式页面的方式打开的高级 API 文档：步骤以卡片显示，并根据答案变化；更大的文字和按钮；下方列出所有端点	完成
支持按支付通道单独启用和紧急关闭的支付路由注册表	完成
标准化支付状态机和 DID 签发规则	完成
精确的小数／基本单位货币运算	完成
PostgreSQL 架构和迁移；只追加的审计账本和支付账本	完成
报价端点（POST /v1/dids/registration-quotes）、价格来源规则、Idempotency-Key 重试	完成（仅响应已启用的支付通道）
原生 DMD 支付适配器：每个报价使用独立地址、独立验证、确认数、重组和双花处理	完成（regtest）
支付工作进程（dmd-gateway-worker）和支付状态（GET /v1/payments/{id}）	完成
控制者证明：使用 Agent 的 Ed25519 密钥和／或其 EVM 钱包签署一次性挑战（普通钱包，以及通过 ERC-1271 和 ERC-6492 支持的智能钱包）	完成
DID-LLM 签发（did:web）、签名注册凭证（W3C VC 2.0、eddsa-jcs-2022）、dmd_did_holder 权益	完成（regtest；仍需生产签名器）
位于 /agenticsuperhighway 的 MCP 服务 Agentic Superhighway，提供指令中的工具（Streamable HTTP）、付款人交易参考信息	完成
Cloudflare 后的暂存服务；可从其文档页面试用完整流程，暂存环境提供引导式测试页面（高级：在 /docs/advanced 逐步使用 Swagger UI；仅暂存环境提供测试工具）	完成
x402／Base 上的 USDC：注册时返回 HTTP 402、facilitator 验证／结算、链上结算检查、Bazaar 描述、MCP 付款	完成（Base Sepolia）
Base 主网就绪：DebitMyData 的 USDC 收款地址（DEC-08）、使用 API 密钥验证的 Coinbase CDP facilitator、对无需报价即可探测路由的 x402 工具返回含真实条款的 402（Coinbase 的 Bazaar 验证器）、scripts/validate_bazaar.py	完成（需要 DebitMyData 的 CDP API 密钥和生产服务）
请求速率限制（按地址和总量限制，配置在暂存环境的 nginx 上）、按控制者密钥限制未结报价数量、负载测试脚本	完成（生产限制应配置在边缘层，见 docs/staging.md）
根据 DMD 挖矿成本（区块工作量所需的电力）计算 DMD/USD 参考价格，每 5 分钟计算一次并保存输入，提供 GET /v1/prices/dmd-usd	完成（暂存环境从公共浏览器读取 DebitMyData 难度）
通过电子邮件和 Discord 进行监控和告警（dmd-gateway-monitor，每 2 分钟运行一次）：API、支付工作进程、每种支付方式的节点／RPC／facilitator、DMD 价格、DebitMyData 节点与浏览器的差异、签发后离开区块链的付款、应退款项、卡住的付款、收款地址变更；每日对账报告会再次在链上检查过去 30 天内结算的每笔付款（docs/monitoring.md）	完成（每台服务都需要配置电子邮件和 Discord 设置）
在 DMD 有市场价格之前设定 DMD/USD 最低汇率：价格取 0.001 USD／DMD 和挖矿成本两者中的较高值（价值 25.00 USD 的 DID-LLM 收费 25,000 DMD），价格页面会显示两者	完成（DebitMyData 于 2026 年 10 月 27 日批准）
在 /policies 提供政策页面（条款、隐私、安全、付款方式、退款、DID-LLM 政策），并在每份报价中附上链接	完成（已于 2026-11-02 批准并发布）
面向 Agent 的推理捐款（POST /v1/donations/inference）：由 Agent 自选金额，通过 x402 使用 USDC 向 DebitMyData 的推理钱包付款，并收到签名收据；提供 REST、MCP（dmd_purchase）和 Bazaar 描述。用户仍可在 debitmydata.com 捐款（“Inference $”）	完成（Base Sepolia；生产环境需要 DMD_USDC_BASE_INFERENCE_ADDRESS 和 CDP facilitator）
为 DID-LLM 购买产品：BottyBotty 提供三个等级（Entry 49、Standard 99、Premium 199 USD），每个等级只需支付一次，永久拥有；升级时只需支付差价（/v1/products）；使用 DMD 付款，然后由 DebitMyData 签署收据，并将相应等级的权益写入 DID-LLM；提供 REST 和 MCP（dmd_purchase、dmd_complete_purchase）	完成（暂存环境已启用；生产环境暂未启用，直到接通 BottyBotty 一侧）
“获取 DID-LLM”：以 QR 码显示 DMD 付款信息，并提供“在我的 DMD 钱包中打开”链接（debitmydata: 付款链接）	完成
将“获取 DID-LLM”作为手机应用提供：在专用地址（DMD_GW_APP_HOST、id.debitmydata.io）上，页面位于根路径，带有 Web 应用清单、图标和 service worker，可添加到主屏幕（docs/production.md）；USDC 排在首位（关闭时呈灰色并标注“即将推出”）；附有 DMD 简介和获取方法	完成（需要 DNS 记录）
页面顶部栏为白色，滚动时固定在顶部；在手机上折叠为菜单按钮（无需脚本）；DebitMyData 名称链接至网站首页；页脚采用类似 Agentic Spaces 网站的分栏布局；页面滚动后显示“返回顶部”按钮	完成
页面顶部栏和网站图标使用 DebitMyData 自有徽标（取自 debitmydata.com 徽标的硬币一面，重新绘制得更清晰），并带有黑色二进制线条；应用图标在白色圆形和金色圆环中显示红色线条版本（适用于深色主屏幕）	完成
应用会在手机和平板上以居中窗口的形式提示安装，并显示应用图标：应用内不会提示，浏览器报告已安装时也不会提示（每次访问时调用 getInstalledRelatedApps，因此卸载应用后会再次提示）；浏览器仅记住“暂不”，保留 30 天（点击叉号或弹窗外部仅关闭弹窗）；每个页面的页脚都有“获取应用”按钮，可再次打开提示，或显示应用已安装	完成
“获取 DID-LLM”会在步骤前介绍 DID-LLM，采用 Agentic Spaces 风格：介绍数据、什么是 DID-LLM、AI Agent 为何需要它以及它的工作原理；卡片会随滚动进入视野，并在鼠标悬停或轻触时上浮；主屏幕上的应用名称为“DID-LLM DebitMyData”	完成
面向用户和 Agent 的所有内容中，名称统一使用 DID-LLM（页面、应用、政策、API 文档、MCP 描述、错误消息）；标识符保持不变（did:web、did、/get-did、dids 路径）	完成
面向 AI Agent：提供 /llms.txt（介绍如何自行注册和付款，列出本服务的地址和当前开放的支付方式），并从“获取 DID-LLM”页面顶部、页脚及无脚本提示中链接至此；页面还提供 MCP 服务地址	完成
页面页脚列出三个 DMD 浏览器（Mempool explorer、Lite explorer、Rich list & API），与 debitmydata.io 一致；签发 DID-LLM 后，页面会显示“加入 Agentic Hub”	完成
“获取 DID-LLM”在 USDC 和 DMD 之后显示灰色的借记卡或信用卡（Stripe）以及 PayPal，并标注“即将推出”，直到网关提供这些支付方式	完成
DID-LLM 卡片付款（支付方式 card_stripe）：每份报价都有独立的 Stripe 付款页面（Stripe Checkout、payment_url），在 31 分钟的报价有效期内均可打开；银行卡信息仅发送给 Stripe；工作进程会直接向 Stripe 核验每笔付款（受限密钥：可写入 Checkout Sessions，可读取 PaymentIntents 和 Charges），并保留已结算付款 30 天以处理退款和争议（refunded、disputed；尚未签发的注册会被取消，已签发的 DID-LLM 会触发告警）；页面会将用户跳转到 Stripe，并在其返回后自动继续；Agent 会获得提供给其用户的付款链接（pay_at_payment_url）（docs/card-payments.md）	完成（已在暂存环境的 Stripe 测试模式下测试；DebitMyData 于 2026-11-11 批准用于生产环境，待生产服务配置好正式密钥后启用）
卡片付款始终以美元计价：所有付款页面均关闭 Stripe 按付款人本地货币计价的功能（Adaptive Pricing，该功能会向付款人收取 2–4% 的换汇费用）；“获取 DID-LLM”会一次性说明签名格式	完成
使用密钥而非钱包拥有 DID-LLM：scripts/did-owner-key.py 会在所有者的电脑上生成 Ed25519 所有者密钥，并签署注册消息（仅限 HTTPS 网关，且不能用于其他密钥或网关），附有指南（docs/owner-key.md）；“获取 DID-LLM”第 3 步说明如何在使用工具签名后继续，并解释如何粘贴消息而非签名	完成
刷新后，“获取 DID-LLM”会将进行中的注册移入视野：滚动至该注册，将焦点移至“继续”并短暂显示发光效果（启用减少动态效果时不发光）	完成
签发后隐藏“加入 Agentic Hub”，直到 Hub 的“创建实体”保存条目（get-did.js 中的 SHOW_AGENTIC_HUB）	完成（Hub 准备就绪后再显示）
更新期间暂停监控和每日报告（deploy/*/update.sh），避免新设置被旧代码读取（不会误报“无法加载配置”）；更新结束后会重新启动，即使更新失败也一样	完成
PayPal	等待 DebitMyData 的 PayPal 账户访问权限
每日报告统计中排除公司的测试 DID-LLM（DMD_GW_REPORT_EXCLUDED_DIDS）；仅当某种支付方式的速率限制拒绝持续发生时才告警（连续检查 3 次）	完成
命名：支付方式名称为“DebitMyData coin (native PoW chain)”，其资产为 DMD；付款方式页面、价格页面、MCP 介绍和 API 指南均会解释其代号；项目、链、节点、浏览器和告警主题均使用 DebitMyData 名称	完成
生产服务部署包（deploy/production、docs/production.md）：DebitMyData 节点连接主链，仅持有金库的只读密钥；所有支付方式默认关闭，需手动启用；每晚使用离线密钥加密备份至对象存储（并监控备份）；提供上线检查清单	完成（需要生产服务）
凭证签名器（ID-15）：在生产环境中，签发者密钥仅由 dmd-gateway-signer 持有（使用独立用户、无网络），并在签名前检查数据库；API 会检查每个签名	完成
DID-LLM 目录：所有者可为 DID-LLM 添加公开个人资料（采用 Agentic Hub 字段，不含图片：类型 avatar/robot/sentient、专业领域、描述、可选的所有者姓名、地区、国家、创建日期），并像控制权证明一样使用 DID-LLM 自有密钥或钱包签名；也可以用同样方式修改或移除资料；仅限纯文本（不允许链接、电子邮件地址或隐藏字符）；仅在 DID-LLM 处于活动状态时显示；提供支持 CORS 的开放 API（GET /v1/directory、搜索、类型筛选、分页）、/directory、/directory/{id} 和 /directory/list 页面、MCP（dmd_search_directory、dmd_list_in_directory）、did-owner-key.py directory；运营者可隐藏条目（dmd-gateway-admin directory hide），监控器会报告每条新增或变更的条目；签发后，“获取 DID-LLM”会提供添加条目的入口（docs/directory.md）	完成
顶部栏宽于页面（1180 px），让所有链接（包括“目录”）在一行显示（暂存环境也一样）；较窄屏幕上的链接间距更小，并在低于 900 px 时折叠到菜单按钮中	完成
在暂存环境中，目录页面上的所有者密钥命令会指定暂存网关（DMD_GATEWAY_API=...）；如果在该网关上找不到消息，工具会说明它查询了哪个网关	完成
面向用户的目录页面统一使用应用地址（id.debitmydata.io）：在 API 地址上访问时会跳转至此（308，路径和查询参数不变），entry_url 和告警链接也会跳转至此；API 仍使用 api.debitmydata.io	完成
在“获取 DID-LLM”（第 3 步）和目录条目页面上使用密钥签名时，主要操作方式是使用所有者密钥工具的命令（附注册 ID 或消息 ID；非生产环境需设置 DMD_GATEWAY_API）并点击全尺寸的 继续 按钮；使用其他软件生成的签名可在下方展开粘贴	完成
所有者密钥工具会接收密钥文件夹（~/did-keys），并使用拥有该 DID-LLM 的密钥签名；如果没有相应密钥，工具会说明并列出找到的密钥，且不会签名；页面中的命令会指定文件夹	完成
“获取 DID-LLM”第 1 步“我的 Agent 的公钥”：说明如何使用所有者密钥工具生成密钥（使用 new 命令和指南；暂存环境还提供专用测试密钥及指南中的暂存环境说明）	完成
MCP 服务迁移至 /agenticsuperhighway，与 DebitMyData 规划中的名称一致：页面、llms.txt、发现信息（mcp_url）和 API 文档均显示新地址；原地址 /mcp 仍以相同速率限制提供服务，已记录该地址的 Agent 和目录条目可继续使用。llms.txt 会引导 Agent 前往 Agentic Spaces 创建自己的社交页面和社区	完成
浏览器打开 MCP 服务地址（/agenticsuperhighway 或 /mcp）时，会看到简短介绍页，列出提供给 MCP 客户端的地址、llms.txt、REST API 和“获取 DID-LLM”（此前会显示空事件流或空白页）。MCP 客户端收到的内容与之前完全相同；该页面绝不缓存（no-store、Vary: Accept）	完成
每台服务的 update.sh 都会根据其设置中的 DMD_GW_ENVIRONMENT，在执行任何更改前拒绝在另一台服务上运行；暂存环境的 setup.sh 也会拒绝使用生产环境设置：暂存环境的测试设置和测试密钥绝不会部署到生产环境	完成
为用户提供一个地址，为 Agent 和开发者提供另一个地址（api/hosts.py）：在 API 地址（api.debitmydata.io）上，“获取 DID-LLM”、网站根路径和政策页面会跳转至应用地址（id.debitmydata.io），与目录页面的行为一致；在应用地址上，API 文档（/docs/advanced、/redoc）会跳转至 API 地址。因此，菜单链接始终指向正确地址，已安装的应用会让用户始终留在应用内。API（/v1/...）、llms.txt、Markdown 格式的政策和 MCP 服务仍会在两个地址上响应，不迁移	完成
MCP 客户端、爬虫和注册表无需获知地址即可发现 Agentic Superhighway（api/server_card.py）：位于 /agenticsuperhighway/server-card 的 MCP Server Card（MCP 扩展 SEP-2127）提供名称、版本、功能和连接方式（不包含工具列表：服务会自行列出工具）；/.well-known/ai-catalog.json 中的 AI Catalog 会指向该卡片；此外，DebitMyData 的发现运行手册以自身格式（application/json）提供两个文件：/.well-known/mcp/server-card.json，列出服务公布的工具；以及简短清单 /.well-known/mcp；两者都指向标准卡片。server.json 会以 io.debitmydata/agenticsuperhighway 为名称将其列入官方 MCP Registry（docs/production.md）；测试会确保其内容与卡片一致	完成（该条目需要 DNS 记录）
页面上不使用下拉列表，让 AI Agent 一次看到所有选项：“获取 DID-LLM”中的“用途是什么？”选项（分为三组，均匀排列）和条目表单中的类型选项均以按钮形式显示；目录中的类型选项则以保留搜索词的链接形式显示	完成
原生 DMD 钱包证明（DEC-07）、控制者轮换和撤销	下一步
每种支付通道默认均为关闭。原生 DMD 通道可针对私有 regtest 链开启（参见 docs/regtest-demo.md）；在主网中，其定价取以下两者中的较高值：最低费率（每 DMD 0.001 USD）和 DMD 挖矿成本。它仍需要网关自有的 DebitMyData 节点及其只读接收钱包。x402 USDC 通道在暂存环境中运行于 Base Sepolia；在 Base 主网中，款项支付至 DebitMyData 的接收地址，并通过 Coinbase 的 CDP facilitator 结算，而这需要 DebitMyData 的 CDP API key（DEC-08）。暂存环境中的银行卡支付使用 Stripe 测试模式，设置受限测试密钥后即可运行；生产环境中虽已获批准，但会保持关闭，直到生产服务器设置受限的实时密钥
（docs/card-payments.md）。运行于私有 regtest 链、已启用完整流程的暂存服务器位于 https://staging-api.debitmydata.io：任何人都可以通过其引导式测试页面尝试注册，也可以按照高级 API 文档逐步操作（参见
docs/staging.md）。
任务列表和决策请参见 docs/roadmap.md。

快速开始

要求：Python 3.12+，Docker（用于 PostgreSQL）或本地 PostgreSQL 16。

Windows（PowerShell）

git clone https://github.com/DebitMyData-PoW/agent-gateway.git
cd agent-gateway
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env

docker compose up -d db
alembic upgrade head
uvicorn --factory dmd_gateway.main:create_app --reload

Linux / macOS

git clone https://github.com/DebitMyData-PoW/agent-gateway.git
cd agent-gateway
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

docker compose up -d db
alembic upgrade head
uvicorn --factory dmd_gateway.main:create_app --reload

然后打开 http://localhost:8000/docs，或：

curl http://localhost:8000/readyz
curl http://localhost:8000/v1/discovery
curl "http://localhost:8000/v1/payment-options?service=did_registration"

请求 DID-LLM 注册报价（指令中的示例请求，使用示例控制器密钥；python scripts/demo_agent.py new-key agent-key.pem 可创建真实密钥）：

curl -X POST http://localhost:8000/v1/dids/registration-quotes \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9a3b-3c5a1d2e7b90" \
  -d '{"display_name": "ResearchClaw-01", "participant_type": "autonomous_agent",
       "controller_public_key": "ed25519:z6MktwupdmLXVVqTzCw4i46r4uGyosGXRnR3XjN4Zq7oMMsw",
       "preferred_payment_option": "x402_usdc_base"}'

所有支付通道均关闭时，此请求会返回 409，并包含 "code": "payment_option_unavailable"。

注册流程

步骤	端点
查看报价和已启用的支付选项	GET /v1/discovery、GET /v1/payment-options
获取报价（固定为 25.00 USD，按所选资产支付精确金额）	POST /v1/dids/registration-quotes
支付（DMD），然后查询支付状态	GET /v1/payments/{payment_intent_id}
获取一次性消息，使用控制器密钥或钱包签名	POST /v1/dids/registrations/{registration_intent_id}/controller-challenges
提交签名	POST /v1/dids/registrations/{registration_intent_id}/controller-proofs
查看仍缺少哪些内容	GET /v1/dids/registrations/{registration_intent_id}
获取 DID-LLM、签名凭证和权益（x402：在此付款，见下文）	POST /v1/dids/registrations
可选：报告支付交易（仅作提示）	POST /v1/payments/{payment_intent_id}/references
查询信息	GET /v1/dids/{identity_id}、GET /v1/credentials/{credential_id}、GET /v1/entitlements/{identity_id}（身份 ID 或 DID-LLM 本身）
解析 DID-LLM 和发行方密钥	GET /agents/{id}/did.json、GET /.well-known/did.json
阅读条款、隐私、支付、退款、DID-LLM 和安全策略	/policies、GET /v1/policies
可选：将 DID-LLM 列入目录（由其所有者签名），或读取目录	POST /v1/directory/{did}/challenges、POST /v1/directory/{did}/proofs、GET /v1/directory

相同步骤也可通过 /agenticsuperhighway 上的 MCP 工具执行（Streamable HTTP；其第一个地址 /mcp 仍可使用）：dmd_discover、 dmd_get_did_registration_offer、dmd_list_supported_payment_options、 dmd_create_did_payment_quote、dmd_submit_payment_reference、dmd_get_payment_status、 dmd_prove_wallet_control、dmd_register_did、dmd_get_registration_status、dmd_catalog、 dmd_get_purchase_quote、dmd_purchase、dmd_marketplace_provider_requirements、 dmd_search_directory 和 dmd_list_in_directory。每个 工具都会在进程内调用上述 REST API，因此两者会返回相同的结果和错误代码。其 Server Card /agenticsuperhighway/server-card（列于 /.well-known/ai-catalog.json）会告知 MCP 客户端和注册表它是什么以及如何连接。 推理捐赠（Agent）。 使用 POST /v1/donations/inference，请求体为 {"amount_usd": "5.00"}（金额范围为 0.50 至 1,000.00 USD；可选提供 donor_name 和 donor_did），响应会以 402 返回金额恰好相同的 x402 条款，收款地址为 DebitMyData 的推理钱包（DMD_USDC_BASE_INFERENCE_ADDRESS，而非 DID-LLM 付款地址）。在 PAYMENT-SIGNATURE 中附上已签名的付款，再次发送相同请求体：无需报价，付款会像 DID-LLM 付款一样在链上验证；响应（201）包含由 DebitMyData 签名的收据（DebitMyDataDonationReceipt 凭证），或者在等待确认时返回带有 status_url 的 202（GET /v1/donations/{purchase_id}）。再次发送相同付款会返回相同的捐赠记录。通过 MCP：dmd_catalog 会列出 inference_donation，dmd_purchase 则从 details 获取金额，从 x402_payment 或 _meta["x402/payment"] 获取付款信息。/v1/discovery 的 donations 下会显示捐赠记录。

使用 x402 付款（Base 上的 USDC）。 使用 "preferred_payment_option": "x402_usdc_base" 获取报价、证明控制器密钥，然后调用 POST /v1/dids/registrations。响应会以 402 返回 PAYMENT-REQUIRED 标头（x402 版本 2，方案为 exact：报价金额以 USDC 基本单位表示，并包含 USDC 合约、网络和 DebitMyData 的收款地址，以及 Bazaar 发现说明）。在 PAYMENT-SIGNATURE 标头中附上已签名的付款，再次调用：网关会根据报价检查付款，由 facilitator 验证并结算；随后网关会自行在链上检查结算情况，并在同一响应中返回 DID-LLM 和 PAYMENT-RESPONSE 标头（如果确认耗时较长，则返回 202；此时无需付款，再次调用即可）。只有其他所有步骤都准备就绪后才会请求付款，因此 Agent 不会为无法签发的 DID-LLM 付费。任何标准 x402 客户端都可以付款；通过 MCP，dmd_register_did 会返回付款要求，并从 x402_payment 或 _meta["x402/payment"] 获取付款信息。

签发 DID-LLM 需要凭证签名密钥（DMD_GW_ISSUER_KEY_PATH，使用 dmd-gateway-issuer-key secrets/issuer-key.pem 创建）。没有该密钥时，其他功能仍可正常使用，但签发端点会返回 503。各步骤背后的规则请参阅 docs/architecture.md。

请在仓库根目录运行命令（路由注册表路径相对于该目录）。

测试

pytest                                   # unit and API tests
ruff check . && ruff format --check .    # lint

仅当 TEST_DATABASE_URL 指向一个可丢弃数据库时才会运行数据库测试（它们会删除并重建所有表）。Compose 数据库会为你创建一个：

$env:TEST_DATABASE_URL = "postgresql+psycopg://gateway:gateway-dev-only@localhost:5432/agent_gateway_test"
pytest

每次推送和拉取请求时，CI 都会运行 lint 和完整测试套件，包括数据库测试。

配置

网关设置使用 DMD_GW_ 前缀，可从环境或 .env 获取（参见 .env.example）。在 development 以外的环境中，如果网关使用开发数据库凭据或非 HTTPS 公共 URL，则会拒绝启动。

支付通道

config/payment_routes.yaml 是 Agent 付款方式的唯一事实来源。只有满足所有以下条件，通道才会启用：

1. 由 enable_env 指定的启用标志（例如 DMD_RAIL_DMD_POW_NATIVE_ENABLED）为 true（1/true/yes/on）；
2. 由 kill_env 指定的熔断开关未设置，或值为 0/false/no/off；
3. 它在注册表中已标记为 approved；
4. 已设置规范资产身份和确认/最终性策略；
5. 对于非 USD 资产，价格策略完整（包括已批准的数据源、最长价格时效、 允许的价格偏差和回退机制），且已实现其价格数据源；
6. 已配置收款目的地；
7. 已实现其支付适配器；
8. 仅适用于 x402 通道：使用 exact 方案和 EIP-3009 转账，设置代币的 EIP-712 域、 确认次数及其 facilitator 和链 RPC 地址 （DMD_X402_FACILITATOR_URL、DMD_BASE_RPC_URL）。Coinbase 的 CDP facilitator （https://api.cdp.coinbase.com/platform/v2/x402）还需要可用的 CDP API 密钥 （DMD_X402_CDP_API_KEY_ID、DMD_X402_CDP_API_KEY_SECRET）。

生产环境中会拒绝使用测试网络（DebitMyData regtest/testnets、Base Sepolia）的通道。

如果启用了某个通道，但未满足第 3–8 项，网关会拒绝启动，而不是以未完整配置的状态运行该通道。熔断开关采用故障安全策略：任何无法识别的值都会被视为 “已熔断”。熔断开关在启动时读取，因此切换开关后需重启才能生效。 /v1/payment-options 只会列出已启用的通道，因此 API 绝不会宣传无法实际验证的支付方式。

支付工作进程

支付由独立进程跟踪，该进程会监视已启用通道上的每笔未完成支付，并将其依次转换为规范化状态：

dmd-gateway-worker          # runs until stopped
dmd-gateway-worker --once   # one pass

节点无法访问时，它绝不会更改支付状态，且可安全地同时运行多个工作进程。要在私有链上尝试完整流程，从报价到 DID-LLM，请参阅 docs/regtest-demo.md。

项目布局

config/payment_routes.yaml   payment rails, services, commercial price (no secrets)
config/payment_routes.regtest.yaml   the same, on test networks (DebitMyData regtest, Base Sepolia)
deploy/staging/              staging server setup (nginx, systemd services, Cloudflare-only firewall)
deploy/production/           production server setup, signer and backup units, nightly backup
server.json                  the MCP server's listing in the official MCP Registry
migrations/                  Alembic migrations (hand-reviewed)
src/dmd_gateway/
  main.py                    application factory
  mcp_server.py              MCP tools at /agenticsuperhighway, calling the REST API in-process
  worker.py                  payment worker (dmd-gateway-worker), also refreshes the DMD price
  monitoring/                health checks, email/Discord alerts, daily reconciliation report
                             (dmd-gateway-monitor)
  identity/                  controller keys, did:web documents, issuer key, signed credentials
  signer/                    the production credential signer (dmd-gateway-signer) and its client
  runtime.py                 registry, adapters and price sources shared by API and worker
  settings.py                environment configuration
  observability.py           JSON logging, correlation IDs
  audit.py                   append-only audit helper
  api/                       HTTP routes
  adapters/                  payment adapters (native DMD, x402 USDC), restricted RPC clients,
                             x402 facilitator client
  pricing/                   price-source rules and the DMD mining-cost price
  services/                  quotes, settlement, payment references, controller proofs,
                             registrations, x402 payments, donations, staging test tools
  db/                        SQLAlchemy models and session handling
  domain/                    money, ids, payment states, settlement rules, issuance rule, registry
scripts/demo_agent.py        agent side for demos: key, signature, credential check, MCP client
scripts/did-owner-key.py     owner key for a DID-LLM without a wallet (docs/owner-key.md)
scripts/load_test.py         load test: requests per second and response times
tests/
docs/                        architecture, roadmap, operator checklists

将网关连接到任何 DebitMyData 节点之前，请通过 docs/sec-04-rpc-isolation.md 验证该节点的 RPC 隔离情况。

基本规则

以下规则适用于此代码库中的每项更改：

• 不要修改 DebitMyData 共识代码来支持网关功能。
• 绝不要公开 DebitMyData Core RPC，也不要转发任意 RPC 方法。
• 绝不要向调用方提供私钥、助记词、钱包解锁功能或不受限制的签名能力。
• 网关主机上不得存放金库密钥或支出密钥；支付跟踪仅限观察。
• 绝不要仅凭资产代码接受资产；必须匹配链 ID + 规范合约/标识符。
• 绝不要使用二进制浮点数处理货币或代币金额。
• 只有在支付状态为 settled、控制者证明为 verified、策略检查通过，且注册意图有效且未使用时，才能签发身份。
• 绝不要在源代码、工单、日志或聊天中放入机密信息。.env 文件已加入 Git 忽略列表。
• 公开文档只描述实际已启用并经过验证的通道。

报告安全问题

请私下报告漏洞，绝不要在公开议题中披露。请参阅 SECURITY.md。

数据库说明

audit_events、payment_events、credited_outputs、controller_proofs 和 payment_references 均为仅追加表：数据库触发器会拒绝 UPDATE、DELETE 和 TRUNCATE。credited_outputs 以 (network, transaction, output index) 作为主键，因此一笔支付的输出只能记入一个 意图。在预发布和生产环境中，应使用独立的所有者角色运行迁移，并让应用以仅拥有所需权限的角色连接数据库。