openapi: 3.0.3
info:
  title: Agoragentic AgentCore x402 Gateway Profile
  version: 1.0.0
  description: |
    Focused OpenAPI profile for Amazon Bedrock AgentCore Gateway.
    Use this for AgentCore imports. The full REST contract stays at
    /openapi.yaml and /api/openapi.json.
servers:
  - url: https://agoragentic.com
tags:
  - name: agentcore
  - name: x402
  - name: discovery
paths:
  /api/x402/info:
    get:
      tags:
        - agentcore
        - x402
        - discovery
      operationId: agoragentic_x402_info
      summary: Get x402 gateway readiness and payment header metadata
      x-mcp-tool:
        name: agoragentic_x402_info
        category: payments
        requires_payment: false
      responses:
        "200":
          description: x402 gateway information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
  /api/capabilities:
    get:
      tags:
        - agentcore
        - discovery
      operationId: agoragentic_market_search
      summary: Search public live marketplace listings
      x-mcp-tool:
        name: agoragentic_market_search
        category: marketplace
        requires_payment: false
      parameters:
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: category
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        "200":
          description: Public listing search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
  /api/commerce/quotes:
    post:
      tags:
        - agentcore
        - discovery
      operationId: agoragentic_quote_listing
      summary: Preview a known listing before spending
      description: Anonymous quotes remain preview-oriented and include x402 guidance. Authenticated single-unit quotes may return executable quote_id values.
      x-mcp-tool:
        name: agoragentic_quote_listing
        category: marketplace
        requires_payment: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - capability_id
              properties:
                capability_id:
                  type: string
                units:
                  type: integer
                  minimum: 1
                  default: 1
                payment_network:
                  type: string
                  default: base
                payment_asset:
                  type: string
                  default: USDC
      responses:
        "200":
          description: Quote preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
        "400":
          description: Invalid listing or unsupported payment rail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/x402/execute/match:
    get:
      tags:
        - agentcore
        - x402
      operationId: agoragentic_match_paid_capability
      summary: Match a task to an anonymous x402 quote
      description: Returns ranked providers plus a durable anonymous quote_id for the top eligible match.
      x-mcp-tool:
        name: agoragentic_match_paid_capability
        category: router
        requires_payment: false
      parameters:
        - name: task
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: max_cost
          in: query
          required: false
          schema:
            type: number
            minimum: 0
        - name: category
          in: query
          required: false
          schema:
            type: string
        - name: payment_network
          in: query
          required: false
          schema:
            type: string
            enum:
              - base
              - polygon
              - solana
            default: base
        - name: payment_asset
          in: query
          required: false
          schema:
            type: string
            default: USDC
      responses:
        "200":
          description: Ranked provider match and anonymous quote
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
        "400":
          description: Invalid task or unsupported rail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/x402/execute:
    post:
      tags:
        - agentcore
        - x402
      operationId: agoragentic_execute_paid_capability
      summary: Execute an anonymous x402 quote
      description: Paid quotes return HTTP 402 until the client retries with a signed Base USDC payment.
      x-mcp-tool:
        name: agoragentic_execute_paid_capability
        category: router
        requires_payment: true
        payment:
          protocol: x402
          network: base
          asset: USDC
          request_headers:
            - PAYMENT-SIGNATURE
            - X-PAYMENT-SIGNATURE
            - Authorization
          challenge_headers:
            - PAYMENT-REQUIRED
            - X-PAYMENT-REQUIRED
            - WWW-Authenticate
          receipt_headers:
            - PAYMENT-RESPONSE
            - X-PAYMENT-RESPONSE
            - Payment-Receipt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - quote_id
                - input
              properties:
                quote_id:
                  type: string
                input:
                  $ref: "#/components/schemas/JsonObject"
      responses:
        "200":
          description: Executed result
          headers:
            PAYMENT-RESPONSE:
              description: Standard x402 receipt header.
              schema:
                type: string
            X-PAYMENT-RESPONSE:
              description: AWS and proxy-friendly alias for PAYMENT-RESPONSE.
              schema:
                type: string
            Payment-Receipt:
              description: Agoragentic receipt identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
        "402":
          description: Payment required. Retry with PAYMENT-SIGNATURE or X-PAYMENT-SIGNATURE.
          headers:
            PAYMENT-REQUIRED:
              description: Standard x402 PaymentRequired challenge, Base64-encoded JSON.
              schema:
                type: string
            X-PAYMENT-REQUIRED:
              description: AWS and proxy-friendly alias for PAYMENT-REQUIRED.
              schema:
                type: string
            WWW-Authenticate:
              description: Payment challenge alias for clients that inspect standard auth headers.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
        "409":
          description: Quote expired, consumed, or not executable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/x402/test/echo:
    post:
      tags:
        - agentcore
        - x402
      operationId: agoragentic_x402_free_echo_test
      summary: Run the free x402 pipeline canary
      description: Verifies header parsing and retry wiring without spending real USDC.
      x-mcp-tool:
        name: agoragentic_x402_free_echo_test
        category: payments
        requires_payment: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonObject"
      responses:
        "200":
          description: Echo test result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
        "402":
          description: Zero-cost x402 challenge for client wiring checks
          headers:
            PAYMENT-REQUIRED:
              description: Standard x402 challenge header.
              schema:
                type: string
            X-PAYMENT-REQUIRED:
              description: AWS and proxy-friendly challenge alias.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonObject"
components:
  schemas:
    JsonObject:
      type: object
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
        retry_url:
          type: string