AgentPay Session API

openapi: 3.2.0
info:
  title: AgentPay Gateway Session 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: Session
paths:
  /v1/session/create:
    head:
      summary: Session Create Probe
      operationId: session_create_probe_v1_session_create_head
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Session
    get:
      summary: Session Create Probe
      operationId: getV1SessionCreate
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Session
      x-operation-id-source: normalized
      x-operation-id-original: session_create_probe_v1_session_create_head
    post:
      summary: Create Session
      description: 'Open a budget-capped agent session for $0.01 USDC.


        Supports two payment paths:

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

        Base — PAYMENT-SIGNATURE:


        On verified payment returns:

        session_id — unique UUID for this session

        max_spend — budget cap from request body

        agent_address — paying agent''s address

        gateway_url — root of agentpay.tools

        tools_endpoint — where to call tools

        created_at — ISO 8601 timestamp

        receipt — tx_hash + network + amount'
      operationId: create_session_v1_session_create_post
      parameters:
      - 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:
              properties:
                agent_address:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Agent Address
                max_spend:
                  default: '0.10'
                  title: Max Spend
                  type: string
                label:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Label
                ttl_seconds:
                  anyOf:
                  - type: integer
                  - type: 'null'
                  title: Ttl Seconds
              title: SessionCreateRequest
              type: object
      tags:
      - Session
  /v1/session/{session_id}:
    get:
      summary: Get Session
      description: 'Server-side ledger for a session: cap, spent, remaining, receipts.'
      operationId: get_session_v1_session__session_id__get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
      tags:
      - Session
components:
  schemas:
    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