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

> ## Agent Instructions
> Rail402 is an x402 payment facilitator, Stellar-native Bazaar discovery layer, and agent tooling for the Stellar network. It currently targets stellar:testnet.
> The live testnet facilitator is https://facilitator.rail402.dev with endpoints /verify, /settle, /supported, /health, and /discovery/*.
> Payment amounts use 7-decimal SEP-41 integer (stroop) arithmetic. Never use floating-point math for amounts.
> Every rejection returns a machine-readable error code and a non-null human-readable reason. When explaining a failure, surface both.

# Verify it yourself

> Copy-paste curl commands against the live testnet facilitator, the settled transaction for every scheme and payer type, the deployed Soroban contracts, and the upstream contributions. Every claim in this section is checkable in a terminal.

Everything in this section is meant to be checked, not taken on faith. This page collects the commands and the on-chain evidence in one place. Run the curl commands against the live facilitator, and open any transaction hash on a block explorer to confirm it settled.

<Note>
  The facilitator runs on Railway and cold-starts in up to about 13 seconds if it has been idle. If the first request is slow, run it twice.
</Note>

## Check the live facilitator

All five commands were run against the live deployment and return the responses shown (abridged).

```bash theme={null}
# 1. Both schemes on stellar:testnet, with sponsored fees advertised truthfully.
curl -s https://facilitator.rail402.dev/supported | jq
# {
#   "kinds": [
#     { "x402Version": 2, "scheme": "exact", "network": "stellar:testnet",
#       "extra": { "areFeesSponsored": true } },
#     { "x402Version": 2, "scheme": "upto",  "network": "stellar:testnet",
#       "extra": { "uptoContract": "CCMM3FMGEH7FHRYXZ3WQDQCTIWDXGZBGW7D4UT7NKH34SUQACYC3U54X",
#                  "areFeesSponsored": true } }
#   ],
#   "extensions": ["bazaar"],
#   "signers": { "stellar:*": ["GBRVXNCL55KOEB7WU3BPSEL34PSUH63UCIFPZDUBIVJBRRG5ZB7V4YR7"] }
# }

# 2. Durable catalog, live signer count, degraded-mode field.
curl -s https://facilitator.rail402.dev/health | jq
# { "status": "ok", "networks": ["stellar:testnet"], "signers": 1,
#   "catalog": { "entries": 3, "storage": "durable" } }

# 3. Browse the Bazaar catalog (the list key is `items`).
curl -s "https://facilitator.rail402.dev/discovery/resources?limit=2" | jq
# { "x402Version": 2, "items": [ { "resource": ".../demo/convert", "accepts": [...] } ],
#   "pagination": { "limit": 2, "offset": 0, "total": ... } }

# 4. Natural-language search (the array key is `resources`, not `items`).
curl -s "https://facilitator.rail402.dev/discovery/search?query=tide" | jq
# { "x402Version": 2, "resources": [ { "resource": ".../quote", ... } ] }

# 5. Confirm a settlement on chain. The fee source is the facilitator, not the buyer.
curl -s "https://horizon-testnet.stellar.org/transactions/3f6031ed4d3d17100992b1e003f9bcc6da51ef684cc1ba402432ae52166a903f" \
  | jq '{ successful, ledger, fee_charged, source_account }'
# { "successful": true, "ledger": 3879480, "fee_charged": "22973",
#   "source_account": "GDR7HR3T..." }   (the facilitator, sponsoring the fee)
```

Command 5 confirms two invariants at once. `fee_charged` is paid by `source_account`, which is the facilitator's signer, so the fee is sponsored. That source is not the buyer whose auth entry moved the funds, so the settlement is non-custodial. See [Fee sponsorship](/architecture/fees) and [the non-custodial invariant](/architecture/settlement#the-non-custodial-invariant).

## Settled transactions

One settlement per scheme, per payer type, per asset. Open any hash on [stellar.expert](https://stellar.expert/explorer/testnet) using the form `https://stellar.expert/explorer/testnet/tx/<hash>`. These are regenerated by the canary suite and kept current in `docs/status/`.

| Scheme  | Payer             | Asset       | How                                     | Transaction                                                                                                                |
| ------- | ----------------- | ----------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `exact` | `G` keypair       | self-issued | unmodified stock client                 | [`3f6031ed…`](https://stellar.expert/explorer/testnet/tx/3f6031ed4d3d17100992b1e003f9bcc6da51ef684cc1ba402432ae52166a903f) |
| `exact` | `G` keypair       | real USDC   | SDK, default fee ceiling                | [`cfb8c0fd…`](https://stellar.expert/explorer/testnet/tx/cfb8c0fdeec7e54d2becb9ee4e357c291727e121397546f25607333064ca57c1) |
| `exact` | `G` keypair       | real USDC   | upstream e2e suite, stock axios         | [`52c62499…`](https://stellar.expert/explorer/testnet/tx/52c62499f22e37e4dc1186552b2f7684a874d9f85a1f38c11320cb2a194a5ca1) |
| `exact` | `G` keypair       | real USDC   | upstream e2e suite, stock fetch         | [`5c5e2231…`](https://stellar.expert/explorer/testnet/tx/5c5e22318b070c120b15440a02c3c7365f6f23ed87157d48a024c59d9394753f) |
| `exact` | `G` (MCP agent)   | self-issued | agent, zero pre-integration             | [`0b149e8d…`](https://stellar.expert/explorer/testnet/tx/0b149e8d9f6f2290bb792d3ffe2125804d655caa43fbc159d8ef13c4972bf713) |
| `exact` | `C` smart account | self-issued | `__check_auth`, via verify and settle   | [`168929e9…`](https://stellar.expert/explorer/testnet/tx/168929e9a4282f2ce24991f06ae394ab5fb0600e9c7548a3b0438308f0464c78) |
| `upto`  | `G` keypair       | self-issued | 3.5M of a 10M ceiling                   | [`5e5d862c…`](https://stellar.expert/explorer/testnet/tx/5e5d862c88efe16592aa7a0671c4edb917f415481884ec526b62088ef846cce5) |
| `upto`  | `G` keypair       | real USDC   | 0.075 of a 0.20 ceiling                 | [`1fb4452b…`](https://stellar.expert/explorer/testnet/tx/1fb4452b7a095ffd848896d85aa59e4e3e60db3b90910c3238ade309e11c846e) |
| `upto`  | `C` smart account | self-issued | 750k of a 2M ceiling, budget reconciled | [`0d78d7cf…`](https://stellar.expert/explorer/testnet/tx/0d78d7cf58e4fe3c8cb5821918c88f033618b70f85c7372c3a242572fafae5e9) |

The two upstream-e2e rows are settlements produced by the unmodified x402 repository's own test clients pointed at Rail402, in real testnet USDC ([Conformance](/architecture/conformance)). The `C`-smart-account `upto` row demonstrates budget reconciliation: the on-ledger budget afterwards reads the actual 750k, not the 2M ceiling, which is only reachable if the settlement contract called the policy's `release` ([Smart accounts](/architecture/smart-accounts)).

## Deployed contracts

Both contracts are deployed on testnet and reproduce byte-for-byte from source with `stellar contract build`. Open either at `https://stellar.expert/explorer/testnet/contract/<address>`.

| Contract              | Address                                                                                                                        | wasm sha256                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `upto` settlement     | [`CCMM3FMG…C3U54X`](https://stellar.expert/explorer/testnet/contract/CCMM3FMGEH7FHRYXZ3WQDQCTIWDXGZBGW7D4UT7NKH34SUQACYC3U54X) | `a19f563e764dfd52a0d229c063e7ac1a1b36f6a976f552a8e19b91ee8e4ef84a` |
| Agent spending policy | [`CC3XJMYT…F7LEC`](https://stellar.expert/explorer/testnet/contract/CC3XJMYTTLQNDHOQHNQPQWLRIABQDUQBNJQKED7D67A3RMLGVQHF7LEC)  | `6d9307303a7f11e14b98530688e1cccb259fc35c537b71561429e77bc4aaa232` |

The smart-account layer reuses OpenZeppelin's audited [`stellar-accounts`](https://github.com/OpenZeppelin/stellar-contracts). The account and its ed25519 verifier (`CCC4DCEZ…`) are OpenZeppelin's; only the budget policy above is Rail402's. See [Smart accounts](/architecture/smart-accounts#composition-with-openzeppelin).

## Upstream contributions

Four Rail402 contributions are public upstream.

| Contribution                                      | Where                                                                            |
| ------------------------------------------------- | -------------------------------------------------------------------------------- |
| Merged into Stellar Developer Docs                | [`stellar/stellar-docs#2718`](https://github.com/stellar/stellar-docs/pull/2718) |
| `__check_auth` client fix (smart-account signing) | [`x402-foundation/x402#3018`](https://github.com/x402-foundation/x402/pull/3018) |
| `upto` for Stellar, proposed                      | [`stellar/x402-stellar#71`](https://github.com/stellar/x402-stellar/pull/71)     |
| `exact` and `upto` design, with SDF engineers     | [`stellar/x402-stellar#72`](https://github.com/stellar/x402-stellar/pull/72)     |

## Run the whole loop yourself

The end-to-end flow, settling a real payment, cataloging it, and finding it by natural-language search, is one command against the live facilitator.

```bash theme={null}
git clone https://github.com/tolgayayci/rail402 && cd rail402 && pnpm install
pnpm canary discovery-loop --facilitator https://facilitator.rail402.dev
```

It runs a stock `@x402` client through verify, settle, catalog, and search, and prints the settled transaction hash. The conformance harness ([`@rail402.dev/conformance`](/reference/conformance)) does the same against the upstream x402 e2e suite.

## Next steps

<CardGroup cols={2}>
  <Card title="Wire-level conformance" icon="clipboard-check" href="/architecture/conformance">
    How Rail402 interoperates with stock x402 clients.
  </Card>

  <Card title="The settlement path" icon="right-left" href="/architecture/settlement">
    What the facilitator does with a signed auth entry.
  </Card>

  <Card title="The upto scheme" icon="gauge" href="/architecture/upto">
    The contract behind the metered rows above.
  </Card>

  <Card title="Deployment" icon="server" href="/architecture/deployment">
    Where and how the live service runs.
  </Card>
</CardGroup>