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

# Search the catalog

> Natural-language ranking over the catalog. The result array is `resources` (not `items`),
paginated by opaque cursor. A missing or empty `query` returns `400 invalid_payload`.




## OpenAPI

````yaml /api-reference/facilitator.openapi.yaml get /discovery/search
openapi: 3.1.0
info:
  title: Rail402 Facilitator API
  version: '2.0'
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: >
    The Rail402 x402 facilitator and Bazaar discovery layer on
    `stellar:testnet`.

    Verify and settle x402 payments, read what the facilitator supports, and
    browse or

    search the discovery catalog. Speaks the x402 v2 wire format, so a stock
    `@x402` client

    interoperates with no Rail402-specific code.


    Amounts are integer strings in atomic units at 7 decimals: one USDC is
    `10000000`, so

    `500000` is 0.05 USDC. Every rejection carries a machine `code`, a non-null
    `reason`, and a

    `retryable` flag.
servers:
  - url: https://facilitator.rail402.dev
    description: stellar:testnet
security: []
tags:
  - name: Payments
    description: Verify and settle payments
  - name: Discovery
    description: Browse and search the Bazaar catalog
  - name: Info
    description: Capabilities, health, and metrics
paths:
  /discovery/search:
    get:
      tags:
        - Discovery
      summary: Search the catalog
      description: >
        Natural-language ranking over the catalog. The result array is
        `resources` (not `items`),

        paginated by opaque cursor. A missing or empty `query` returns `400
        invalid_payload`.
      operationId: searchResources
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          example: current price of a commodity
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: The ranked results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Missing or empty query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402Error'
components:
  schemas:
    SearchResponse:
      type: object
      properties:
        x402Version:
          type: integer
          example: 2
        resources:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveryEntry'
        pagination:
          type:
            - object
            - 'null'
          properties:
            limit:
              type: integer
            cursor:
              type:
                - string
                - 'null'
        searchMethod:
          type: string
          example: hybrid (bm25+static-embedding, rrf)
        partialResults:
          type: boolean
    X402Error:
      type: object
      required:
        - code
        - reason
        - retryable
      properties:
        code:
          type: string
          example: invalid_network
        reason:
          type: string
        retryable:
          type: boolean
        details:
          type: object
          additionalProperties: true
    DiscoveryEntry:
      type: object
      properties:
        resource:
          type: string
          example: https://your-seller.example/quote
        type:
          type: string
          enum:
            - http
            - mcp
        accepts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRequirements'
        description:
          type: string
        lastUpdated:
          type: string
          format: date-time
        domainVerified:
          type: boolean
        quality:
          type: object
          properties:
            totalSettlements:
              type: integer
            uniquePayers:
              type: integer
    PaymentRequirements:
      type: object
      properties:
        scheme:
          type: string
          example: exact
        network:
          type: string
          example: stellar:testnet
        asset:
          type: string
          example: CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA
        amount:
          type: string
          description: Atomic units, integer string
          example: '500000'
        payTo:
          type: string
          example: GBOQSB3F...QR2
        maxTimeoutSeconds:
          type: integer
          example: 60
        extra:
          type: object
          additionalProperties: true

````