# x402: HTTP 402 as a Payment Rail, and What the Repository Actually Ships

> The x402-foundation/x402 repository defines an open standard for internet native payments over HTTP, with reference SDKs in TypeScript, Python and Go. The spec is broad; the operational guidance is narrower than the marketing implies.

**x402-foundation/x402** — A payments protocol for the internet. Built on HTTP.

- Repository: https://github.com/x402-foundation/x402
- Website: https://x402.org
- Stars: 6,671 · Forks: 2,107
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/x402-foundation-x402

## The Problem x402 Targets: Paid HTTP Without a Second Protocol

HTTP already reserves status code 402 for "Payment Required", and almost nobody uses it. x402 takes that slot literally. A resource server that wants to charge for an endpoint returns 402 with a PaymentRequired object, and the client retries with proof of payment attached. No redirect to a hosted checkout, no separate billing API, no session cookie exchange.

The README frames the audience as two roles that normally sit on opposite sides of a payment integration. A resource server is "an HTTP server that provides an API or other resource for a client", and a client is "an entity wanting to pay for a resource". The standard's stated technical goal is minimal integration: one line for the server, one function for the client.

That framing matters because it excludes a lot. x402 is not a checkout product, not a subscription manager, and not a merchant-of-record layer. It is a wire format plus a verification role. If your problem is "charge a card and handle refunds", x402 is the wrong shape entirely.

## How the 402 Handshake Works, Step by Step

The README lays out a numbered flow, and the ordering is the part worth internalising. Steps 1 and 2 are optional when the client already knows the payment terms for a resource, which means an agent that has cached requirements can skip straight to signing.

Otherwise: the client requests the resource, the server answers 402 Payment Required with a base64 PaymentRequired object in a PAYMENT-REQUIRED header. The client picks one entry from the returned PaymentRequirements, builds a PaymentPayload for that scheme and network, and resends the original request with a PAYMENT-SIGNATURE header carrying the payload.

The server then verifies. It can verify locally, or POST the PaymentPayload and PaymentRequirements to a facilitator's /verify endpoint. The facilitator is defined as "a server that facilitates verification and execution of payments for one or many networks". That split is the design's central bet: the client and server should not need to think about gas or RPC, so that work is pushed into the facilitator role.

The README names three payment schemes: exact, upto, and batch-settlement. Specifications live under specs/schemes/. The distinction between them is not explained in the README itself, so anyone choosing a scheme has to read the spec directory rather than the front page.

## Installing the SDKs and Getting a First 402 Response

The README gives package names per language. For a minimal Express server it lists @x402/core, @x402/evm and @x402/svm, installed with npm. Note that the repository's own package.json is private and only pins pnpm@11.1.1, so the published SDK packages are what you consume, not the monorepo root.

```bash
npm install @x402/core @x402/evm @x402/svm @x402/express
```

The README's headline example shows the server side as a middleware call keyed by route, with an accepts array and a description. The comment in that snippet says you can list as many networks and schemes as you want to support.

```typescript
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [...],
        description: "Weather data",
      },
    },
  ),
);
```

The README points to examples/ for full details, and the repository has examples/typescript/, examples/python/ and examples/go/ directories. For a client, the minimal Fetch setup is @x402/core, @x402/evm, @x402/svm and @x402/fetch. Python is a single pip install x402, and Go is go get github.com/x402-foundation/x402/go/v2.

What you should see after wiring the middleware: an unauthenticated request to the protected route returns 402 with a PAYMENT-REQUIRED header rather than your handler's normal body. The README does not document what the header looks like decoded, so plan to inspect it yourself.

## The Facilitator Decision Is the Real Integration Cost

This is where the README is most direct and most projects will skim past it. There is a section titled "Choosing a Production Path" that separates testnet from mainnet. For testnet development and quickstarts, the public x402 facilitator is described as the easiest way to start. For production mainnet routes, the README says to decide on your facilitator model explicitly, and lists three options: a production facilitator provider that supports your target network, running your own facilitator, or self-facilitating inside your resource server.

Then the sentence that should govern your planning: "Do not assume the public x402.org facilitator is the default production path for mainnet EVM routes." That is a maintainer telling you the convenient thing is not the durable thing.

The trust model is stated as a principle rather than a mechanism. The README says all payment schemes must not allow the facilitator or resource server to move funds other than in accordance with client intentions. That is a constraint on scheme design, not a guarantee about any particular facilitator you connect to. If you are evaluating a third-party facilitator, the README does not give you a checklist for that review; it points to the Facilitators directory and the Network & Token Support docs for operator guidance.

## Where x402 Is the Wrong Tool

The README's own principles create the boundary. x402 is described as network, token and currency agnostic, and it says support may extend to fiat based networks while never deprioritising onchain payments in favour of fiat. So if your requirement is fiat settlement with no crypto component, you are not the target user, and the project says as much.

Second, the response-versus-certainty trade-off is real and the README admits it as a goal: the ability to trade off speed of response for guarantee of payment. A scheme that returns fast gives a weaker payment guarantee than one that waits. There is no single correct answer, and the README does not pick one for you.

Third, the flow is only as good as the client. A browser user who has no wallet and no signing library cannot complete step 3. The README's ease-of-use principle targets abstracting crypto away from client and server into the facilitator, but that abstraction still assumes the client can produce a PaymentPayload for some scheme and network. For a public marketing page with anonymous human visitors, a conventional payment processor remains the simpler path.

Finally, backwards compatibility is promised with an escape hatch: the README says x402 will not deprecate support for an existing network unless removal is deemed necessary for the security of the standard. Security-driven removals are therefore possible, and a network you depend on could be one.

## How x402 Differs from a Payment Gateway Integration

The closest familiar alternative is a hosted payment API such as Stripe: your server calls out to a provider, the provider holds the merchant relationship, and the client is redirected or embedded into provider-controlled UI. The payment is a separate transaction that happens alongside the HTTP request.

x402 inverts that. The payment is a header on the same request that fetches the resource, and verification can happen inline at the resource server or by a POST to a facilitator's /verify endpoint. There is no redirect and no provider-hosted form. The trade is that you take on facilitator selection yourself, which the README makes explicit rather than hiding.

A second comparison is worth naming because the README names it: self-facilitation. Instead of trusting an external facilitator, you run the verification and execution inside your own resource server, with the README linking to examples/typescript/servers/self-facilitation/. That is a different operational profile, not a different protocol. You keep the 402 handshake and lose the dependency on a third party's uptime and network coverage.

For agent-to-API payments specifically, the README lists @402/mcp and @x402/extensions among the published packages, and the related-searches vocabulary around "X402 agents" reflects that use case. The repository also points to community directories including x402scan.com, Agentic.Market, Pay.sh, app.ampersend.ai/discover and x402-list.com for discovery of x402 services. Those are third-party, and the README labels them community-maintained.

## Licence, Maintenance and What Upgrades Cost You

The repository is licensed Apache-2.0, with a NOTICE file at the top level. Apache-2.0 includes an express patent grant and requires that you preserve licence and notice files when redistributing. If you vendor the specs or copy example code into a product, keep LICENSE and NOTICE intact. This is a description of the licence text, not legal advice; get your own review if you are redistributing modified code.

The repository is not archived, and the last push was on 2026-09-21, one day before this writing. That is a live tree. The top level contains a foundation/ directory, a contracts/ directory, an e2e/ directory, and language directories for go, java, python and typescript, plus specs/ and docs/. The README notes that docs/ is the source for Mintlify-published documentation, so documentation changes arrive as repository commits rather than only through a separate docs site.

Upgrade cost concentrates in the SDK packages rather than the spec. The README's backwards-compatibility principle says x402 aims for backwards compatibility for non-major version changes whenever possible, which is a goal, not a contract. The Go module path carries a v2 segment (go/v2), so Go consumers are already on a major-version boundary. Pin your SDK versions and read the release notes before bumping, since no releases were retrievable here and I cannot tell you what any given version changed.

## Conclusion

Adopt x402 if you are building an HTTP resource server that needs per-request payment and you accept that the facilitator model must be chosen explicitly for mainnet. Do not adopt it if you need a settled production default or a fiat-only path, because the README states the public x402.org facilitator is not the default production path for mainnet EVM routes. Before writing code, verify your target network appears in the Networks & Token Support docs and decide whether you will use a facilitator provider, run your own, or self-facilitate inside the resource server.

## FAQ

### What is the x402 protocol?

x402 is an open standard for internet native payments built on HTTP, using the 402 Payment Required status code. A resource server returns a PaymentRequired object in a PAYMENT-REQUIRED header, and the client retries with a PaymentPayload in a PAYMENT-SIGNATURE header.

### Where can I buy x402?

You cannot buy x402. It is an open standard published in the x402-foundation/x402 repository under Apache-2.0, with reference SDKs installed from npm, pip and the Go module proxy.

### What is the current price of x402?

x402 has no price. It is a protocol and a set of SDK packages, not a token or a paid product. What you pay is whatever a resource server charges for its endpoints, expressed in the PaymentRequirements it returns.

## Sources

- [Issues](https://github.com/x402-foundation/x402/issues)
- [License: Apache-2.0](https://github.com/x402-foundation/x402/blob/main/LICENSE)
- [Project website](https://x402.org)
- [README](https://github.com/x402-foundation/x402/blob/main/README.md)
- [x402-foundation/x402 on GitHub](https://github.com/x402-foundation/x402)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/x402-foundation-x402