{"id":28017876,"url":"https://github.com/coinbase/x402","last_synced_at":"2025-09-23T01:08:33.645Z","repository":{"id":281272514,"uuid":"936374955","full_name":"coinbase/x402","owner":"coinbase","description":"A payments protocol for the internet. Built on HTTP.","archived":false,"fork":false,"pushed_at":"2025-05-05T22:28:01.000Z","size":4438,"stargazers_count":138,"open_issues_count":13,"forks_count":18,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-05T22:28:12.986Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://x402.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coinbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-21T01:17:52.000Z","updated_at":"2025-05-05T22:28:04.000Z","dependencies_parsed_at":"2025-03-08T00:56:09.806Z","dependency_job_id":"7cc26261-aa1e-4ae3-a0ba-a23d7285053a","html_url":"https://github.com/coinbase/x402","commit_stats":null,"previous_names":["coinbase/x402"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fx402","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fx402/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fx402/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coinbase%2Fx402/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coinbase","download_url":"https://codeload.github.com/coinbase/x402/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252587507,"owners_count":21772474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-10T12:01:31.913Z","updated_at":"2025-09-23T01:08:33.632Z","avatar_url":"https://github.com/coinbase.png","language":"TypeScript","funding_links":[],"categories":["Payments \u0026 Banking","TypeScript","Crypto Payment Rails","Blockchain and Rewards","📄 Specifications \u0026 Whitepapers","📖 Protocol Documentation","Crypto payment rails","📗 Community","Uncategorized","Agent Payments"],"sub_categories":["On-Chain Analytics","x402","x402 Protocol","Uncategorized","Benchmark Reality Check (real-world tool use)"],"readme":"# x402 payments protocol\n\n\u003e \"1 line of code to accept digital dollars. No fee, 2 second settlement, $0.001 minimum payment.\"\n\n```typescript\napp.use(\n  // How much you want to charge, and where you want the funds to land\n  paymentMiddleware(\"0xYourAddress\", { \"/your-endpoint\": \"$0.01\" })\n);\n// That's it! See examples/typescript/servers/express.ts for a complete example. Instruction below for running on base-sepolia.\n```\n\n## Philosophy\n\nPayments on the internet are fundamentally flawed. Credit Cards are high friction, hard to accept, have minimum payments that are far too high, and don't fit into the programmatic nature of the internet.\nIt's time for an open, internet-native form of payments. A payment rail that doesn't have high minimums + % based fee. Payments that are amazing for humans and AI agents.\n\n## Principles\n\n- **Open standard:** the x402 protocol will never force reliance on a single party\n- **HTTP Native:** x402 is meant to seamlessly complement the existing HTTP request made by traditional web services, it should not mandate additional requests outside the scope of a typical client / server flow.\n- **Chain and token agnostic:** we welcome contributions that add support for new chains, signing standards, or schemes, so long as they meet our acceptance criteria laid out in [CONTRIBUTING.md](https://github.com/coinbase/x402/blob/main/CONTRIBUTING.md)\n- **Trust minimizing:** all payment schemes must not allow for the facilitator or resource server to move funds, other than in accordance with client intentions\n- **Easy to use:** x402 needs to be 10x better than existing ways to pay on the internet. This means abstracting as many details of crypto as possible away from the client and resource server, and into the facilitator. This means the client/server should not need to think about gas, rpc, etc.\n\n## Ecosystem\n\nThe x402 ecosystem is growing! Check out our [ecosystem page](https://x402.org/ecosystem) to see projects building with x402, including:\n\n- Client-side integrations\n- Services and endpoints\n- Ecosystem infrastructure and tooling\n- Learning and community resources\n\nWant to add your project to the ecosystem? See our [demo site README](https://github.com/coinbase/x402/tree/main/typescript/site#adding-your-project-to-the-ecosystem) for detailed instructions on how to submit your project.\n\n**Roadmap:** see [ROADMAP.md](https://github.com/coinbase/x402/blob/main/ROADMAP.md)\n\n## Terms:\n\n- `resource`: Something on the internet. This could be a webpage, file server, RPC service, API, any resource on the internet that accepts HTTP / HTTPS requests.\n- `client`: An entity wanting to pay for a resource.\n- `facilitator server`: A server that facilitates verification and execution of on-chain payments.\n- `resource server`: An HTTP server that provides an API or other resource for a client.\n\n## Technical Goals:\n\n- Permissionless and secure for clients and servers\n- Gasless for client and resource servers\n- Minimal integration for the resource server and client (1 line for the server, 1 function for the client)\n- Ability to trade off speed of response for guarantee of payment\n- Extensible to different payment flows and chains\n\n## V1 Protocol\n\nThe `x402` protocol is a chain agnostic standard for payments on top of HTTP, leverage the existing `402 Payment Required` HTTP status code to indicate that a payment is required for access to the resource.\n\nIt specifies:\n\n1. A schema for how servers can respond to clients to facilitate payment for a resource (`PaymentRequirements`)\n2. A standard header `X-PAYMENT` that is set by clients paying for resources\n3. A standard schema and encoding method for data in the `X-PAYMENT` header\n4. A recommended flow for how payments should be verified and settled by a resource server\n5. A REST specification for how a resource server can perform verification and settlement against a remote 3rd party server (`facilitator`)\n6. A specification for a `X-PAYMENT-RESPONSE` header that can be used by resource servers to communicate blockchain transactions details to the client in their HTTP response\n\n### V1 Protocol Sequencing\n\n![](./static/x402-protocol-flow.png)\n\nThe following outlines the flow of a payment using the `x402` protocol. Note that steps (1) and (2) are optional if the client already knows the payment details accepted for a resource.\n\n1. `Client` makes an HTTP request to a `resource server`.\n\n2. `Resource server` responds with a `402 Payment Required` status and a `Payment Required Response` JSON object in the response body.\n\n3. `Client` selects one of the `paymentRequirements` returned by the server response and creates a `Payment Payload` based on the `scheme` of the `paymentRequirements` they have selected.\n\n4. `Client` sends the HTTP request with the `X-PAYMENT` header containing the `Payment Payload` to the resource server.\n\n5. `Resource server` verifies the `Payment Payload` is valid either via local verification or by POSTing the `Payment Payload` and `Payment Requirements` to the `/verify` endpoint of a `facilitator server`.\n\n6. `Facilitator server` performs verification of the object based on the `scheme` and `network` of the `Payment Payload` and returns a `Verification Response`.\n\n7. If the `Verification Response` is valid, the resource server performs the work to fulfill the request. If the `Verification Response` is invalid, the resource server returns a `402 Payment Required` status and a `Payment Required Response` JSON object in the response body.\n\n8. `Resource server` either settles the payment by interacting with a blockchain directly, or by POSTing the `Payment Payload` and `Payment PaymentRequirements` to the `/settle` endpoint of a `facilitator server`.\n\n9. `Facilitator server` submits the payment to the blockchain based on the `scheme` and `network` of the `Payment Payload`.\n\n10. `Facilitator server` waits for the payment to be confirmed on the blockchain.\n\n11. `Facilitator server` returns a `Payment Execution Response` to the resource server.\n\n12. `Resource server` returns a `200 OK` response to the `Client` with the resource they requested as the body of the HTTP response, and a `X-PAYMENT-RESPONSE` header containing the `Settlement Response` as Base64 encoded JSON if the payment was executed successfully.\n\n### Type Specifications\n\n#### Data types\n\n**Payment Required Response**\n\n```json5\n{\n  // Version of the x402 payment protocol\n  x402Version: int,\n\n  // List of payment requirements that the resource server accepts. A resource server may accept on multiple chains, or in multiple currencies.\n  accepts: [paymentRequirements]\n\n  // Message from the resource server to the client to communicate errors in processing payment\n  error: string\n}\n```\n\n**paymentRequirements**\n\n```json5\n{\n  // Scheme of the payment protocol to use\n  scheme: string;\n\n  // Network of the blockchain to send payment on\n  network: string;\n\n  // Maximum amount required to pay for the resource in atomic units of the asset\n  maxAmountRequired: uint256 as string;\n\n  // URL of resource to pay for\n  resource: string;\n\n  // Description of the resource\n  description: string;\n\n  // MIME type of the resource response\n  mimeType: string;\n\n  // Output schema of the resource response\n  outputSchema?: object | null;\n\n  // Address to pay value to\n  payTo: string;\n\n  // Maximum time in seconds for the resource server to respond\n  maxTimeoutSeconds: number;\n\n  // Address of the EIP-3009 compliant ERC20 contract\n  asset: string;\n\n  // Extra information about the payment details specific to the scheme\n  // For `exact` scheme on a EVM network, expects extra to contain the records `name` and `version` pertaining to asset\n  extra: object | null;\n}\n```\n\n**`Payment Payload`** (included as the `X-PAYMENT` header in base64 encoded json)\n\n```json5\n{\n  // Version of the x402 payment protocol\n  x402Version: number;\n\n  // scheme is the scheme value of the accepted `paymentRequirements` the client is using to pay\n  scheme: string;\n\n  // network is the network id of the accepted `paymentRequirements` the client is using to pay\n  network: string;\n\n  // payload is scheme dependent\n  payload: \u003cscheme dependent\u003e;\n}\n```\n\n#### Facilitator Types \u0026 Interface\n\nA `facilitator server` is a 3rd party service that can be used by a `resource server` to verify and settle payments, without the `resource server` needing to have access to a blockchain node or wallet.\n\n**POST /verify**. Verify a payment with a supported scheme and network:\n\n- Request body JSON:\n  ```json5\n  {\n    x402Version: number;\n    paymentHeader: string;\n    paymentRequirements: paymentRequirements;\n  }\n  ```\n- Response:\n  ```json5\n  {\n    isValid: boolean;\n    invalidReason: string | null;\n  }\n  ```\n\n**POST /settle**. Settle a payment with a supported scheme and network:\n\n- Request body JSON:\n\n  ```json5\n  {\n    x402Version: number;\n    paymentHeader: string;\n    paymentRequirements: paymentRequirements;\n  }\n  ```\n\n- Response:\n\n  ```json5\n  {\n    // Whether the payment was successful\n    success: boolean;\n\n    // Error message from the facilitator server\n    error: string | null;\n\n    // Transaction hash of the settled payment\n    txHash: string | null;\n\n    // Network id of the blockchain the payment was settled on\n    networkId: string | null;\n  }\n  ```\n\n**GET /supported**. Get supported payment schemes and networks:\n\n- Response:\n  ```json5\n  {\n    kinds: [\n      {\n        \"scheme\": string,\n        \"network\": string,\n      }\n    ]\n  }\n  ```\n\n### Schemes\n\nA scheme is a logical way of moving money.\n\nBlockchains allow for a large number of flexible ways to move money. To help facilitate an expanding number of payment use cases, the `x402` protocol is extensible to different ways of settling payments via its `scheme` field.\n\nEach payment scheme may have different operational functionality depending on what actions are necessary to fulfill the payment.\nFor example `exact`, the first scheme shipping as part of the protocol, would have different behavior than `upto`. `exact` transfers a specific amount (ex: pay $1 to read an article), while a theoretical `upto` would transfer up to an amount, based on the resources consumed during a request (ex: generating tokens from an LLM).\n\nSee `specs/schemes` for more details on schemes, and see `specs/schemes/exact/scheme_exact_evm.md` to see the first proposed scheme for exact payment on EVM chains.\n\n### Schemes vs Networks\n\nBecause a scheme is a logical way of moving money, the way a scheme is implemented can be different for different blockchains. (ex: the way you need to implement `exact` on Ethereum is very different from the way you need to implement `exact` on Solana).\n\nClients and facilitators must explicitly support different `(scheme, network)` pairs in order to be able to create proper payloads and verify / settle payments.\n\n## Running example\n\n**Requirements:** Node.js v24 or higher\n\n1. From `examples/typescript` run `pnpm install` and `pnpm build` to ensure all dependent packages and examples are setup.\n\n2. Select a server, i.e. express, and `cd` into that example. Add your server's ethereum address to get paid to into the `.env` file, and then run `pnpm dev` in that directory.\n\n3. Select a client, i.e. axios, and `cd` into that example. Add your private key for the account making payments into the `.env` file, and then run `pnpm dev` in that directory.\n\nYou should see activities in the client terminal, which will display a weather report.\n\n## Running tests\n\n1. Navigate to the typescript directory: `cd typescript`\n2. Install dependencies: `pnpm install`\n3. Run the unit tests: `pnpm test`\n\nThis will run the unit tests for the x402 packages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fx402","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoinbase%2Fx402","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoinbase%2Fx402/lists"}