openapi: 3.2.0
info:
  title: x402 List Reference API
  version: 1.0.0
  description: Public REST API for x402-list.com - the directory of all services using the x402 protocol (HTTP 402 Payment Required).
  contact:
    name: x402 List
    url: https://x402-list.com
    email: info@x402-list.com
  termsOfService: https://x402-list.com/terms
  license:
    name: MIT
  x-data-license: CC-BY-4.0
servers:
- url: https://x402-list.com/api/v1
  description: Production
tags:
- name: Reference
  description: 'Reference data: supported networks, categories, and service tags'
paths:
  /networks:
    get:
      operationId: getNetworks
      summary: List supported blockchain networks
      description: Returns all blockchain networks that x402 services accept payments on. Each network includes a service count and average uptime. Uses CAIP-2 identifiers.
      tags:
      - Reference
      responses:
        '200':
          description: Array of networks with stats. meta.avg_uptime_method declares the aggregation method (identical to /stats).
          headers:
            X-Meter-Remaining:
              $ref: '#/components/headers/MeterRemaining'
            X-Meter-Reset:
              $ref: '#/components/headers/MeterReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Network'
                  meta:
                    type: object
                    properties:
                      avg_uptime_method:
                        type: string
                  provenance:
                    $ref: '#/components/schemas/Provenance'
        '402':
          $ref: '#/components/responses/MeteredPaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /categories:
    get:
      operationId: getCategories
      summary: List service categories
      description: Returns the distinct list of categories currently used by listed services. Useful for populating filter dropdowns or submission forms.
      tags:
      - Reference
      responses:
        '200':
          description: List of category strings
          headers:
            X-Meter-Remaining:
              $ref: '#/components/headers/MeterRemaining'
            X-Meter-Reset:
              $ref: '#/components/headers/MeterReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                  provenance:
                    $ref: '#/components/schemas/Provenance'
              example:
                data:
                - AI
                - Blockchain
                - Compute
                - Content
                - Data
                - Finance
                - Other
                - Verification
        '402':
          $ref: '#/components/responses/MeteredPaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 429
              message: Too many requests. Please slow down.
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 500
              message: Internal server error
    MeteredPaymentRequired:
      description: 'Metered: this IP is beyond the free daily quota (2,000 GET requests/day per IP on /api/v1/*). Each further request costs $0.01 USDC (x402) on Base. Pay accepts[0] with an x402-capable client and retry the same request with a PAYMENT-SIGNATURE header; the successful response then carries a PAYMENT-RESPONSE header. The PAYMENT-REQUIRED response header carries the same x402 PaymentRequired object base64-encoded, without the app-level message field (body only).'
      headers:
        PAYMENT-REQUIRED:
          schema:
            type: string
          description: base64 JSON of the x402 PaymentRequired object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
  schemas:
    Provenance:
      type: object
      description: Data provenance and license block. Present once per response, top-level in the envelope alongside data (and meta where present), never per item. Declares the CC BY 4.0 data license and how to attribute this data.
      properties:
        license:
          type: string
          enum:
          - CC-BY-4.0
          description: SPDX identifier of the data license (Creative Commons Attribution 4.0 International).
        attribution_required:
          type: boolean
          description: Whether attribution is required when reusing this data (always true under CC BY 4.0).
        attribution:
          type: string
          description: Ready-to-use attribution string to display when reusing this data.
          example: 'Data: x402-list.com (CC BY 4.0)'
        cite_as:
          type: string
          format: uri
          description: 'Canonical URL to cite as the source of this specific resource: the human-readable page where one exists, otherwise the request URL without its query string.'
          example: https://x402-list.com/services/acme-generate
        source:
          type: string
          format: uri
          description: Canonical site origin behind the directory.
          example: https://x402-list.com
    Network:
      type: object
      description: A blockchain network that x402 services accept payments on
      properties:
        id:
          type: string
          format: uuid
        caip2_id:
          type: string
          description: CAIP-2 chain identifier as stored (may be lowercase, e.g. the Solana reference); kept for backwards compatibility. Prefer caip2 for joins.
          example: eip155:8453
        caip2:
          type: string
          description: Canonical CAIP-2 identifier for cross-endpoint joins (exact casing, Solana reference truncated to 32 chars). Matches network_caip2 in service pricing and facilitator chains. Falls back to caip2_id for networks not yet in the canonical map.
          example: eip155:8453
        name:
          type: string
          example: Base
        abbreviation:
          type: string
          example: BSE
        chain_type:
          type: string
          example: evm
        is_mainnet:
          type: boolean
        explorer_url:
          type: string
          format: uri
        service_count:
          type: integer
          description: Number of services accepting payments on this network
        avg_uptime:
          type: number
          description: Per-service mean of the latest daily uptime rollup for services on this network (see meta.avg_uptime_method)
    PaymentRequired:
      type: object
      description: x402 v2 PaymentRequired body returned on a 402 (also base64-encoded in the PAYMENT-REQUIRED response header).
      properties:
        x402Version:
          type: integer
          enum:
          - 2
        accepts:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRequirements'
        resource:
          type: object
          description: The paid resource this 402 guards (echoed by the x402 server).
          properties:
            url:
              type: string
              example: https://x402-list.com/api/v1/submit
            description:
              type: string
              example: Resubmission fee after a rejected submission
            mimeType:
              type: string
              example: application/json
            serviceName:
              type: string
              example: x402 List
        error:
          type: string
          description: App-level error code, e.g. resubmission_fee_required
        message:
          type: string
          description: Human-readable explanation with a pointer to /api (body only; absent from the PAYMENT-REQUIRED header)
    PaymentRequirements:
      type: object
      description: A single x402 payment option (one element of accepts[]).
      properties:
        scheme:
          type: string
          enum:
          - exact
        network:
          type: string
          description: CAIP-2 network id
          example: eip155:8453
        asset:
          type: string
          description: Token contract address
          example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
        amount:
          type: string
          description: Atomic USDC (6 decimals) as a string; "500000" = $0.50
          example: '500000'
        payTo:
          type: string
          description: Receiving wallet address
        maxTimeoutSeconds:
          type: integer
          example: 300
        extra:
          type: object
          description: EIP-712 signing domain parameters
          properties:
            name:
              type: string
              example: USD Coin
            version:
              type: string
              example: '2'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
  headers:
    MeterReset:
      schema:
        type: integer
      description: 'Unix timestamp (seconds) at which this IP''s free daily metered-GET quota resets: the next 00:00 UTC. Same shape as X-RateLimit-Reset. Lets a caller behind a shared egress IP tell when the per-IP quota rolls over.'
    MeterRemaining:
      schema:
        type: integer
      description: Free metered GET requests left today for this IP (see the metering note in the API description).