{"_id":"@agentxv2/payments","_rev":"5-33041f87ebb9db5940b2e1fa36078071","name":"@agentxv2/payments","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@agentxv2/payments","version":"0.1.0","license":"MIT","_id":"@agentxv2/payments@0.1.0","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"dist":{"shasum":"3c254827d1ee098bdca2f1d4c60ba1d2d8652f8c","tarball":"https://registry.npmjs.org/@agentxv2/payments/-/payments-0.1.0.tgz","fileCount":28,"integrity":"sha512-UsaZU8JrS19TEVJ8RS6N0bx5ohJHpl4i/1+7mV86xS7/4FotNdwsbsi4UODq9ZGpCgTlUcbBksnGnrvnCB/6lA==","signatures":[{"sig":"MEYCIQCVUnajCfa+YXtVCYo6FrSFw23xk+lNWniMhmI1FHReNAIhALDDGPDw1k+F73Ok4ML4nr9FSnFJ/U7bbKzDqxySmWFJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":94111},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./db/*":"./db/*","./router":{"types":"./dist/router.d.ts","import":"./dist/router.js","require":"./dist/router.js"},"./package.json":"./package.json"},"gitHead":"9dd730383c7ff4dcd8f9b4a069c2c525bd8fd23f","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"_npmVersion":"10.8.2","description":"AgentX Payments — zero-AgentX-dependency payment engine (chain / Stripe / x402 / MPP / a2a). Embedded service or standalone library.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"pg":"^8.13.0","viem":"^2.55.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.9","express":"^4.19.2","@types/pg":"^8.11.10","typescript":"^5.5.0","@types/node":"^22.0.0","@types/express":"^4.17.21"},"peerDependencies":{"express":">=4"},"peerDependenciesMeta":{"express":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/payments_0.1.0_1786049489537_0.04642568748794229","host":"s3://npm-registry-packages-npm-production"},"deprecated":"已迁移至 @0xinfrax/payments（能力一致，仅依赖来源变化）"},"0.2.0":{"name":"@agentxv2/payments","version":"0.2.0","license":"MIT","_id":"@agentxv2/payments@0.2.0","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"dist":{"shasum":"b1d2515d7fb36a359af5a60b6f222d3867e617ac","tarball":"https://registry.npmjs.org/@agentxv2/payments/-/payments-0.2.0.tgz","fileCount":37,"integrity":"sha512-NPL9iQso8/UuHZdPtebS6bsGKS4B7U5HaumwvGZz7cgxWXGcMH9WL7wDirwR4rV5JMs/rmBnY48KHozvxOy/Qw==","signatures":[{"sig":"MEYCIQCctcvSyQuthujHKF3UAFA21JWur7CukM+wvMWsTJEXKgIhANcalWgmlwte9enE9Iz0fYGBOhkLniSGQN7cRnXxUpXd","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":175427},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./db/*":"./db/*","./router":{"types":"./dist/router.d.ts","import":"./dist/router.js","require":"./dist/router.js"},"./package.json":"./package.json"},"gitHead":"9dd730383c7ff4dcd8f9b4a069c2c525bd8fd23f","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"_npmVersion":"10.8.2","description":"AgentX Payments — zero-AgentX-dependency payment engine (chain / Stripe / x402 / MPP / a2a). Embedded service or standalone library.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"pg":"^8.13.0","viem":"^2.55.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.9","express":"^4.19.2","@types/pg":"^8.11.10","typescript":"^5.5.0","@types/node":"^22.0.0","@types/express":"^4.17.21"},"peerDependencies":{"express":">=4"},"peerDependenciesMeta":{"express":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/payments_0.2.0_1786055641497_0.40158802212966815","host":"s3://npm-registry-packages-npm-production"},"deprecated":"已迁移至 @0xinfrax/payments（能力一致，仅依赖来源变化）"},"0.2.1":{"name":"@agentxv2/payments","version":"0.2.1","license":"MIT","_id":"@agentxv2/payments@0.2.1","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"dist":{"shasum":"6f5279cf720cd1f9726b74964fd0097abfe05bec","tarball":"https://registry.npmjs.org/@agentxv2/payments/-/payments-0.2.1.tgz","fileCount":39,"integrity":"sha512-sQIfz6bMkqMVsgd46Xc1eOEDH4APQDiDnZiNPb8GYS6FcH0mV81jIgyY7so7xD7tPi+RLegN/IQtldQiiA3org==","signatures":[{"sig":"MEUCIAt7PwB9GRXHWo3v2vKxdLIB3hp8Fh0bQZAS6R5JlR7hAiEAryGHhYRRpM8HBj7y2B6Km8r9uBGTohi5pja2fh8SPp8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":180465},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./db/*":"./db/*","./router":{"types":"./dist/router.d.ts","import":"./dist/router.js","require":"./dist/router.js"},"./package.json":"./package.json"},"gitHead":"b9dfc56288195e381f42b00252e73330e734f7c3","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"_npmVersion":"10.8.2","description":"AgentX Payments — zero-AgentX-dependency payment engine (chain / Stripe / x402 / MPP / a2a). Embedded service or standalone library.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"pg":"^8.13.0","viem":"^2.55.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.9","express":"^4.19.2","@types/pg":"^8.11.10","typescript":"^5.5.0","@types/node":"^22.0.0","@types/express":"^4.17.21"},"peerDependencies":{"express":">=4"},"peerDependenciesMeta":{"express":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/payments_0.2.1_1786058244380_0.6939425073743575","host":"s3://npm-registry-packages-npm-production"},"deprecated":"已迁移至 @0xinfrax/payments（能力一致，仅依赖来源变化）"},"0.2.2":{"name":"@agentxv2/payments","version":"0.2.2","keywords":["agentx","payments","x402","payment-channel","mpp","a2a","stablecoin","stripe","web3"],"author":{"url":"sftgroup","name":"AgentX"},"license":"MIT","_id":"@agentxv2/payments@0.2.2","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"homepage":"https://github.com/sftgroup/Agentx/tree/main/payments","bugs":{"url":"https://github.com/sftgroup/Agentx/issues"},"dist":{"shasum":"1fbd8f7a4d32f00b920404bcc16ab8d70d884833","tarball":"https://registry.npmjs.org/@agentxv2/payments/-/payments-0.2.2.tgz","fileCount":39,"integrity":"sha512-jGN6vVRsCpyypf6KoJONor+SfhwQzTjOtlXX3aEst2Sv6pAumFn655tLmkNpJga9Q6+lSLxdfqD/SYFy3SN54g==","signatures":[{"sig":"MEYCIQDdoTAiYCZ7ayhCsMIQRzkVI1oN5ucJy7sNHu7OjNg/IwIhANNJv1c+UERPs5DkDi3qogLoccN69S8E48iGTolW5vy2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":181248},"main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"},"./db/*":"./db/*","./router":{"types":"./dist/router.d.ts","import":"./dist/router.js","require":"./dist/router.js"},"./package.json":"./package.json"},"gitHead":"57ac61599281a612d5c1623214b341c4c33b0830","scripts":{"test":"vitest run","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"repository":{"url":"git+https://github.com/sftgroup/Agentx.git","type":"git"},"_npmVersion":"10.8.2","description":"AgentX Payments — zero-AgentX-dependency payment engine (chain / Stripe / x402 / MPP / a2a). Embedded service or standalone library.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"pg":"^8.13.0","viem":"^2.55.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.9","express":"^4.19.2","@types/pg":"^8.11.10","typescript":"^5.5.0","@types/node":"^22.0.0","@types/express":"^4.17.21"},"peerDependencies":{"express":">=4"},"peerDependenciesMeta":{"express":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/payments_0.2.2_1786063830981_0.4236789311672684","host":"s3://npm-registry-packages-npm-production"},"deprecated":"已迁移至 @0xinfrax/payments（能力一致，仅依赖来源变化）"}},"time":{"created":"2026-08-06T20:51:29.358Z","modified":"2026-08-09T21:48:27.226Z","0.1.0":"2026-08-06T20:51:29.676Z","0.2.0":"2026-08-06T22:34:01.690Z","0.2.1":"2026-08-06T23:17:24.513Z","0.2.2":"2026-08-07T00:50:31.123Z"},"bugs":{"url":"https://github.com/sftgroup/Agentx/issues"},"author":{"url":"sftgroup","name":"AgentX"},"license":"MIT","homepage":"https://github.com/sftgroup/Agentx/tree/main/payments","keywords":["agentx","payments","x402","payment-channel","mpp","a2a","stablecoin","stripe","web3"],"repository":{"url":"git+https://github.com/sftgroup/Agentx.git","type":"git"},"description":"AgentX Payments — zero-AgentX-dependency payment engine (chain / Stripe / x402 / MPP / a2a). Embedded service or standalone library.","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"readme":"# @agentxv2/payments\n\n零业务耦合的通用支付引擎（chain / Stripe / x402 / MPP 支付通道 / 稳定币 / period 授权制 / a2a-pay）。\n\n> **维护**：由 **AgentX**（GitHub [sftgroup/Agentx](https://github.com/sftgroup/Agentx)）团队维护；源码位于仓库 [`payments/`](https://github.com/sftgroup/Agentx/tree/main/payments) 目录，npm 包 `@agentxv2/payments` 由 AgentX 账号发布与维护。集成方可作为独立库使用，但问题的修复与演进统一由 AgentX 负责。\n\n> **集成到独立项目**：完整部署步骤（安装 / 数据库 / 合约 / 代码接入 / 验证 / 生产注意）见 [`DEPLOY.md`](./DEPLOY.md)。\n\n- **嵌入式服务**：作为宿主 Gateway 的内部引擎（AgentX 当前用法，见 `gateway/src/services/payments.ts`）\n- **独立库**：可被任意项目依赖，以「调用方自持 store」的形态独立运行\n\n核心设计：**模块只懂钱**（方法 / 资产 / 金额 / 凭证）。业务上下文（如 `agentId`、订单号）一律经 `metadata` 透传；持久化走注入的 `PaymentStore` 接缝；宿主业务（订阅注册、发货、授权）只通过 `onWebhookEvent` / `onCredit` 回调接入。模块不解释、不校验、不消费任何业务参数。\n\n依赖仅有 `pg`（账本/凭证）与 `viem`（链上读写）。\n\n---\n\n## 目录\n\n- [依赖配置（迁移到其他项目）](#依赖配置迁移到其他项目)\n- [数据库迁移](#数据库迁移)\n- [快速开始（独立库形态）](#快速开始独立库形态)\n- [嵌入式形态（宿主自带 store / 回调）](#嵌入式形态宿主自带-store--回调)\n- [业务上下文透传规则](#业务上下文透传规则)\n- [API 参考](#api-参考)\n- [本地验证](#本地验证)\n- [目录结构](#目录结构)\n\n---\n\n## 依赖配置（迁移到其他项目）\n\n### 1. package.json\n\n```jsonc\n{\n  \"dependencies\": {\n    \"@agentxv2/payments\": \"file:../payments\" // 或 git / 私有 registry，见下\n    // pg / viem 是模块的传递依赖，npm install 会自动安装，宿主无需显式声明\n  }\n}\n```\n\n> 若宿主自身也要用 `viem` 发交易（链上/ x402 付款），可另行声明自己版本的 `viem`——模块会从自身 `node_modules` 解析，互不冲突。\n\n### 2. 三种安装来源\n\n| 场景 | package.json 写法 |\n| --- | --- |\n| Monorepo / 本地开发 | `\"@agentxv2/payments\": \"file:../payments\"` |\n| Git 仓库（打 tag 固定版本） | `\"@agentxv2/payments\": \"git+https://github.com/<org>/payments.git#v0.2.0\"` |\n| 私有 npm registry | `\"@agentxv2/payments\": \"^0.2.0\"`（配合 `.npmrc` 指向 registry） |\n\n### 3. 使用前构建\n\n发布物是 `tsc` 产物（`dist/`）。`file:` 引用前需确保已构建：\n\n```bash\ncd payments && npm install && npm run build\n```\n\n---\n\n## 数据库迁移\n\n模块拥有自己的 `payment_*` 表（5 个迁移文件，随包发布在 `db/migrations/`）：\n\n| 迁移 | 表 | 用途 |\n| --- | --- | --- |\n| `001_payment_intents.sql` | `payment_intents` | 统一支付意图（chain / fiat / x402 / mpp / a2a） |\n| `002_payment_credits.sql` | `payment_credits` / `payment_balances` / `payment_access` | 入账台账、余额、通用访问登记表 |\n| `003_payment_sessions.sql` | `payment_sessions` / `payment_vouchers` | MPP 通道会话 / 凭证 |\n| `004_payment_events.sql` | `payment_events` | 归一化 webhook 事件回放 |\n| `005_payment_authorizations.sql` | `payment_authorizations` | period 授权制订阅（一次性预授权 n 期，无重签） |\n\n在**新项目自己的数据库**中执行（不要复用其他项目的表）：\n\n```bash\nfor f in node_modules/@agentxv2/payments/db/migrations/*.sql; do\n  psql \"$DATABASE_URL\" -f \"$f\"\ndone\n```\n\n通用形态使用 `PgPaymentStore`（读这些表）。如果宿主已有自己的订阅/余额表，可自定义实现 `PaymentStore` 注入（见[嵌入式形态](#嵌入式形态宿主自带-store--回调)），此时可不执行模块迁移。\n\n---\n\n## 快速开始（独立库形态）\n\n```ts\nimport { Pool } from 'pg'\nimport { PaymentsService, PgPaymentStore } from '@agentxv2/payments'\n\nconst pool = new Pool({ connectionString: process.env.DATABASE_URL })\n\nconst payments = new PaymentsService({\n  store: new PgPaymentStore(pool),\n\n  // 链上：每个 slot 一条（可读链上套餐价 / 订阅状态）\n  chains: {\n    sepolia: {\n      rpcUrl: process.env.RPC_URL,\n      chainId: 11155111,\n      subscriptionManager: process.env.SUBSCRIPTION_MANAGER, // 部署好的 SubscriptionManager\n    },\n  },\n\n  // 法币：不配则 fiat 轨返回「未配置」（503）\n  stripe: {\n    secretKey: process.env.STRIPE_SECRET_KEY,\n    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,\n    apiBase: process.env.STRIPE_API_BASE,   // 可选，默认 https://api.stripe.com/v1；本地 mock 用 http://127.0.0.1:8777/v1\n    tokenUsdPrice: 1,                        // 可选，默认 1：native 单价 → 用于套餐自动定价\n  },\n\n  // x402：不配则 verify 返回「未配置」\n  x402: {\n    enabled: true,\n    payTo: process.env.X402_PAY_TO,          // 平台收款钱包\n    priceWei: process.env.X402_PRICE_WEI,    // 单次价格（周期支付最低门槛）\n    chain: 'sepolia',\n  },\n\n  // ── 宿主业务只写在这里 ──────────────────────────────────────────────\n  // webhook 事件（Stripe）→ 你的业务：开订阅、发凭证、写订单\n  onWebhookEvent: async (event) => {\n    if (event.type === 'checkout.session.completed') {\n      const [subscriber, resourceId] = String(event.object.client_reference_id ?? '').split('|')\n      await grantAccess(subscriber, resourceId) // 例如写 payment_access 或你自己的表\n    }\n  },\n  // 链上付款验证成功入账后（x402 轨）→ 你的业务\n  onCredit: async (credit) => {\n    await notifyUser(credit.payer, credit.amountWei)\n  },\n})\n```\n\n### 三个轨的典型用法\n\n```ts\n// ① 链上：用户先在链上调用 SubscriptionManager.subscribe(planId)，然后：\nconst active = await payments.chain.hasActiveSubscription('sepolia', subscriber, agentId)\nconst plan = await payments.chain.getPlan('sepolia', planId) // 定价、套餐详情\nconst feeBps = await payments.chain.platformFeeBps('sepolia')\n\n// ② 法币：创建 Stripe Checkout Session（可自动定价）\nconst checkout = await payments.createPayment({\n  method: 'fiat',\n  subscriber,\n  period: 'month',\n  pricing: { planId },                    // 省略 amountCents → 按链上套餐价换算\n  metadata: { agentId, planId },          // 业务参数原样透传\n  clientReference: `${subscriber}|${agentId}|${planId}`, // 由你构造，webhook 原样回显\n})\n// → { method:'fiat', sessionUrl, sessionId, clientReference, redirect:true }\n\n// ③ x402：用户向 payTo 转账后验证入账（幂等）\nconst verified = await payments.verifyPayment(txHash, 'sepolia')\n// → { reference, payer, creditedWei, asset, chain } 或 null（非有效支付）\nconst balance = await payments.balanceOf(subscriber) // 模块账本余额\n```\n\n### Webhook 路由（需要 rawBody）\n\n```ts\napp.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf } }))\n\napp.post('/webhooks/stripe', async (req, res) => {\n  try {\n    await payments.handleWebhook(req.rawBody.toString(), req.headers['stripe-signature'])\n    res.json({ received: true })\n  } catch (err) {\n    res.status(400).json({ error: err.message }) // 签名无效 → 'Invalid signature'\n  }\n})\n```\n\n### 访问检查\n\n```ts\n// 通用 store 只查 payment_access 登记表；「链上 OR 链下」的统一策略由你的 store 实现决定\nconst access = await payments.resolveAccess(subscriber, { agentId }, { chain: 'sepolia' })\n```\n\n### 可选：现成 Express router（版本 A 推荐）\n\n`@agentxv2/payments/router` 提供了覆盖全部端点（`/info` `/price` `/checkout` `/verify` `/webhook` `/balance` `/access`）的现成 router，挂载即用：\n\n```ts\nimport { createPaymentsRouter } from '@agentxv2/payments/router'\n\napp.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf } })) // webhook 需要 rawBody\napp.use('/payments', createPaymentsRouter(payments))\n```\n\n`express` 是 optional peer 依赖：不调用 `createPaymentsRouter` 就不需要它。\n\n---\n\n## 嵌入式形态（宿主自带 store / 回调）\n\n模块的所有持久化都走 `PaymentStore` 接口，宿主可注入自己的表：\n\n```ts\nimport { PaymentsService } from '@agentxv2/payments'\nimport type { PaymentStore, PaymentCredit } from '@agentxv2/payments'\n\nclass MyStore implements PaymentStore {\n  balanceOf(address, asset) { /* 读你的余额表 */ }\n  credit(credit: PaymentCredit) { /* 幂等入账 */ }\n  isCreditRecorded(reference) { /* 幂等探针 */ }\n  deduct(address, amount, asset) { /* 扣减，返回是否充足 */ }\n  resolveAccess(subscriber, resource, opts) { /* 你的统一访问策略 */ }\n}\n\nconst payments = new PaymentsService({ store: new MyStore(), chains, stripe, x402, ... })\n```\n\nAgentX 自身即此形态的参考实现：\n\n- 组装：`gateway/src/services/payments.ts`（env → 模块配置）\n- 自定义 store + 事件桥：`gateway/src/services/payments-bridge.ts`（`AgentxPaymentStore` 覆盖 `fiat_subscriptions` / `x402_*` 表，`PaymentsBridge` 把模块 webhook 事件落到业务订阅表）\n\n---\n\n## 业务上下文透传规则\n\n1. **`metadata`**：业务参数（`agentId` / `planId` / 订单号…）放这里，模块原样落 `payment_intents.metadata`（JSONB），不解释、不校验、不消费。\n2. **`clientReference`**（fiat）：由调用方构造的透明引用（如 `subscriber|agentId|planId`），模块转发给 Stripe 并在结果与 webhook 事件中原样回显；解析它属于宿主业务。\n3. **访问策略**：`resolveAccess` 的语义由注入的 store 决定（通用 `PgPaymentStore` 只查 `payment_access`；AgentX 的 store 是「链上 OR fiat/x402」）。模块不感知。\n\n---\n\n## API 参考\n\n| 成员 | 说明 |\n| --- | --- |\n| `PaymentsService.createPayment(input)` | 创建支付意图（fiat checkout / x402 订阅 / MPP open / a2a create） |\n| `PaymentsService.verifyPayment(txHash, chain?)` | 验证链上付款并幂等入账（原生优先，失败回退 stablecoin EIP-3009） |\n| `PaymentsService.handleWebhook(payload, signature)` | 校验 Stripe 签名 → 归一化事件 → 调 `onWebhookEvent` |\n| `PaymentsService.resolveAccess(subscriber, resource, opts?)` | 委托 store 的访问检查 |\n| `PaymentsService.balanceOf / deduct` | 余额查询 / 原子扣减（委托 store） |\n| `PaymentsService.chain` | `ChainAdapter`：`getPlan` / `hasActiveSubscription` / `platformFeeBps` |\n| `PaymentsService.stripe` | `StripeAdapter`：`createCheckoutSession` / `verifyWebhookSignature` / `parseEvent` |\n| `PaymentsService.x402` | `X402Adapter`：`verifyAndCredit` / `balanceOf` / `deduct` / `paymentRequiredHeaders` |\n| `PaymentsService.mpp` | `MPPAdapter`：`open` / `voucher` / `topUp` / `settle` / `close` / `session`（支付通道） |\n| `PaymentsService.mppVoucher / mppTopUp / mppSettle / mppClose / mppSession` | MPP 通道操作（服务层薄封装） |\n| `PaymentsService.chargePeriod(authorizationId)` | period 授权制：原子扣一期（幂等，耗尽标记 exhausted） |\n| `PaymentsService.getAuthorization(authorizationId)` | 查询授权（owner / 剩余 / 期数 / 状态） |\n| `PgPaymentStore` | 通用 Postgres store（`payment_*` 表） |\n| `PgMPPSessionStore` / `PgAuthorizationStore` | MPP 通道 / period 授权的 Pg 实现（可选，注入到 Options） |\n| `updateIntentStatus(paymentId, status)` | 推进 intent 生命周期（`created→paid/failed/closed`）；x402 由 verifyPayment 自动置 `paid`，fiat 由宿主在回调里驱动 |\n| `PaymentError` / `isPaymentError` | 带 `code` + 建议 `status` 的类型化错误（宿主按码映射 HTTP） |\n| `createPaymentsRouter` | 现成 Express router（`@agentxv2/payments/router`） |\n| `X402Client` / `PaymentsClient` / `MPPClient` / `A2AClient` / `PeriodClient` | 面向任意部署点的 HTTP 客户端 |\n| `buildVoucherMessage` / `recoverEIP3009Signer` / `recoverPermit2Signer` | EIP-712 协议 helper（MPP voucher / 稳定币双机制） |\n| `buildPaymentMessage` / `encodeHeader` / `decodeHeader` | x402 v2 协议 helper（PaymentRequired / PaymentPayload / PaymentResponse） |\n\n类型集中在 `types.ts`：`PaymentMethod`、`CreatePaymentInput / CreatePaymentResult`、`PaymentCredit`、`VerifiedPayment`、`WebhookEvent`、`PlanInfo`、`X402Info`、`MPPSessionRow`、`PaymentAuthorization` 等。\n\n---\n\n## 本地验证\n\n仓库内置两套本地 harness（需 docker，无需 Stripe 账号、无需真实链）：\n\n| 脚本 | 验证对象 | 说明 |\n| --- | --- | --- |\n| `scripts/local-payments/run.sh` | 嵌入式形态（B） | 起 postgres+anvil → 部署合约（含 MockUSDC）→ 起 gateway → `FLOWS=\"f1 f4 f5 f6 f7 f8\"` 全绿（F1-3 三轨订阅 / F4 x402 v2 / F5 MPP / F6 稳定币 EIP-3009 / F7 period 授权制 / F8 a2a-pay） |\n| `scripts/local-payments/run-decouple.sh` | 独立库形态（A） | 只 import 模块自身 + 独立 `agentx_payments` 库，证明零 AgentX 耦合，19 项断言 |\n| `npm test` | 单测 | 9 个文件 87 项断言（协议 / 适配器 / service / router / 错误码） |\n\n解耦验证断言示例：模块入口必须从自身 `dist/` 解析、依赖仅 `pg,viem`、src/dist 无 `fiat_subscriptions` / `x402_*` / `@agentxv2/sdk` 等业务 token、DB 仅 `payment_*` 表。\n\n---\n\n## 目录结构\n\n```\npayments/\n├── package.json            # @agentxv2/payments, deps: pg + viem\n├── tsconfig.json\n├── db/migrations/          # 001-005（模块自有 payment_* 表）\n├── src/\n│   ├── index.ts            # 公共入口\n│   ├── types.ts            # 通用类型（metadata 透传约定）\n│   ├── errors.ts           # PaymentError{code,status}\n│   ├── service.ts          # PaymentsService（引擎 + 回调接缝）\n│   ├── store.ts            # PaymentStore 接口 + PgPaymentStore + PgMPPSessionStore + PgAuthorizationStore\n│   ├── client.ts           # X402Client / PaymentsClient / MPPClient / A2AClient / PeriodClient\n│   ├── router.ts           # createPaymentsRouter（express 为 optional peer）\n│   ├── protocol/\n│   │   ├── x402-v2.ts      # PaymentRequired / PaymentPayload / PaymentResponse（EIP-712）\n│   │   ├── mpp-voucher.ts  # MPP voucher（EIP-712，channelId 确定性公式）\n│   │   └── stablecoin.ts   # EIP-3009 + Permit2 验签 helper\n│   └── adapters/\n│       ├── chain.ts        # 链上只读（getPlan / hasActiveSubscription）\n│       ├── stripe.ts       # Stripe 协议层（可配 apiBase 指向 mock）\n│       ├── x402.ts         # 原生代币付款验证 + 入账（stablecoin fallback）\n│       ├── mpp.ts          # MPP 通道（open/voucher/topUp/settle/close/session）\n│       └── stablecoin.ts   # EIP-3009 Transfer 事件入账验证\n```\n","readmeFilename":"README.md"}