> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Built on Stellar x402 Facilitator

> Free, public x402 facilitator for Stellar with ~5-second finality and sponsored fees. Full verification and settlement flow powered by the OpenZeppelin Relayer.

The **Built on Stellar** x402 Facilitator is a production-ready payment facilitator for the [x402 protocol](https://developers.stellar.org/docs/build/agentic-payments/x402) on Stellar. It handles payment verification and settlement so that sellers can accept per-request payments without running their own blockchain infrastructure.

Built with the [OpenZeppelin Relayer][oz-relayer] and the [x402 Facilitator Plugin][oz-plugin], it exposes the standard x402 `/verify`, `/settle`, and `/supported` endpoints and is fully compatible with the [Coinbase x402 ecosystem][x402-ecosystem].

## Key information

| | Testnet | Mainnet |
| - | - | - |
| **Facilitator URL** | `https://channels.openzeppelin.com/x402/testnet` | `https://channels.openzeppelin.com/x402` |
| **API key generation** | [Generate testnet key](https://channels.openzeppelin.com/testnet/gen) | [Generate mainnet key](https://channels.openzeppelin.com/gen) |
| **x402 version** | v2 | v2 |
| **x402 scheme** | `exact` | `exact` |
| **Supported assets** | Any [SEP-41] token (defaults to USDC) | Any [SEP-41] token (defaults to USDC) |

Verify endpoint availability:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -I https://channels.openzeppelin.com/x402/supported
# Expected: HTTP 200 with supported assets/networks
```

## Get started

### 1. Generate an API key

Generate an API key for the network you want to use:

* **Testnet**: [https://channels.openzeppelin.com/testnet/gen](https://channels.openzeppelin.com/testnet/gen) (no authentication required)
* **Mainnet**: [https://channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen) (requires GitHub OAuth)

Store the generated API key securely. It cannot be retrieved after creation.

### 2. Configure the facilitator URL

Use the facilitator URL in your x402 server configuration. Here's an example using `@x402/express`:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactStellarScheme } from "@x402/stellar/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://channels.openzeppelin.com/x402/testnet",
  createAuthHeaders: async () => {
    const headers = { Authorization: `Bearer YOUR_API_KEY` };
    return { verify: headers, settle: headers, supported: headers };
  },
});

const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network: "stellar:testnet",
            payTo: "SERVER_STELLAR_ADDRESS",
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    new x402ResourceServer(facilitatorClient).register(
      "stellar:testnet",
      new ExactStellarScheme(),
    ),
  ),
);

app.get("/weather", (req, res) => {
  res.send({ weather: "sunny", temperature: 70 });
});

app.listen(4021);
```

#### Pricing formats

The `price` field supports two formats:

**Human-readable** — A dollar-string like `"$0.001"`. The x402 SDK converts this to the equivalent on-chain amount and assumes USDC on Stellar.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
price: "$0.001";
```

**Explicit asset and amount** — Specify the on-chain [SEP-41] asset contract address and the amount in base units (the smallest unit as defined by the token's `decimals`; for example, if a USDC token has 7 decimals, then 1 USDC = 10,000,000 base units).

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
price: {
  asset: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
  amount: "10000",
};
```

Use the explicit format when you want to accept a specific asset other than USDC, or when you need precise control over the on-chain amount.

### 3. Accept payments

With the middleware in place, any request to a protected route will trigger the x402 payment flow:

1. The client requests the resource
2. The server responds with `402 Payment Required` and a `PAYMENT-REQUIRED` header containing the payment instructions (price, network, facilitator URL)
3. The client signs a Soroban authorization entry and resubmits the request with a `PAYMENT-SIGNATURE` header
4. The facilitator verifies and settles the payment on-chain
5. The server returns the resource along with a `PAYMENT-RESPONSE` header confirming settlement

## How it works

The Built on Stellar facilitator leverages the OpenZeppelin Relayer framework with the x402 Facilitator Plugin. Under the hood, it uses the [OpenZeppelin Relayer][oz-relayer] for high-throughput transaction submission.

### Verification

When a payment is received, the facilitator:

1. Validates the x402 protocol version, scheme, and network
2. Decodes the transaction XDR and checks it is an `invokeHostFunction` calling `transfer`
3. Confirms the amount and recipient match the payment requirements
4. Verifies the authorization entries are properly signed by the payer
5. Simulates the transaction on-chain to confirm it will succeed

### Settlement

After verification, the facilitator submits the payment on-chain via the OpenZeppelin Relayer and returns confirmation to the server.

## Understanding Soroban authorization

x402 on Stellar uses Soroban's authorization model rather than pre-signed transactions. When a client pays for a resource, they sign an **authorization entry** - a statement that authorizes a specific contract call.

### What the client signs

The authorization entry contains:

* **Contract ID**: The USDC token contract
* **Function**: `transfer`
* **Arguments**: `from` (payer), `to` (recipient), `amount`
* **Expiration**: When this authorization expires

This approach provides several benefits:

* The facilitator can wrap the auth entry with sponsored fees
* No sequence number conflicts
* Built-in replay protection via expiration

## Supported features

* **Networks**: `stellar:testnet`, `stellar:pubnet` ([CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) identifiers)
* **Assets**: Any [SEP-41] token asset (defaults to USDC)
* **x402 scheme**: `exact-v2`
* **Endpoints**: `/verify`, `/settle`, `/supported`
* **Settlement**: Managed on-chain submission via [OpenZeppelin Relayer][oz-relayer]
* **Compatibility**: Works with all [x402 ecosystem packages][x402-ecosystem] and [Stellar x402-compatible wallets](https://developers.stellar.org/docs/build/agentic-payments/x402#x402-compatible-wallets)

## Self-hosting

If you want to run your own instance of the facilitator instead of using the hosted service, you can deploy the OpenZeppelin Relayer with the x402 Facilitator Plugin directly. See the [OpenZeppelin x402 Facilitator guide][oz-facilitator-guide] and the [plugin source code][oz-plugin] for setup instructions.

## Resources

* [@x402/stellar (npm)](https://www.npmjs.com/package/@x402/stellar) — npm package for x402 on Stellar
* [x402-stellar (repo)](https://github.com/stellar/x402-stellar) — Tools, examples, and references for x402 on Stellar
* [x402 on Stellar](https://developers.stellar.org/docs/build/agentic-payments/x402) — Overview of the x402 protocol on Stellar
* [x402 protocol specification](https://www.x402.org) — x402 specification and whitepaper
* [OpenZeppelin x402 Facilitator Plugin][oz-plugin] — Source code
* [OpenZeppelin x402 Facilitator Docs][oz-facilitator-guide] — Full configuration and setup guide
* [OpenZeppelin Stellar Relayer SDK](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk) — SDK for interacting with the Relayer

[oz-relayer]: https://docs.openzeppelin.com/relayer/1.4.x

[oz-plugin]: https://github.com/OpenZeppelin/relayer-plugin-x402-facilitator

[oz-facilitator-guide]: https://docs.openzeppelin.com/relayer/1.4.x/guides/stellar-x402-facilitator-guide

[SEP-41]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md

[x402-ecosystem]: https://github.com/coinbase/x402