Turnpike#

An open-source x402 payment facilitator for Stellar, with a native Bazaar discovery layer.

The facilitator runs on Stellar testnet today, with settled payments verified in CI. The Bazaar discovery layer, the upto scheme, and mainnet are designed and specified but not built — they are the proposed grant work. Every page marks which is which.

Turnpike lets any server charge per request in stablecoins without running blockchain infrastructure, and lets any autonomous agent pay for those requests without holding XLM or managing a wallet. The discovery layer makes those paid endpoints findable, so an agent can locate a resource, pay for it, and consume it without a human in the loop.

Apache-2.0. Built on the Apache-2.0 @x402/stellar package. Submitted in response to the Stellar Community Fund RFP for an x402 Facilitator with Bazaar discovery support.

The problem#

Three gaps sit between Stellar and machine-to-machine commerce.

A seller cannot charge per request without becoming a blockchain operator. Accepting an on-chain payment for a single API call means running RPC infrastructure, holding and rotating keys, managing transaction sequencing, paying network fees, handling confirmation and reorg semantics, and writing verification logic that is correct against a moving protocol. For a team whose actual product is a weather API or an inference endpoint, that is a disproportionate amount of undifferentiated work. The economics are worse than the engineering: the cost of building payment infrastructure vastly exceeds the revenue from per-call pricing at small volumes, so per-call pricing does not get built.

An agent cannot pay without holding native gas. Even when a seller accepts payment, the buyer traditionally needs the network’s native asset to pay transaction fees. An autonomous agent that holds USDC to spend on API calls should not also need to acquire, hold, monitor, and top up XLM in order to transact. Every additional asset an agent must manage is another failure mode and another operational dependency.

Paid endpoints are not discoverable. A payment protocol without discovery only works when a human has already told the agent where to look. The interesting behaviour — an agent that needs a capability it does not have, finds a service offering it, evaluates the price, pays, and uses it — requires a catalogue. Without one, x402 is a payment rail for pre-arranged relationships rather than an open market.

What Turnpike does#

Turnpike is a facilitator: the component in the x402 protocol that abstracts the blockchain away from the seller.

The seller’s server responds to an unpaid request with HTTP 402 Payment Required and a description of acceptable terms. The buyer constructs a signed payment payload. The seller hands that payload to Turnpike, which verifies it, submits the settlement transaction to Stellar, pays the network fee on the buyer’s behalf, and returns the settled transaction hash. The seller never touches a key, an RPC endpoint, or a transaction envelope.

The Bazaar discovery layer catalogues the resources that pass through the facilitator and makes them searchable, with listing ownership bound to on-chain settlement rather than to client claims.

Who this is for#

Design commitments#

These are the constraints I have chosen to hold myself to. They shape every decision in the rest of these docs.

Correctness is defined by the protocol, not by me. An unmodified, stock x402 client — installed from public npm, with no patches — must be able to complete a payment against Turnpike. I run that assertion in CI on every push, against a pinned client version. If conformance ever requires patching the client, the fault is mine and the fix belongs in the service.

Wrap, do not reimplement. Authorization-entry validation, transaction assembly, and settlement are delegated to the Apache-2.0 @x402/stellar package. I do not hand-roll cryptography. My code is the HTTP surface, the error semantics, the operational plumbing, and the discovery layer.

Every rejection explains itself. No rejection path returns a null, empty, or generic reason. This is an explicit acceptance requirement of the RFP and, more practically, it is the difference between an integrator debugging in ten minutes and an integrator giving up.

Advertise only what is true. /supported reports actual capability, including whether fees are genuinely sponsored. Claims I cannot substantiate do not appear — in the API, in these docs, or in the submission that references them.

Publish the failures. Reliability numbers in these docs include a payment I lost and a measurement I retracted. A reliability section that reports only successes tells a reader nothing, because they cannot distinguish it from one that was never tested.

Current status#

Turnpike has a working testnet implementation. A stock x402 client completes real, settled payments against it, verified in continuous integration on infrastructure I do not control.

The Bazaar discovery layer, the upto scheme, and mainnet deployment are designed and specified but not yet built. They are the substance of the proposed grant work, and the plan for delivering them is set out in Roadmap and Tranches.

The scope boundary is stated precisely in Reliability and Evidence. I would rather a reviewer read exactly what I have not yet proven than discover the gap themselves.

Documentation map#