openapi: 3.0.3
info:
  title: a2apay Agent API
  description: >
    Pay-per-call AI query and persistent memory services for autonomous
    agents, backed by redundant Internet Computer (ICP) canisters. Payment
    is required via the x402 protocol (HTTP 402) in USDC on Base mainnet
    (eip155:8453). No API keys or accounts — the payment itself is the
    authentication.
  version: "1.0.0"
  contact:
    url: https://a2apay.io
servers:
  - url: https://a2apay.io
    description: Production

paths:
  /api/agent-service:
    post:
      operationId: agentQuery
      summary: On-demand AI query
      description: >
        Submit a prompt and receive a real AI-generated answer. Backed by
        autonomous ICP canisters for bookkeeping and revenue-split
        settlement. Requires x402 payment of $0.028 USDC on Base per
        request.
      tags: [agent-service]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  description: The question or instruction to send to the AI.
                  example: "What's 7 times 8?"
      responses:
        "200":
          description: Successful AI response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: string
                    description: The AI-generated answer text.
                    example: "7 times 8 is 56."
        "400":
          description: Missing or invalid "prompt" field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: >
            Payment required. Returns the x402 payment challenge — price,
            payTo address, network, and asset — that must be satisfied
            and retried with a signed payment attached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/X402PaymentRequired"
        "405":
          description: Method not allowed (only POST is supported on this route).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Upstream AI call or fulfillment failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/agent-memory:
    post:
      operationId: agentMemoryWrite
      summary: Persistent agent memory storage
      description: >
        Store a key/value entry (with optional tags) in persistent,
        redundant ICP-backed storage. Requires x402 payment of $0.028
        USDC on Base per write.
      tags: [agent-memory]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [key, val]
              properties:
                key:
                  type: string
                  description: The memory key to store under.
                val:
                  type: string
                  description: The value to store.
                tags:
                  type: array
                  items:
                    type: string
                  description: Optional tags for categorizing the memory entry.
      responses:
        "200":
          description: Write recorded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  result:
                    type: boolean
                    example: true
        "402":
          description: >
            Payment required. Returns the x402 payment challenge — price,
            payTo address, network, and asset — that must be satisfied
            and retried with a signed payment attached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/X402PaymentRequired"
        "403":
          description: Router denied or failed the write.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "405":
          description: Method not allowed (only POST is supported on this route).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          description: Storage backend failure.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string

    X402PaymentRequired:
      type: object
      description: >
        Standard x402 v2 payment-required response. The `accepts` array
        lists acceptable payment options; the client signs and retries
        with a valid `payment-signature` header.
      properties:
        x402Version:
          type: integer
          example: 2
        accepts:
          type: array
          items:
            type: object
            properties:
              scheme:
                type: string
                example: exact
              network:
                type: string
                example: eip155:8453
              amount:
                type: string
              asset:
                type: string
                description: ERC-20 token contract address (USDC on Base).
              payTo:
                type: string
                description: Address funds are paid to.
              maxTimeoutSeconds:
                type: integer
                example: 60
        resource:
          type: object
          properties:
            url:
              type: string
            description:
              type: string
            serviceName:
              type: string
            tags:
              type: array
              items:
                type: string
            iconUrl:
              type: string