openapi: 3.2.0
info:
  title: x402 List Suggestions 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: Suggestions
  description: Post paid suggestions for the directory (feedback in x402)
paths:
  /suggestions:
    post:
      operationId: postSuggestion
      summary: Post a paid suggestion for the directory (F11)
      description: 'Suggest a change, feature, bug, or data fix for the x402 List directory itself. The feedback channel is paid in x402: every suggestion costs a one-time $0.10 USDC (x402) payment on Base, as anti-spam skin-in-the-game. There is NO refund. Suggestions are internal and manually reviewed; they are never published and there is no public roadmap. This endpoint is agent-first (JSON only). The paid flow is the standard x402 handshake: the first call (no PAYMENT-SIGNATURE) returns HTTP 402 with a PAYMENT-REQUIRED header and an accepts[] body (single option, $0.10 USDC on Base) plus the app-level error code suggestion_fee_required; sign the payment and retry the same request with a PAYMENT-SIGNATURE header. On success the 201 carries a PAYMENT-RESPONSE header. When the payment layer is not configured, the endpoint answers HTTP 503 (suggestions temporarily unavailable).'
      tags:
      - Suggestions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionRequest'
            example:
              text: Add a /api/v1/services bulk export endpoint for offline indexing
              category: feature
              email: agent@example.com
      responses:
        '201':
          description: Suggestion received, pending manual review
          headers:
            PAYMENT-RESPONSE:
              schema:
                type: string
              description: base64 JSON of the x402 SettleResponse (settlement receipt)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                        - received
                  provenance:
                    $ref: '#/components/schemas/Provenance'
        '400':
          description: Validation error (text missing or too long, invalid category or email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Payment required: send accepts[0] ($0.10 USDC on Base) with an x402-capable client and retry the same request with a PAYMENT-SIGNATURE header. The PAYMENT-REQUIRED response header carries the same x402 PaymentRequired object base64-encoded, without the app-level message field (which is body-only).'
          headers:
            PAYMENT-REQUIRED:
              schema:
                type: string
              description: base64 JSON of the x402 PaymentRequired object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
              example:
                x402Version: 2
                accepts:
                - scheme: exact
                  network: eip155:8453
                  asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                  amount: '100000'
                  payTo: '0x0000000000000000000000000000000000000000'
                  maxTimeoutSeconds: 300
                  extra:
                    name: USD Coin
                    version: '2'
                resource:
                  url: https://x402-list.com/api/v1/suggestions
                  description: Suggestion fee for x402 List directory feedback
                  mimeType: application/json
                  serviceName: x402 List
                error: suggestion_fee_required
                message: 'Posting a suggestion to the x402 List directory requires a $0.10 x402 payment on Base (USDC). Pay with an x402-capable client: send the request again with a PAYMENT-SIGNATURE header. See https://x402-list.com/api for the flow.'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: The payment layer is not configured, so the suggestion box is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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
  schemas:
    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'
    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
    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)
    SuggestionRequest:
      type: object
      description: Paid suggestion body (F11). Only "text" is required; the request must be paid ($0.10 USDC on Base via the x402 handshake). Suggestions are internal and manually reviewed, never published.
      required:
      - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 2000
          description: The suggestion (1 to 2000 characters)
        category:
          type: string
          enum:
          - feature
          - bug
          - data
          - other
          default: other
          description: Suggestion category (defaults to "other" when omitted)
        email:
          type: string
          format: email
          description: 'Optional contact email: receives the review outcome'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string