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

# Bucketed activity series for charts

> UTC day- or hour-bucketed payment activity, zero-filled so a chart axis is continuous,
ending at the in-progress bucket (render the last point as "so far", not a drop).
Cached ~30s server-side.




## OpenAPI

````yaml /api-reference/explorer.openapi.yaml get /ecosystem/timeseries
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:
  /ecosystem/timeseries:
    get:
      tags:
        - payments
      summary: Bucketed activity series for charts
      description: >
        UTC day- or hour-bucketed payment activity, zero-filled so a chart axis
        is continuous,

        ending at the in-progress bucket (render the last point as "so far", not
        a drop).

        Cached ~30s server-side.
      operationId: getEcosystemTimeseries
      parameters:
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - day
              - hour
            default: day
        - name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 30
          description: Span in buckets when bucket=day
        - name: hours
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 168
            default: 48
          description: Span in buckets when bucket=hour
        - name: network
          in: query
          schema:
            type: string
      responses:
        '200':
          description: The zero-filled series
          content:
            application/json:
              schema:
                type: object
                required:
                  - bucket
                  - from
                  - to
                  - generatedAt
                  - points
                properties:
                  bucket:
                    type: string
                    enum:
                      - day
                      - hour
                  from:
                    type: string
                    format: date-time
                  to:
                    type: string
                    format: date-time
                  network:
                    type: string
                  generatedAt:
                    type: string
                    format: date-time
                  points:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimeseriesPoint'
        '400':
          description: Invalid bucket or span
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TimeseriesPoint:
      type: object
      required:
        - bucket
        - start
        - payments
        - uniqueBuyers
        - uniqueSellers
        - byScheme
        - volume
      properties:
        bucket:
          type: string
          description: 'UTC bucket key: "2026-08-15" (day) or "2026-08-15T10" (hour)'
        start:
          type: string
          format: date-time
          description: Bucket start instant
        payments:
          type: integer
        uniqueBuyers:
          type: integer
        uniqueSellers:
          type: integer
        byScheme:
          type: object
          additionalProperties:
            type: integer
        volume:
          type: array
          items:
            $ref: '#/components/schemas/AssetVolume'
    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
    AssetVolume:
      type: object
      required:
        - assetContract
        - count
        - total
        - totalDecimal
      properties:
        assetContract:
          type: string
        asset:
          type: string
          description: SEP-11 asset string ("native" | "CODE:ISSUER")
        assetCode:
          type: string
        count:
          type: integer
        total:
          type: string
          description: BigInt-safe integer-string sum (never a float, never 64-bit SQL)
        totalDecimal:
          type: string
          description: Human amount

````