> ## 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. # Self-register a facilitator (no auth needed — by design) > Any x402 facilitator can announce its base URL. The explorer validates the URL (https, publicly routable), probes `GET {baseUrl}/supported` ITSELF, and registers only what it verified: the signer set and any advertised upto contract. From then on the facilitator's settlements are attributed to it and its `/supported` is re-polled automatically. An announcement is a lead, never a fact — nothing posted here can inflate a facilitator's standing, which is why the endpoint needs no authentication. Facilitators running the Rail402 codebase announce automatically when `FACILITATOR_PUBLIC_URL` is set (default-on heartbeat). ## OpenAPI ````yaml /api-reference/explorer.openapi.yaml post /announce openapi: 3.1.0 info: title: Rail402 Explorer API version: 0.1.0 summary: x402 payments explorer for Stellar description: > Read-only public API over x402 payment activity observed on Stellar. The explorer watches the ledger directly (Soroban RPC + Horizon), classifies x402 settlements structurally — no facilitator registration is required for a payment to appear — attributes each payment to the facilitator that submitted it, and enriches sellers via the x402 Bazaar. **Amounts** are stroop-scale integer strings (7 decimals). Every amount field has a `…Decimal` companion for display; never do arithmetic on the decimal form. **Confidence tiers** (every payment carries one; inference is never presented as fact): - `rail402` — submitted by the Rail402 deployment's published signer. - `verified-facilitator` — submitter matches a registered facilitator's live `/supported` signers. - `x402-shaped` — structurally an x402 settlement, submitter unknown. **History**: the full Soroban RPC retention window (~7 days) is backfilled for all facilitators including unknown ones, and every registry-verified facilitator's complete chain-epoch history (back to the 2025-12-17 testnet reset) is recovered from Horizon. Horizon-recovered rows have no `asset`/`assetCode` (that string only exists in event data); `assetContract` is always present. **Errors** are always `{ code, reason, retryable, details? }` — branch on `code`, never parse `reason`. CORS is open (`*`): browsers may call this API directly. servers: - url: https://explorer-explorer.up.railway.app description: stellar:testnet security: [] tags: - name: payments description: The payment stream and per-transaction detail - name: entities description: Sellers and facilitators - name: registry description: Facilitator self-registration - name: ops description: Health and metrics paths: /announce: post: tags: - registry summary: Self-register a facilitator (no auth needed — by design) description: > Any x402 facilitator can announce its base URL. The explorer validates the URL (https, publicly routable), probes `GET {baseUrl}/supported` ITSELF, and registers only what it verified: the signer set and any advertised upto contract. From then on the facilitator's settlements are attributed to it and its `/supported` is re-polled automatically. An announcement is a lead, never a fact — nothing posted here can inflate a facilitator's standing, which is why the endpoint needs no authentication. Facilitators running the Rail402 codebase announce automatically when `FACILITATOR_PUBLIC_URL` is set (default-on heartbeat). operationId: announceFacilitator requestBody: required: true content: application/json: schema: type: object required: - baseUrl properties: baseUrl: type: string format: uri example: https://your-facilitator.example.com responses: '200': description: Verified and registered content: application/json: schema: type: object required: - facilitator properties: facilitator: $ref: '#/components/schemas/Facilitator' '400': description: URL refused before any request was made content: application/json: schema: $ref: '#/components/schemas/Error' example: code: explorer_announce_invalid_url reason: >- The announced facilitator base URL was refused: it must be an https URL on a publicly routable host. retryable: false '502': description: The facilitator's /supported did not answer or was invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: code: explorer_announce_unreachable reason: >- The announced facilitator did not serve a valid /supported response, so it was not registered. retryable: true components: schemas: Facilitator: type: object required: - id - baseUrl - verified - signers - uptoContracts - networks - source - createdAt properties: id: type: string example: x402-org displayName: type: string example: x402.org baseUrl: type: string example: https://x402.org/facilitator verified: type: boolean description: >- True once the explorer itself fetched a valid /supported from baseUrl signers: type: array items: type: string description: >- Checksum-validated Stellar signer addresses from /supported (re-polled every 5 min) uptoContracts: type: array items: type: string description: upto settlement contracts advertised in /supported extra networks: type: array items: type: string source: type: string enum: - seed - announce lastSeenAt: type: string format: date-time lastError: type: string description: Last probe failure; stale signers are kept over none createdAt: type: string format: date-time Error: type: object required: - code - reason - retryable properties: code: type: string description: >- Stable machine-readable identifier — branch on this, never on `reason` reason: type: string description: Non-null human-legible explanation retryable: type: boolean description: Whether an identical retry could plausibly succeed details: type: object additionalProperties: true ````