-
Notifications
You must be signed in to change notification settings - Fork 257
docs: add Built on Stellar x402 facilitator landing page
#2312
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
a0348cd
Add Built on Stellar x402 Facilitator landing page
marcelosalloum c7279cc
Potential fix for pull request finding
marcelosalloum 1f0a024
Add new x402/built-on-stellar route to routes.txt
marcelosalloum 1f4c9f8
Remove custom title and logo
marcelosalloum File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,188 @@ | ||
| --- | ||
| title: Built on Stellar x402 Facilitator | ||
| sidebar_position: 10 | ||
| sidebar_label: Built on Stellar Facilitator | ||
| description: "Free, public x402 facilitator for Stellar with ~5-second finality and sponsored fees. Full verification and settlement flow powered by the OpenZeppelin Relayer." | ||
| hide_title: true | ||
| --- | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| alignItems: "center", | ||
| gap: "16px", | ||
| marginBottom: "16px", | ||
| }} | ||
| > | ||
| <img | ||
| src="/assets/x402/built-on-stellar-logo.png" | ||
| alt="Built on Stellar logo" | ||
| width="68" | ||
| height="68" | ||
| style={{ borderRadius: "8px", alignItems: "center", margin: 0 }} | ||
| /> | ||
| <h1 | ||
| style={{ | ||
| margin: 0, | ||
| marginTop: "20px", | ||
| fontSize: "48px", | ||
| lineHeight: "56px", | ||
| height: "56px", | ||
| display: "flex", | ||
| alignItems: "center", | ||
| }} | ||
| > | ||
| Built on Stellar x402 Facilitator | ||
| </h1> | ||
| </div> | ||
|
|
||
| The **Built on Stellar** x402 Facilitator is a production-ready payment facilitator for the [x402 protocol](./README.mdx) 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) | | ||
|
|
||
| ## 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 | ||
| - **Mainnet**: https://channels.openzeppelin.com/gen | ||
|
|
||
| ### 2. Configure the facilitator URL | ||
|
|
||
| Use the facilitator URL in your x402 server configuration. Here's an example using `@x402/express`: | ||
|
|
||
| ```typescript | ||
| 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 | ||
| 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 | ||
| 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. | ||
|
|
||
| ## 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` | ||
|
marcelosalloum marked this conversation as resolved.
|
||
| - **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](./README.mdx#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](./README.mdx) — 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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.