openapi: 3.1.0
info:
  title: 8gentz Sovereign Agentic Gateway API
  description: |
    Protocol-agnostic ingress for autonomous AI agent swarms.
    
    ## Authentication
    
    This API uses the **x402 HTTP micropayment protocol** for authentication.
    No API keys, no accounts, no OAuth tokens required.
    
    1. Send any request — if payment is required you receive HTTP 402
    2. Sign the µUSDC micropayment from your DID-compatible wallet on Base (eip155:8453)
    3. Retry with payment proof in headers
    
    See [auth.md](https://8gentz.io/auth.md) for full instructions.
    
    ## Protocols
    
    The gateway supports 8 agent protocols:
    - **MCP** (Anthropic Model Context Protocol) — `mcp.8gentz.io`
    - **A2A** (Google Agent-to-Agent) — `a2a.8gentz.io`
    - **ANP** (Agent Network Protocol) — `anp.8gentz.io`
    - **ACP** (Coinbase Agent Commerce Protocol) — `acp.8gentz.io`
    - **OpenAI** compatible — `openai.8gentz.io`
    - **UCP** (Universal Commerce Protocol) — `ucp.8gentz.io`
    - **MPP** (Micropayment Protocol) — `mpp.8gentz.io`
    - **Nostr** — `nostr.8gentz.io`
  version: 1.0.0
  contact:
    name: 8gentz
    url: https://8gentz.io
    email: hello@8gentz.io
  license:
    name: Proprietary
    url: https://8gentz.io/legal/terms
  x-llm-description: |
    Use this API to route AI agent requests through the 8gentz gateway.
    Discover tools with GET /v1/tools, execute them with POST /v1/tools/{tool_name}.
    Authentication is x402 micropayments — no pre-registration needed.

servers:
  - url: https://gateway.8gentz.io
    description: Main gateway (all protocols)
  - url: https://mcp.8gentz.io
    description: MCP protocol endpoint
  - url: https://openai.8gentz.io
    description: OpenAI-compatible endpoint
  - url: https://a2a.8gentz.io
    description: A2A protocol endpoint

security:
  - x402: []

components:
  securitySchemes:
    x402:
      type: http
      scheme: x402
      description: |
        x402 HTTP micropayment protocol. Send request, receive 402 with payment details,
        sign µUSDC payment from DID-compatible wallet on Base (eip155:8453), retry.
        See https://8gentz.io/auth.md

  schemas:
    Tool:
      type: object
      required: [tool_name, description, input_schema]
      properties:
        tool_name:
          type: string
          description: Unique tool identifier
          example: get_sentiment_score
        description:
          type: string
          description: Human and agent-readable tool description
          example: Returns quantitative sentiment for a macro sector
        input_schema:
          type: object
          description: JSON Schema for tool input parameters
        cost_per_execution:
          type: integer
          description: Cost in µUSDC per execution
          example: 50
        app_id:
          type: string
          description: Application identifier
          example: my-app

    ToolRegistration:
      allOf:
        - $ref: '#/components/schemas/Tool'
        - type: object
          required: [backend_routing_url]
          properties:
            backend_routing_url:
              type: string
              format: uri
              description: Backend URL to route tool execution to
              example: http://10.0.10.45:9000/execute

    ToolExecution:
      type: object
      required: [tool_name, parameters]
      properties:
        tool_name:
          type: string
        parameters:
          type: object
          description: Tool input parameters matching the tool's input_schema

    ToolResult:
      type: object
      properties:
        result:
          description: Tool execution result
        audit_hash:
          type: string
          description: Autheo onchain audit transaction hash
        cost_charged:
          type: integer
          description: µUSDC charged for this execution
        zk_proof:
          type: string
          description: zk-STARK proof of execution (optional, for privacy)

    PaymentRequired:
      type: object
      properties:
        error:
          type: string
          example: payment_required
        payment_details:
          type: object
          properties:
            network:
              type: string
              example: eip155:8453
            currency:
              type: string
              example: USDC
            amount_micro_usdc:
              type: integer
              example: 1
            recipient:
              type: string
              example: "0xSAGP_VAULT_ADDRESS"
            operation:
              type: string
              example: discovery.tools.list

    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok, degraded, down]
          example: ok
        version:
          type: string
          example: 1.0.0
        protocols:
          type: array
          items:
            type: string
          example: [mcp, a2a, anp, acp, openai, ucp, mpp, nostr]
        pqc_active:
          type: boolean
          example: true
        audit_chain:
          type: string
          example: autheo

paths:
  /v1/health:
    get:
      operationId: getHealth
      summary: Gateway health check
      description: Returns gateway operational status, active protocols, and PQC status.
      tags: [Discovery]
      security: []
      responses:
        '200':
          description: Gateway is operational
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /v1/tools:
    get:
      operationId: listTools
      summary: List available tools
      description: |
        Returns all tools registered on the gateway, available across all 8 protocols.
        Requires x402 micropayment (0.5 µUSDC).
      tags: [Tools]
      responses:
        '200':
          description: List of available tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
                  total:
                    type: integer
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /v1/tools/{tool_name}:
    post:
      operationId: executeTool
      summary: Execute a tool
      description: |
        Execute a registered tool by name. Cost varies by tool (see cost_per_execution).
        Requires x402 micropayment. Result includes Autheo audit hash.
      tags: [Tools]
      parameters:
        - name: tool_name
          in: path
          required: true
          schema:
            type: string
          description: Tool name as returned by listTools
          example: get_sentiment_score
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolExecution'
      responses:
        '200':
          description: Tool executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '404':
          description: Tool not found

  /internal/register:
    post:
      operationId: registerTools
      summary: Register backend tools
      description: |
        Register one or more backend tools on the gateway. Once registered, tools are
        immediately available across all 8 supported protocols (MCP, A2A, ANP, ACP,
        OpenAI, UCP, MPP, Nostr).
        
        Requires cluster secret in X-App-Secret header (internal network only).
      tags: [Registration]
      security:
        - clusterSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ToolRegistration'
              example:
                - app_id: my-app
                  tool_name: get_sentiment_score
                  description: Returns quantitative sentiment for a macro sector
                  input_schema:
                    type: object
                    required: [sector]
                    properties:
                      sector:
                        type: string
                  backend_routing_url: http://10.0.10.45:9000/execute
                  cost_per_execution: 50
      responses:
        '200':
          description: Tools registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  registered:
                    type: integer
                    description: Number of tools registered
                  tools:
                    type: array
                    items:
                      type: string
                    description: Names of registered tools
        '401':
          description: Invalid cluster secret

  /v1/audit/{agent_did}:
    get:
      operationId: queryAuditLog
      summary: Query agent audit log
      description: |
        Query the Autheo onchain audit log for a specific agent DID.
        Returns operation history with transaction hashes and zk-STARK proofs.
      tags: [Audit]
      parameters:
        - name: agent_did
          in: path
          required: true
          schema:
            type: string
          description: Agent DID (e.g. did:web:agent.example.com or did:ethr:0x...)
          example: did:web:agent.example.com
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Audit records
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        operation:
                          type: string
                        tool_name:
                          type: string
                        cost_charged:
                          type: integer
                        tx_hash:
                          type: string
                        zk_proof:
                          type: string
        '402':
          description: Payment required

tags:
  - name: Discovery
    description: Gateway discovery and health endpoints
  - name: Tools
    description: Tool listing and execution
  - name: Registration
    description: Backend tool registration (internal)
  - name: Audit
    description: Onchain audit log queries

externalDocs:
  description: 8gentz Documentation
  url: https://8gentz.io/docs