AgentPay Tools API

openapi: 3.2.0
info:
  title: AgentPay Gateway Tools API
  description: Buyer-side trust layer for x402 agents. verified_route ranks providers on paid delivery evidence and sybil-collapsed payer counts; pre_trade_check returns an ok/caution/avoid verdict before a trade; session_create opens a spend cap the gateway enforces for the paying wallet on Stacks and Base, with chain-verified receipts on a public ledger. USDC on Base and Stellar, sBTC or STX on Stacks (any Stacks x402 client).
  contact:
    name: AgentPay
    url: https://agentpay.tools/
    email: romudille@gmail.com
  version: 0.1.0
tags:
- name: Tools
paths:
  /tools:
    get:
      summary: List Tools
      description: List all available tools with pricing (HTML for browsers, JSON default).
      operationId: list_tools_tools_get
      parameters:
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
  /tools/{tool_name}:
    head:
      summary: Get Tool
      description: 'Get details for a specific tool. Supports legacy aliases.


        Browsers (Accept: text/html) get a server-rendered, indexable page;

        agents keep the JSON contract.'
      operationId: get_tool_tools__tool_name__head
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
    get:
      summary: Get Tool
      description: 'Get details for a specific tool. Supports legacy aliases.


        Browsers (Accept: text/html) get a server-rendered, indexable page;

        agents keep the JSON contract.'
      operationId: getToolsByToolName
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
      x-operation-id-source: normalized
      x-operation-id-original: get_tool_tools__tool_name__head
  /tools/{tool_name}/call:
    head:
      summary: Head Tool
      description: 'HEAD pre-flight for x402 discovery — answers 402, mirroring the GET probe.


        Probers scoring "does the resource return 402?" treat any other status as

        a failure, so HEAD returns the same 402 challenge as GET

        /tools/{name}/call (status + PAYMENT-REQUIRED header incl.

        extensions.bazaar, no pending row) with an empty body per HEAD semantics.

        The X-Price-USDC/X-Pay-To pre-flight headers are kept for cost-check

        callers.'
      operationId: head_tool_tools__tool_name__call_head
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
    get:
      summary: Call Tool Get
      description: 'x402 discovery crawlers probe resources with GET — answer with the

        same 402 challenge POST issues, so the validation crawl can read the

        PAYMENT-REQUIRED header (incl. extensions.bazaar). Without this the

        crawl gets a 405 and the listing never leaves ''processing''.'
      operationId: call_tool_get_tools__tool_name__call_get
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
    post:
      summary: Call Tool
      description: 'Main endpoint — call a paid MCP tool.


        Supports two payment paths:

        Stellar — X-Payment: tx_hash=,from=,id=

        Base — PAYMENT-SIGNATURE:


        Flow:

        1. Neither header → _issue_402 (advertise both options) — the body is

        parsed leniently first: a bare/malformed POST still gets the 402,

        never a 422.

        2. X-Payment → _settle_stellar, then _execute_and_log

        3. PAYMENT-SIGNATURE + $0 tool → _settle_free_v2 (no on-chain settle)

        4. PAYMENT-SIGNATURE → _settle_base_path, then _execute_and_log

        (2–4 validate the body strictly before settling, so a malformed paid

        call 422s without burning the payment.)'
      operationId: call_tool_tools__tool_name__call_post
      parameters:
      - name: tool_name
        in: path
        required: true
        schema:
          type: string
          title: Tool Name
      - name: x-payment
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Payment
      - name: x-agent-address
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Address
      - name: payment-signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment-Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              description: 'Body of POST /tools/{name}/call.


                Canonical shape nests tool arguments under "parameters", but some

                clients send them at the top level ({"symbol": "SOL"} instead of

                {"parameters": {"symbol": "SOL"}}). Pydantic used to silently discard

                unknown keys, so those calls ran on tool defaults with no error. The

                validator below folds unrecognized top-level keys into `parameters`

                whenever `parameters` itself is empty, so both shapes work; nested

                callers are byte-for-byte unaffected.'
              properties:
                parameters:
                  default: {}
                  title: Parameters
                  type: object
                agent_address:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Agent Address
              title: ToolCallRequest
              type: object
      security: []
      tags:
      - Tools
  /tools/register:
    post:
      summary: Register Tool
      description: 'Register a new MCP tool in the marketplace.


        Registration is gated because a tool carries a developer_address (the

        revenue-split recipient) and an endpoint the gateway will call:

        - 404 when TOOL_REGISTER_SECRET is unset (registration off — there is

        no third-party developer flow yet)

        - 401 unless X-Register-Secret matches (constant-time compare)

        - 422 unless name/price/addresses/endpoint validate; endpoints must be

        https and resolve only to public addresses'
      operationId: register_tool_tools_register_post
      parameters:
      - name: x-register-secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Register-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterToolRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Tools
components:
  schemas:
    RegisterToolRequest:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        endpoint:
          type: string
          title: Endpoint
        price_usdc:
          type: string
          title: Price Usdc
        developer_address:
          type: string
          title: Developer Address
        parameters:
          type: object
          title: Parameters
        category:
          type: string
          title: Category
          default: data
      type: object
      required:
      - name
      - description
      - endpoint
      - price_usdc
      - developer_address
      - parameters
      title: RegisterToolRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError