> ## 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.

# Operate a facilitator

> The operator's path: run Rail402, choose networks and assets, sponsor fees, and what the facilitator checks before it settles.

A facilitator verifies x402 payments, submits them and pays their network fees from its sponsor account; it
is never the source of the funds. Rail402 is built on the unmodified `@x402/stellar` scheme and also runs the
Bazaar catalog and search. This page walks the operator's path.

## 1. Run it on testnet

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/tolgayayci/rail402 && cd rail402
./deploy/docker.sh               # builds the image, creates and funds a testnet sponsor, starts Postgres and the service
curl http://127.0.0.1:8080/supported
```

[Run your own (Docker)](https://docs.rail402.dev/facilitator/docker.md) has the details; the facilitator can also run
[in process](https://docs.rail402.dev/facilitator/in-process.md) inside a seller. Point the [seller quickstart](https://docs.rail402.dev/quickstart/sellers.md) at
your URL with `FACILITATOR_URL` and pay it with the [buyer quickstart](https://docs.rail402.dev/quickstart/buyers.md).

## 2. Choose the networks

`NETWORKS` lists the networks served (`stellar:testnet`, `stellar:pubnet`); every per-network setting has a
`TESTNET_` or `PUBNET_` prefix ([Configuration](https://docs.rail402.dev/configuration.md#per-network)). `/supported` lists each served
network's kinds (`exact`, and `upto` where enabled) and its signers.

Pubnet settings are explicit, and the service refuses to start without them: an https RPC URL, a decision on
API keys (`PUBNET_REQUIRE_API_KEY`) and an hourly sponsor budget
(`PUBNET_MAX_SPONSOR_SPEND_XLM_PER_HOUR`); channel accounts are provisioned by an operator, not at startup.
Pubnet has not been exercised end to end; see [Configuration](https://docs.rail402.dev/configuration.md) and
[Operations](https://docs.rail402.dev/operations.md) before enabling it.

## 3. Choose the assets

Each network accepts Circle USDC by default. `ASSETS` lists every accepted SEP-41 token as
`CONTRACT:SYMBOL:DECIMALS[:MIN:MAX]`; the service reads each token's `decimals()` at startup and refuses a
mismatch ([Accepted assets](https://docs.rail402.dev/facilitator/assets.md)).

## 4. Trustlines and recipients

Before simulating, the facilitator checks that the payer can pay and that `payTo` can receive: for a Stellar
Asset Contract, a `G…` account needs an authorized trustline
(`invalid_exact_stellar_payload_payer_trustline_missing`,
`invalid_exact_stellar_payload_recipient_trustline_missing`). The sponsor and channel accounts hold XLM only;
they need no trustline, because they never hold the payment asset. A muxed `M…` `payTo` is refused for
`exact`.

## 5. What the buyer authorized, and what the facilitator checks

* **`exact`**: one Soroban authorization entry for `transfer(payer, payTo, amount)`, with address
  credentials. Rail402 checks the entry before any simulation: no facilitator account in it, no
  sub-invocations, the payer's signature present, the invocation identical to the transaction's call, and
  `signatureExpirationLedger` not past (`invalid_exact_stellar_signature_expired`) and at least
  `EXPIRATION_MARGIN_LEDGERS` ahead (`…_expiration_too_soon`); the upstream verifier refuses one too far ahead
  ([Authorization and expiry](https://docs.rail402.dev/verification-rules.md#5-authorization-and-expiry),
  [Expiration](https://docs.rail402.dev/verification-rules.md#expiration)).
* **`upto`**: signed terms with a cap for the `upto` settlement contract. The facilitator's settlement
  authority authorizes the settled amount, and the contract checks `0 ≤ amount ≤ cap`
  ([upto payments](https://docs.rail402.dev/facilitator/upto.md), [upto contract](https://docs.rail402.dev/reference/upto-contract.md)).

Every rejection has a stable code and a reason ([Errors and verification rules](https://docs.rail402.dev/verification-rules.md)).

## 6. Sponsor the fees

The sponsor account (`SPONSOR_SECRET`) pays every fee through a fee bump around a transaction whose source is
one of its channel accounts, so settlements run in parallel (`CHANNEL_COUNT`). `/supported` advertises
`extra.areFeesSponsored: true`. Fee ceilings (`MAX_TX_FEE_STROOPS`, `UPTO_MAX_TX_FEE_STROOPS`), a reserve
(`SPONSOR_RESERVE_XLM`) and an hourly budget bound what the sponsor may spend
([fee ceilings](https://docs.rail402.dev/configuration.md#fee-ceilings), [Operations](https://docs.rail402.dev/operations.md)).

## 7. Run the Bazaar

A settled payment that carries the `bazaar` extension is cataloged and searchable; with `STORE=postgres` (the
default) the catalog is durable and shared by every replica. See [Cataloging](https://docs.rail402.dev/bazaar/cataloging.md), [Discovery](https://docs.rail402.dev/bazaar/discovery.md) and
[Search](https://docs.rail402.dev/bazaar/search.md). The catalog lists only resources on public hosts; to see a seller on your own
machine listed and searchable, follow [Try the Bazaar locally](https://docs.rail402.dev/facilitator/docker.md#try-the-bazaar-locally). The
[hosted discovery MCP](https://docs.rail402.dev/agents/hosted-mcp.md) image serves the catalog's search to remote agents with no key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.