{"_id":"@accord-protocol/rails-x402","_rev":"3-fc4ffa0753e17ef5e184f23cc0f4f8a5","name":"@accord-protocol/rails-x402","dist-tags":{"latest":"0.4.2"},"versions":{"0.4.0":{"name":"@accord-protocol/rails-x402","version":"0.4.0","keywords":["accord-protocol","rails","x402","http-402","facilitator","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","_id":"@accord-protocol/rails-x402@0.4.0","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"homepage":"https://github.com/accord-protocol/accord-protocol/tree/main/packages/accord-rails-x402","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dist":{"shasum":"a3588509f74862abd9f68cf86ac42b85dad34a4c","tarball":"https://registry.npmjs.org/@accord-protocol/rails-x402/-/rails-x402-0.4.0.tgz","fileCount":6,"integrity":"sha512-/hUlwpbkpLvpVMK/pDhYYi61ulI0eMjSVm6bKWbZ5Tg7HAiYMCXlu37KoFO9cuDMQZCx4qNU53CljT56Ls08yQ==","signatures":[{"sig":"MEYCIQC/EgslpUBKilaajJCq3P8FBkmt11R88M06/eWUhZGU7wIhAOCeRWj2PKZPINwIxN2cjkY3ZZnpxvP+K4PVOPVPCt5j","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24404},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"3de0b386d2e83302cac87206d198a8a799b6baa8","scripts":{"test":"npx tsx --test src/__tests__/*.test.ts","build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"},"repository":{"url":"git+https://github.com/accord-protocol/accord-protocol.git","type":"git","directory":"packages/accord-rails-x402"},"_npmVersion":"10.9.4","description":"Accord rail adapter for x402-compatible HTTP payments. Wraps any x402 facilitator (Coinbase, custom) into the AccordRailAdapter shape so x402 endpoints can settle Accord agreements atomically (pay_before_response).","directories":{},"_nodeVersion":"22.21.1","dependencies":{"@accord-protocol/core":"^0.4.0","@accord-protocol/rails":"^0.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/rails-x402_0.4.0_1778775563229_0.3299248712456686","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@accord-protocol/rails-x402","version":"0.4.1","keywords":["accord-protocol","rails","x402","http-402","facilitator","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","_id":"@accord-protocol/rails-x402@0.4.1","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"homepage":"https://github.com/accord-protocol/accord-protocol/tree/main/packages/accord-rails-x402","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dist":{"shasum":"d07894cc9d7977b3bfabae45046d66f3fd1c6b44","tarball":"https://registry.npmjs.org/@accord-protocol/rails-x402/-/rails-x402-0.4.1.tgz","fileCount":6,"integrity":"sha512-znAlIfRh2X/1I+mtcWICk4qZGCsrvfvrsyAKGn21vBJkJuzj2iOvmJ5Dh4VGFaJKtTeyzC0pM458ia17PuLq6Q==","signatures":[{"sig":"MEUCIBUx2rgvDGGs2I6tfFyE6trGFxpfiZksiYk92wuqkG5SAiEAhBz2zGIH7d++7/undCa8L7dt25+GyZj9OAynX316E3w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@accord-protocol%2frails-x402@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":24412},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"e42de427235ef205df05351fb51e607b159d23b6","scripts":{"test":"npx tsx --test src/__tests__/*.test.ts","build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:297d952e-0cf4-4f16-bac1-2abcc8cf0068"}},"repository":{"url":"git+https://github.com/accord-protocol/accord-protocol.git","type":"git","directory":"packages/accord-rails-x402"},"_npmVersion":"11.14.1","description":"Accord rail adapter for x402-compatible HTTP payments. Wraps any x402 facilitator (Coinbase, custom) into the AccordRailAdapter shape so x402 endpoints can settle Accord agreements atomically (pay_before_response).","directories":{},"_nodeVersion":"24.15.0","dependencies":{"@accord-protocol/core":"^0.4.1","@accord-protocol/rails":"^0.4.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","tsup":"^8.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/rails-x402_0.4.1_1778872901360_0.2566441540572324","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@accord-protocol/rails-x402","version":"0.4.2","description":"Accord rail adapter for x402-compatible HTTP payments. Wraps any x402 facilitator (Coinbase, custom) into the AccordRailAdapter shape so x402 endpoints can settle Accord agreements atomically (pay_before_response).","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --clean","typecheck":"tsc --noEmit","test":"npx tsx --test src/__tests__/*.test.ts"},"keywords":["accord-protocol","rails","x402","http-402","facilitator","agent-payments","rail-adapter"],"author":{"name":"bez111"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/accord-protocol/accord-protocol.git","directory":"packages/accord-rails-x402"},"homepage":"https://accordprotocol.ai/learn/accord-vs-x402/","bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"dependencies":{"@accord-protocol/core":"^0.4.2","@accord-protocol/rails":"^0.4.2"},"devDependencies":{"@types/node":"^20.0.0","tsup":"^8.0.0","tsx":"^4.0.0","typescript":"^5.0.0"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"gitHead":"437febb0a70b3162d4b10b19874f1a0026a59bdf","_id":"@accord-protocol/rails-x402@0.4.2","_nodeVersion":"24.15.0","_npmVersion":"11.15.0","dist":{"integrity":"sha512-vK3Qqbx4rVZW7ZU8MR1H67enVcqtDqGCnRgLA6yqlr1/P0sr3+nD3VuDuugJnZgdHhGYHA5IcUa+kaikRuSJUw==","shasum":"f1dea9ecacf0cbe76429eb0c833b572284e6aa1f","tarball":"https://registry.npmjs.org/@accord-protocol/rails-x402/-/rails-x402-0.4.2.tgz","fileCount":6,"unpackedSize":24750,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@accord-protocol%2frails-x402@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBCrs4xQBVsqjve57r0rtYjWCzEujr0hLX9DqRV97TyuAiEA+ieOj/Lx5ANaQcHlx1XtMV8GS6iWDw7fD8N/Wk1yrbY="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:297d952e-0cf4-4f16-bac1-2abcc8cf0068"}},"directories":{},"maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rails-x402_0.4.2_1779582062099_0.3416610525553563"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T16:19:23.168Z","modified":"2026-05-24T00:21:02.560Z","0.4.0":"2026-05-14T16:19:23.383Z","0.4.1":"2026-05-15T19:21:41.522Z","0.4.2":"2026-05-24T00:21:02.247Z"},"bugs":{"url":"https://github.com/accord-protocol/accord-protocol/issues"},"author":{"name":"bez111"},"license":"MIT","homepage":"https://accordprotocol.ai/learn/accord-vs-x402/","keywords":["accord-protocol","rails","x402","http-402","facilitator","agent-payments","rail-adapter"],"repository":{"type":"git","url":"git+https://github.com/accord-protocol/accord-protocol.git","directory":"packages/accord-rails-x402"},"description":"Accord rail adapter for x402-compatible HTTP payments. Wraps any x402 facilitator (Coinbase, custom) into the AccordRailAdapter shape so x402 endpoints can settle Accord agreements atomically (pay_before_response).","maintainers":[{"name":"accord-protocol","email":"alexander.bezkrovny@gmail.com"}],"readme":"# `@accord-protocol/rails-x402`\n\nAccord rail adapter for **x402-compatible HTTP payments**. Wraps any [x402 facilitator](https://github.com/coinbase/x402) (Coinbase's hosted one, a self-hosted shim, or a test stub) into the [`AccordRailAdapter`](../accord-rails) shape.\n\nThis is the rail that lets x402 endpoints **upgrade into Accord agreements** — keep paying USDC on Base via x402, get verifiable Accord work-receipts on top.\n\nPublic docs: [Website](https://accordprotocol.ai/) · [Accord vs x402](https://accordprotocol.ai/learn/accord-vs-x402/) · [Accord/402 flow](https://accordprotocol.ai/learn/accord-402-flow/)\n\n## Install\n\n```bash\nnpm install @accord-protocol/rails-x402 @accord-protocol/rails @accord-protocol/core\n```\n\nNo other dependencies — the facilitator is pluggable, you wire whichever HTTP client (or stub) you want.\n\n## Usage\n\n```ts\nimport { createX402RailAdapter, type X402Facilitator } from \"@accord-protocol/rails-x402\";\n\nconst facilitator: X402Facilitator = {\n  network: \"base-sepolia\",\n  async verify({ agreement, paymentPayload, scheme }) {\n    const r = await fetch(\"https://x402.coinbase.com/verify\", {\n      method: \"POST\",\n      body: JSON.stringify({ /* per facilitator API */ }),\n    });\n    const json = await r.json();\n    return json.ok\n      ? { ok: true, payment_id: json.payment_id, scheme: json.scheme, payer: json.payer }\n      : { ok: false, code: json.code, message: json.message };\n  },\n  async settle({ agreement, paymentPayload, payment_id }) {\n    const r = await fetch(\"https://x402.coinbase.com/settle\", { /* … */ });\n    const json = await r.json();\n    return { tx_hash: json.tx_hash, block_height: json.block_height };\n  },\n};\n\nconst rail = createX402RailAdapter({ facilitator });\n```\n\n## How x402 maps to Accord\n\nPer [ACCORD-003](../../specs/ACCORD-003-settlement-receipt.md), the x402 rail's only mode is **`paid_before_response`** — payment is verified atomically, the response goes back, the buyer either got the work or didn't pay.\n\nReceipt shape:\n\n```json\n{\n  \"type\": \"accord.settlement_receipt.v0\",\n  \"rail\": \"x402\",\n  \"mode\": \"paid_before_response\",\n  \"status\": \"settled\",\n  \"tx\": { \"tx_id\": \"<facilitator-issued payment_id>\", \"network\": \"base-sepolia\", \"block_height\": ... }\n}\n```\n\n`payment_id` (from the facilitator) doubles as the receipt's `tx_id` when the facilitator doesn't expose a separate `settle` endpoint — typical for facilitator-broker setups where verify and submit happen in one round-trip.\n\n## Buyer payment-proof shape\n\n```json\n{\n  \"x402_payment_payload\": \"<base64 of facilitator's PaymentPayload>\",\n  \"scheme\": \"exact\"\n}\n```\n\nThe payload is opaque — for Coinbase's facilitator on Base it's an EIP-3009 `transferWithAuthorization` signature. The adapter doesn't decode it; it hands it to the facilitator.\n\n## verifyPayment checks (in order)\n\n1. **Shape** — `x402_payment_payload` is a non-empty string.\n2. **Currency** — agreement asks for USDC or USDT (rejection: `CURRENCY_NOT_SUPPORTED`; for ERG use `rails-ergo`, for rsUSDT/rsUSDC/rsBTC use `rails-rosen`, for native ERC-20 paywalled-Note flows use `rails-base`).\n3. **`facilitator.verify(...)`** — the rail of last resort. Returns `ok` + `payment_id` or a structured rejection.\n   - On `ok: false` → `FACILITATOR_REJECTED`.\n   - On thrown → `FACILITATOR_UNAVAILABLE`.\n\nOn success: `payment_id` is whatever the facilitator returns (typically the EVM tx hash that will land the payment).\n\n## settle behaviour\n\n`settle()` re-calls `facilitator.verify(...)` (idempotent under x402's stateless contract) to get a fresh `payment_id`, then optionally calls `facilitator.settle(...)` for the real on-chain `tx_hash`. If the facilitator doesn't expose `settle`, the adapter still returns a `settled` Settlement Receipt using `payment_id` as the tx id — typical for facilitator-flow x402 where verify and submit happen in the same step.\n\n## Error codes\n\n`X402_RAIL_ERROR_CODES`:\n\n```text\nINVALID_PAYMENT_SHAPE\nFACILITATOR_REJECTED\nFACILITATOR_UNAVAILABLE\nCURRENCY_NOT_SUPPORTED\n```\n\n## Why this exists\n\n> *x402 verifies payment. Accord verifies completion.*\n\nx402 alone gives you a paid request; Accord adds the agreement object, the verifier hook, the dispute trail, and the cross-rail settlement registry. The `rails-x402` adapter is the **bridge**: existing x402 providers can join Accord without changing payment rails. Set price + verification rules in an Accord Agreement, accept the same x402 X-PAYMENT header, return Accord Verification + Settlement Receipts on top.\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}