openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "AAAA Nexus API",
    "version": "0.5.1",
    "description": "Formally verified AI safety APIs for autonomous agents. Supports REST, MCP, A2A (Google protocol), and x402 micropayment protocol.",
    "contact": {
      "email": "atomadic@proton.me",
      "url": "https://github.com/atomadictech/aaaa-nexus"
    }
  },
  "servers": [
    {
      "url": "https://atomadic.tech",
      "description": "Production"
    }
  ],
  "security": [],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key obtained from https://atomadic.tech/pay"
      },
      "X402PaymentProof": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment-Proof",
        "description": "Base64-encoded USDC payment proof for x402 autonomous payment flow (Base L2, Polygon, or Solana)"
      },
      "AdminTokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Admin-Token",
        "description": "Admin token for privileged operations"
      }
    },
    "responses": {
      "PaymentRequired": {
        "description": "Payment required. Use x402 protocol: send USDC on Base L2, Polygon, or Solana to the treasury address provided in the response, then retry with the X-Payment-Proof header.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string", "example": "Payment required" },
                "amount": { "type": "string", "example": "0.002" },
                "currency": { "type": "string", "example": "USDC" },
                "treasury": { "type": "string", "description": "Destination wallet address" },
                "chains": {
                  "type": "array",
                  "items": { "type": "string" },
                  "example": ["base", "polygon", "solana"]
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string", "example": "Unauthorized" }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request body or missing required fields.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "HelixStatus": {
        "type": "object",
        "description": "HELIX integrity subsystem status",
        "properties": {
          "anti_hallucination": { "type": "boolean" },
          "ecc_status": { "type": "boolean" },
          "integrity_parity": { "type": "boolean" }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["user", "assistant", "system"],
            "description": "Message role"
          },
          "content": {
            "type": "string",
            "description": "Message content"
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Free", "description": "Endpoints that require no authentication or payment" },
    { "name": "Oracle", "description": "Entropy oracle and hallucination detection" },
    { "name": "Security", "description": "RatchetGate session security, identity verification, threat scoring, and compliance" },
    { "name": "Agents", "description": "Agent registration, topology, planning, intent classification, and reputation" },
    { "name": "Inference", "description": "LLM inference with built-in hallucination guard" },
    { "name": "Text", "description": "Text processing utilities: summarization, sentiment, NER, translation, and more" },
    { "name": "Protocol", "description": "Protocol discovery endpoints: MCP and A2A agent card" },
    { "name": "DeFi", "description": "Decentralized finance: LP optimization, risk scoring, oracle guard, liquidation shield, bridge proof, contract audit, yield oracle" },
    { "name": "Compliance", "description": "Regulatory compliance: EU AI Act, fairness, explainability, lineage, oversight, incidents, transparency" },
    { "name": "Payments", "description": "Stripe payment sessions, price listing, and payment verification" },
    { "name": "Forge", "description": "Model marketplace: leaderboard, quarantine, verification, delta submission, badges" },
    { "name": "Shield", "description": "AAAA Shield: post-quantum key exchange, session management, key rotation" },
    { "name": "Delegation", "description": "UCAN delegation chain validation, revocation, and depth queries" },
    { "name": "UCAN", "description": "UCAN token creation, verification, revocation, and delegation" },
    { "name": "Keys", "description": "Cryptographic key generation, rotation, and revocation" },
    { "name": "Credits", "description": "Credit balance, usage history, and detailed usage breakdown" },
    { "name": "Audit", "description": "Audit event logging, trail retrieval, and export" },
    { "name": "Swarm", "description": "Swarm messaging: relay, broadcast, join, leave, topology, peers" },
    { "name": "Trust", "description": "Bounded trust scoring and trust history (TCM-100-BoundedMonotonicity)" },
    { "name": "Reputation", "description": "Reputation ledger: record interactions, score queries, history" },
    { "name": "Escrow", "description": "Agent-to-agent escrow: create, release, dispute, status" },
    { "name": "SLA", "description": "SLA management: register, report violations, status checks" },
    { "name": "VeriRand", "description": "Premium verifiable random bytes and batch/stream RNG" },
    { "name": "VRF", "description": "Verifiable random function for gaming draws and verification" },
    { "name": "Drift", "description": "DriftGuard model drift detection and certification" },
    { "name": "Identity", "description": "Agent identity registration, lookup, revocation, and challenges" }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health and version",
        "description": "Returns current service status, version, build date, entropy epoch, and HELIX subsystem flags.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "version": { "type": "string", "example": "0.5.0" },
                    "build": { "type": "string", "example": "2026-04-08" },
                    "epoch": { "type": "integer", "example": 17409216 },
                    "next_epoch_in_s": { "type": "integer", "example": 45 },
                    "helix": { "$ref": "#/components/schemas/HelixStatus" }
                  }
                },
                "example": {
                  "status": "ok",
                  "version": "0.5.0",
                  "build": "2026-04-08",
                  "epoch": 17409216,
                  "next_epoch_in_s": 45,
                  "helix": {
                    "anti_hallucination": true,
                    "ecc_status": true,
                    "integrity_parity": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "OpenAPI specification",
        "description": "Returns the full OpenAPI 3.x specification for this API.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "OpenAPI specification document",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent.json": {
      "get": {
        "operationId": "getAgentCard",
        "summary": "A2A agent card",
        "description": "Returns the Google A2A protocol agent card for agent discovery and capability advertisement.",
        "tags": ["Protocol", "Free"],
        "responses": {
          "200": {
            "description": "A2A agent card",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "operationId": "getMcpManifest",
        "summary": "MCP server manifest",
        "description": "Returns the MCP server manifest for client auto-discovery.",
        "tags": ["Protocol", "Free"],
        "responses": {
          "200": {
            "description": "MCP server manifest",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/ai-plugin.json": {
      "get": {
        "operationId": "getAiPluginManifest",
        "summary": "OpenAI plugin manifest",
        "description": "Returns the OpenAI plugin manifest for ChatGPT plugin discovery.",
        "tags": ["Protocol", "Free"],
        "responses": {
          "200": {
            "description": "OpenAI plugin manifest",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/pricing.json": {
      "get": {
        "operationId": "getPricingManifest",
        "summary": "Machine-readable pricing",
        "description": "Returns machine-readable pricing for all API endpoints.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "Pricing manifest",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent-card.json": {
      "get": {
        "operationId": "getAgentCardAlt",
        "summary": "Alternative A2A agent card path",
        "description": "Alternative path for the A2A agent card, for compatibility with various A2A client implementations.",
        "tags": ["Protocol", "Free"],
        "responses": {
          "200": {
            "description": "A2A agent card",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/v1/oracle/entropy": {
      "get": {
        "operationId": "getEntropyEpoch",
        "summary": "Entropy epoch oracle",
        "description": "Returns the current entropy epoch for zero-RTT A2A handshakes. No authentication required.",
        "tags": ["Free", "Oracle"],
        "responses": {
          "200": {
            "description": "Current entropy epoch",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "epoch": { "type": "integer", "example": 17409216 },
                    "entropy": { "type": "string", "example": "a3f8c2..." },
                    "timestamp": { "type": "string", "format": "date-time", "example": "2026-04-09T12:00:00Z" },
                    "source": { "type": "string", "example": "quantum_ensemble" },
                    "verified": { "type": "boolean", "example": true }
                  }
                },
                "example": {
                  "epoch": 17409216,
                  "entropy": "a3f8c2...",
                  "timestamp": "2026-04-09T12:00:00Z",
                  "source": "quantum_ensemble",
                  "verified": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/rng/quantum": {
      "get": {
        "operationId": "getQuantumRng",
        "summary": "Quantum random number with proof",
        "description": "Returns a verifiable quantum random value with cryptographic proof. No authentication required.",
        "tags": ["Free", "Oracle"],
        "responses": {
          "200": {
            "description": "Quantum random value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "random": { "type": "string", "example": "0x7f3a8c2e9d1b4a6f..." },
                    "bits": { "type": "integer", "example": 256 },
                    "source": { "type": "string", "example": "quantum" },
                    "verified": { "type": "boolean", "example": true },
                    "epoch": { "type": "integer", "example": 17409216 }
                  }
                },
                "example": {
                  "random": "0x7f3a8c2e9d1b4a6f...",
                  "bits": 256,
                  "source": "quantum",
                  "verified": true,
                  "epoch": 17409216
                }
              }
            }
          }
        }
      }
    },
    "/v1/rng/verify": {
      "get": {
        "operationId": "verifyRng",
        "summary": "Verify current epoch random value",
        "description": "Verify that the current epoch random value is valid and has not been tampered with.",
        "tags": ["Free", "Oracle"],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "epoch": { "type": "integer" },
                    "valid": { "type": "boolean" },
                    "proof": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/rng/seeded": {
      "post": {
        "operationId": "seededRng",
        "summary": "Seeded deterministic RNG",
        "description": "Generate deterministic random values from a provided seed. Paid endpoint.",
        "tags": ["VeriRand"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["seed"],
                "properties": {
                  "seed": { "type": "string", "example": "my-deterministic-seed" },
                  "count": { "type": "integer", "example": 10 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic random values",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "values": { "type": "array", "items": { "type": "string" } },
                    "seed": { "type": "string" },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/rng/batch": {
      "post": {
        "operationId": "batchRng",
        "summary": "Batch random generation",
        "description": "Generate a batch of random values in a single request. Paid endpoint.",
        "tags": ["VeriRand"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["count"],
                "properties": {
                  "count": { "type": "integer", "example": 100 },
                  "bits": { "type": "integer", "example": 256 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch random values",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "values": { "type": "array", "items": { "type": "string" } },
                    "count": { "type": "integer" },
                    "bits": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/rng/stream": {
      "post": {
        "operationId": "streamRng",
        "summary": "Streaming random values",
        "description": "Stream random values via Server-Sent Events. Paid endpoint.",
        "tags": ["VeriRand"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "count": { "type": "integer", "example": 1000 },
                  "bits": { "type": "integer", "example": 256 },
                  "interval_ms": { "type": "integer", "example": 100 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream of random values",
            "content": {
              "text/event-stream": {
                "schema": { "type": "string", "description": "Server-Sent Events stream of random values" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/verirand/bytes": {
      "post": {
        "operationId": "verirandBytes",
        "summary": "Premium verifiable random bytes",
        "description": "Generate premium verifiable random bytes with cryptographic proof. Paid endpoint.",
        "tags": ["VeriRand"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["length"],
                "properties": {
                  "length": { "type": "integer", "example": 32, "description": "Number of bytes to generate" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verifiable random bytes with proof",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bytes": { "type": "string", "description": "Hex-encoded random bytes" },
                    "length": { "type": "integer" },
                    "proof": { "type": "string" },
                    "verified": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/register": {
      "post": {
        "operationId": "registerAgent",
        "summary": "Register an agent",
        "description": "Register an agent in the swarm topology. Compatible with the Google A2A protocol. No authentication required.",
        "tags": ["Free", "Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "capabilities"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" },
                  "capabilities": {
                    "type": "array",
                    "items": { "type": "string" },
                    "example": ["inference", "planning", "code-generation"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string", "example": "my-agent-001" },
                    "registered_at": { "type": "string", "format": "date-time", "example": "2026-04-09T14:30:00Z" },
                    "status": { "type": "string", "example": "active" },
                    "capabilities": {
                      "type": "array",
                      "items": { "type": "string" },
                      "example": ["inference", "planning"]
                    }
                  }
                },
                "example": {
                  "agent_id": "my-agent-001",
                  "registered_at": "2026-04-09T14:30:00Z",
                  "status": "active",
                  "capabilities": ["inference", "planning"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/v1/agents/topology": {
      "get": {
        "operationId": "getSwarmTopology",
        "summary": "Live swarm topology",
        "description": "Returns live swarm topology statistics for all registered agents. No authentication required.",
        "tags": ["Free", "Agents"],
        "responses": {
          "200": {
            "description": "Swarm topology",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": { "type": "integer", "example": 1247 },
                    "edges": { "type": "integer", "example": 3891 },
                    "average_degree": { "type": "number", "format": "float", "example": 3.1 },
                    "components": { "type": "integer", "example": 5 },
                    "largest_component_size": { "type": "integer", "example": 1240 }
                  }
                },
                "example": {
                  "agents": 1247,
                  "edges": 3891,
                  "average_degree": 3.1,
                  "components": 5,
                  "largest_component_size": 1240
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/status": {
      "get": {
        "operationId": "getAgentStatus",
        "summary": "Agent status lookup",
        "description": "Look up the current status of a registered agent.",
        "tags": ["Agents"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Agent status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["active", "inactive", "suspended"] },
                    "last_seen": { "type": "string", "format": "date-time" },
                    "uptime_s": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/capabilities": {
      "get": {
        "operationId": "getAgentCapabilities",
        "summary": "List agent capabilities",
        "description": "List the registered capabilities for a specific agent.",
        "tags": ["Agents"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Agent capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "capabilities": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/search": {
      "get": {
        "operationId": "searchAgents",
        "summary": "Search agents by capability",
        "description": "Search for agents that provide a specific capability.",
        "tags": ["Agents"],
        "parameters": [
          { "name": "capability", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Capability to search for" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Matching agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "agent_id": { "type": "string" },
                          "capabilities": { "type": "array", "items": { "type": "string" } },
                          "status": { "type": "string" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/health": {
      "get": {
        "operationId": "getAgentHealth",
        "summary": "Agent health check",
        "description": "Check the health status of a specific agent.",
        "tags": ["Agents"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Agent health status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "healthy": { "type": "boolean" },
                    "last_heartbeat": { "type": "string", "format": "date-time" },
                    "latency_ms": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/discover": {
      "get": {
        "operationId": "discoverAgents",
        "summary": "Discover agents (A2A compatible)",
        "description": "Discover available agents in the network. Compatible with Google A2A discovery protocol.",
        "tags": ["Free", "Agents"],
        "responses": {
          "200": {
            "description": "List of discoverable agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "agent_id": { "type": "string" },
                          "capabilities": { "type": "array", "items": { "type": "string" } },
                          "status": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/update": {
      "post": {
        "operationId": "updateAgent",
        "summary": "Update agent capabilities",
        "description": "Update the capabilities and metadata of a registered agent.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" },
                  "capabilities": { "type": "array", "items": { "type": "string" } },
                  "metadata": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "updated_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/deregister": {
      "post": {
        "operationId": "deregisterAgent",
        "summary": "Deregister an agent",
        "description": "Remove an agent from the swarm topology.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent deregistered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "deregistered_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "deregistered" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/message": {
      "post": {
        "operationId": "messageAgent",
        "summary": "Send direct message to agent",
        "description": "Send a direct message to a specific agent in the swarm.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target_agent_id", "message"],
                "properties": {
                  "target_agent_id": { "type": "string" },
                  "message": { "type": "object" },
                  "sender_agent_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message delivered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message_id": { "type": "string" },
                    "delivered": { "type": "boolean" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/negotiate": {
      "post": {
        "operationId": "negotiateAgents",
        "summary": "Negotiate terms between agents",
        "description": "Negotiate terms and conditions between two agents for a collaborative task.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["initiator_id", "responder_id", "terms"],
                "properties": {
                  "initiator_id": { "type": "string" },
                  "responder_id": { "type": "string" },
                  "terms": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Negotiation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "negotiation_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["accepted", "rejected", "pending"] },
                    "agreed_terms": { "type": "object" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/delegate": {
      "post": {
        "operationId": "delegateTask",
        "summary": "Delegate task to another agent",
        "description": "Delegate a task to another agent in the swarm network.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["from_agent_id", "to_agent_id", "task"],
                "properties": {
                  "from_agent_id": { "type": "string" },
                  "to_agent_id": { "type": "string" },
                  "task": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task delegated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "delegation_id": { "type": "string" },
                    "status": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/semantic-diff": {
      "post": {
        "operationId": "semanticDiff",
        "summary": "Semantic diff between agent outputs",
        "description": "Compute a semantic diff between two agent outputs to identify meaningful differences. Costs $0.04/call.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["output_a", "output_b"],
                "properties": {
                  "output_a": { "type": "string" },
                  "output_b": { "type": "string" },
                  "context": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Semantic diff result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "similarity_score": { "type": "number", "format": "float" },
                    "differences": { "type": "array", "items": { "type": "object" } },
                    "summary": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/contradiction": {
      "post": {
        "operationId": "detectContradiction",
        "summary": "Detect contradictions in agent outputs",
        "description": "Detect logical contradictions between agent outputs. Costs $0.02/call.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["statements"],
                "properties": {
                  "statements": {
                    "type": "array",
                    "items": { "type": "string" },
                    "example": ["The model accuracy is 95%", "The model fails 20% of the time"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contradiction detection result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contradictions_found": { "type": "boolean" },
                    "contradictions": { "type": "array", "items": { "type": "object" } },
                    "confidence": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/swarm/inbox": {
      "get": {
        "operationId": "pollSwarmInbox",
        "summary": "Poll swarm inbox",
        "description": "Poll queued messages for the registered agent. No authentication required.",
        "tags": ["Free", "Agents"],
        "responses": {
          "200": {
            "description": "Queued messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "type": "object" }
                }
              }
            }
          }
        }
      }
    },
    "/v1/swarm/relay": {
      "post": {
        "operationId": "swarmRelay",
        "summary": "Relay message through swarm",
        "description": "Relay a message through the swarm network to reach a target agent.",
        "tags": ["Swarm"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target_agent_id", "message"],
                "properties": {
                  "target_agent_id": { "type": "string" },
                  "message": { "type": "object" },
                  "ttl": { "type": "integer", "description": "Hop limit for relay" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message relayed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "relay_id": { "type": "string" },
                    "hops": { "type": "integer" },
                    "delivered": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/swarm/broadcast": {
      "post": {
        "operationId": "swarmBroadcast",
        "summary": "Broadcast to all swarm members",
        "description": "Broadcast a message to all members of the swarm group.",
        "tags": ["Swarm"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["message"],
                "properties": {
                  "message": { "type": "object" },
                  "group_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "broadcast_id": { "type": "string" },
                    "recipients": { "type": "integer" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/swarm/join": {
      "post": {
        "operationId": "swarmJoin",
        "summary": "Join swarm group",
        "description": "Join a swarm group to receive broadcasts and participate in swarm activities.",
        "tags": ["Swarm"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "group_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Joined swarm group",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "group_id": { "type": "string" },
                    "joined_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/swarm/leave": {
      "post": {
        "operationId": "swarmLeave",
        "summary": "Leave swarm group",
        "description": "Leave a swarm group.",
        "tags": ["Swarm"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "group_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Left swarm group",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "group_id": { "type": "string" },
                    "left_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/swarm/topology": {
      "get": {
        "operationId": "getSwarmScopedTopology",
        "summary": "Swarm-scoped topology",
        "description": "Returns swarm-scoped topology. Same data as /v1/agents/topology but scoped to the swarm group.",
        "tags": ["Free", "Swarm"],
        "responses": {
          "200": {
            "description": "Swarm topology",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": { "type": "integer" },
                    "edges": { "type": "integer" },
                    "average_degree": { "type": "number", "format": "float" },
                    "components": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/swarm/peers": {
      "get": {
        "operationId": "getSwarmPeers",
        "summary": "List swarm peers",
        "description": "List all peers in the swarm group.",
        "tags": ["Free", "Swarm"],
        "responses": {
          "200": {
            "description": "Swarm peers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "peers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "agent_id": { "type": "string" },
                          "status": { "type": "string" },
                          "joined_at": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/oracle/hallucination": {
      "post": {
        "operationId": "detectHallucination",
        "summary": "Hallucination oracle",
        "description": "Detect hallucinations with a certified upper bound. Returns a formally proved hallucination probability bound. Costs $0.002/call.",
        "tags": ["Oracle"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["claim"],
                "properties": {
                  "claim": { "type": "string", "example": "Water boils at 100°C at sea level" },
                  "context": { "type": "string", "example": "physics" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hallucination analysis result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "claim": { "type": "string" },
                    "context": { "type": "string" },
                    "hallucination_bound": { "type": "number", "format": "float", "example": 0.0012 },
                    "verified": { "type": "boolean", "example": true },
                    "proof_type": { "type": "string", "example": "formal" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                },
                "example": {
                  "claim": "The capital of France is Paris",
                  "context": "geography",
                  "hallucination_bound": 0.0012,
                  "verified": true,
                  "proof_type": "formal",
                  "timestamp": "2026-04-09T14:30:00Z"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/register": {
      "post": {
        "operationId": "ratchetRegisterSession",
        "summary": "RatchetGate — register session",
        "description": "Register a new RatchetGate session to mitigate session fixation attacks. Costs $0.002/call.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string", "example": "sess-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "registered_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "registered" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/advance": {
      "post": {
        "operationId": "ratchetAdvanceSession",
        "summary": "RatchetGate — advance session",
        "description": "Advance the session ratchet window to trigger re-keying. Costs $0.002/call.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string", "example": "sess-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session advanced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "advanced_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "advanced" },
                    "window": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/probe": {
      "get": {
        "operationId": "ratchetProbe",
        "summary": "RatchetGate — health probe",
        "description": "Health probe for a ratchet session. Free endpoint.",
        "tags": ["Free", "Security"],
        "responses": {
          "200": {
            "description": "Ratchet probe result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "active_sessions": { "type": "integer" },
                    "healthy": { "type": "boolean" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/ratchet/status": {
      "get": {
        "operationId": "ratchetStatus",
        "summary": "RatchetGate — session status",
        "description": "Check the status of a ratchet session. Costs $0.004/call.",
        "tags": ["Security"],
        "parameters": [
          { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Session identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Session status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["active", "expired", "revoked"] },
                    "window": { "type": "integer" },
                    "created_at": { "type": "string", "format": "date-time" },
                    "last_advanced": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/revoke": {
      "post": {
        "operationId": "ratchetRevoke",
        "summary": "RatchetGate — revoke session",
        "description": "Revoke a ratchet session, invalidating all associated keys.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "revoked_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "revoked" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/verify": {
      "post": {
        "operationId": "ratchetVerify",
        "summary": "RatchetGate — verify session integrity",
        "description": "Verify the integrity of a ratchet session, ensuring no tampering has occurred.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session integrity result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "integrity_valid": { "type": "boolean" },
                    "proof": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ratchet/list": {
      "get": {
        "operationId": "ratchetList",
        "summary": "RatchetGate — list active sessions",
        "description": "List all active ratchet sessions. Requires API key.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Active sessions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "session_id": { "type": "string" },
                          "status": { "type": "string" },
                          "created_at": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/identity/verify": {
      "post": {
        "operationId": "verifyIdentity",
        "summary": "Topological identity verification",
        "description": "Verify agent identity in untrusted networks with Sybil-resistance and a formally proved depth limit. Costs $0.020/call.",
        "tags": ["Security", "Identity"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identity verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "verified": { "type": "boolean" },
                    "sybil_resistant": { "type": "boolean" },
                    "depth_limit_proved": { "type": "boolean" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/identity/register": {
      "post": {
        "operationId": "registerIdentity",
        "summary": "Register agent identity",
        "description": "Register a new agent identity in the identity registry.",
        "tags": ["Identity"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "public_key": { "type": "string" },
                  "metadata": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identity registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "registered_at": { "type": "string", "format": "date-time" },
                    "identity_hash": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/identity/lookup": {
      "get": {
        "operationId": "lookupIdentity",
        "summary": "Lookup registered identity",
        "description": "Look up a registered identity by agent ID.",
        "tags": ["Identity"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Identity details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "public_key": { "type": "string" },
                    "registered_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/identity/revoke": {
      "post": {
        "operationId": "revokeIdentity",
        "summary": "Revoke agent identity",
        "description": "Revoke a registered agent identity.",
        "tags": ["Identity"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identity revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "revoked_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "revoked" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/identity/challenge": {
      "post": {
        "operationId": "challengeIdentity",
        "summary": "Issue identity challenge",
        "description": "Issue a cryptographic challenge to verify an agent's identity.",
        "tags": ["Identity"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Challenge issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "challenge_id": { "type": "string" },
                    "nonce": { "type": "string" },
                    "expires_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/identity/sybil-check": {
      "get": {
        "operationId": "sybilCheck",
        "summary": "Sybil-resistance check",
        "description": "Sybil-resistance check on the calling IP address. Free endpoint.",
        "tags": ["Free", "Identity"],
        "responses": {
          "200": {
            "description": "Sybil check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ip": { "type": "string" },
                    "sybil_score": { "type": "number", "format": "float" },
                    "suspicious": { "type": "boolean" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/threat/score": {
      "post": {
        "operationId": "scoreThreat",
        "summary": "Multi-vector threat score",
        "description": "Compute a multi-vector threat score (velocity, behavioral, and intent) for an agent interaction. Costs $0.003/call.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" },
                  "context": { "type": "string", "example": "multi-agent-transaction" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threat score result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "threat_score": { "type": "number", "format": "float" },
                    "velocity_score": { "type": "number", "format": "float" },
                    "behavioral_score": { "type": "number", "format": "float" },
                    "intent_score": { "type": "number", "format": "float" },
                    "verdict": { "type": "string", "enum": ["safe", "suspicious", "threat"] },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/threat/analyze": {
      "post": {
        "operationId": "analyzeThreat",
        "summary": "Deep threat analysis",
        "description": "Perform deep threat analysis on an agent or interaction pattern.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "interaction_log": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threat analysis result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "risk_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                    "findings": { "type": "array", "items": { "type": "object" } },
                    "recommendations": { "type": "array", "items": { "type": "string" } },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/threat/report": {
      "post": {
        "operationId": "reportThreat",
        "summary": "Report a threat incident",
        "description": "Report a threat incident involving a specific agent.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "description"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "description": { "type": "string" },
                  "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                  "evidence": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Threat reported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report_id": { "type": "string" },
                    "status": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/threat/block": {
      "post": {
        "operationId": "blockThreat",
        "summary": "Block a threatening agent",
        "description": "Block a threatening agent from further interactions.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "reason": { "type": "string" },
                  "duration_s": { "type": "integer", "description": "Block duration in seconds, 0 for permanent" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent blocked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "blocked_at": { "type": "string", "format": "date-time" },
                    "expires_at": { "type": "string", "format": "date-time" },
                    "status": { "type": "string", "example": "blocked" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/threat/history": {
      "get": {
        "operationId": "getThreatHistory",
        "summary": "Threat history for an agent",
        "description": "Retrieve the threat history for a specific agent.",
        "tags": ["Security"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Threat history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "event_type": { "type": "string" },
                          "severity": { "type": "string" },
                          "timestamp": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/trust/decay": {
      "get": {
        "operationId": "getTrustDecay",
        "summary": "Current trust ceiling value",
        "description": "Returns the current trust ceiling value, reflecting the bounded monotonicity decay. Free endpoint.",
        "tags": ["Free", "Trust"],
        "responses": {
          "200": {
            "description": "Trust decay value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ceiling": { "type": "number", "format": "float" },
                    "decay_rate": { "type": "number", "format": "float" },
                    "epoch": { "type": "integer" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/trust/score": {
      "post": {
        "operationId": "getTrustScore",
        "summary": "Bounded trust score",
        "description": "Compute a bounded trust score for on-chain governance (TCM-100-BoundedMonotonicity). Costs $0.04/call.",
        "tags": ["Trust"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trust score",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "trust_score": { "type": "number", "format": "float" },
                    "bounded": { "type": "boolean" },
                    "ceiling": { "type": "number", "format": "float" },
                    "proof": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/trust/history": {
      "get": {
        "operationId": "getTrustHistory",
        "summary": "Trust score history",
        "description": "Retrieve trust score history for an agent. Costs $0.04/query.",
        "tags": ["Trust"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Trust score history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "trust_score": { "type": "number", "format": "float" },
                          "timestamp": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/check": {
      "post": {
        "operationId": "checkCompliance",
        "summary": "GDPR/CCPA compliance gate",
        "description": "Verify regulatory compliance for a data operation with formal proof. Supports GDPR and CCPA jurisdictions. Costs $0.005/call.",
        "tags": ["Security", "Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data_type", "jurisdiction", "operation"],
                "properties": {
                  "data_type": { "type": "string", "example": "user_pii" },
                  "jurisdiction": { "type": "string", "example": "EU" },
                  "operation": { "type": "string", "example": "store" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compliance check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data_type": { "type": "string" },
                    "jurisdiction": { "type": "string" },
                    "operation": { "type": "string" },
                    "compliant": { "type": "boolean" },
                    "proof_type": { "type": "string", "example": "formal" },
                    "regulations": {
                      "type": "array",
                      "items": { "type": "string" },
                      "example": ["GDPR", "CCPA"]
                    },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/eu-ai-act": {
      "post": {
        "operationId": "euAiActCertificate",
        "summary": "EU AI Act compliance certificate",
        "description": "Generate an EU AI Act compliance certificate for an AI system. Costs $0.04/check.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["system_id", "risk_category", "intended_purpose"],
                "properties": {
                  "system_id": { "type": "string" },
                  "risk_category": { "type": "string", "enum": ["minimal", "limited", "high", "unacceptable"] },
                  "intended_purpose": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "EU AI Act certificate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "certificate_id": { "type": "string" },
                    "system_id": { "type": "string" },
                    "compliant": { "type": "boolean" },
                    "risk_category": { "type": "string" },
                    "requirements": { "type": "array", "items": { "type": "object" } },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/fairness": {
      "post": {
        "operationId": "fairnessProof",
        "summary": "Fairness proof (FNS-100-FairnessBound)",
        "description": "Generate a fairness proof certificate for a model. Costs $0.04/check.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id", "dataset_id", "protected_attrs", "metric"],
                "properties": {
                  "model_id": { "type": "string" },
                  "dataset_id": { "type": "string" },
                  "protected_attrs": { "type": "array", "items": { "type": "string" } },
                  "metric": { "type": "string", "example": "demographic_parity" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fairness proof certificate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "certificate_id": { "type": "string" },
                    "model_id": { "type": "string" },
                    "fair": { "type": "boolean" },
                    "metric_value": { "type": "number", "format": "float" },
                    "bound": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/explain": {
      "post": {
        "operationId": "explainabilityCertificate",
        "summary": "Explainability certificate (XPL-100-ExplainBound)",
        "description": "Generate an explainability certificate for a model decision. Costs $0.04/call.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id", "decision_id", "subject_context"],
                "properties": {
                  "model_id": { "type": "string" },
                  "decision_id": { "type": "string" },
                  "subject_context": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Explainability certificate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "certificate_id": { "type": "string" },
                    "explanation": { "type": "string" },
                    "features": { "type": "array", "items": { "type": "object" } },
                    "explainability_score": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/lineage": {
      "post": {
        "operationId": "dataLineage",
        "summary": "Data lineage (LIN-100-ChainIntegrity)",
        "description": "Verify data lineage chain integrity. Costs $0.04/call.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id", "dataset_stages"],
                "properties": {
                  "model_id": { "type": "string" },
                  "dataset_stages": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Data lineage verification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model_id": { "type": "string" },
                    "chain_valid": { "type": "boolean" },
                    "stages_verified": { "type": "integer" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/oversight": {
      "post": {
        "operationId": "logOversight",
        "summary": "Log oversight event",
        "description": "Log a human oversight event for an AI system. Costs $0.02/event.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["system_id", "reviewer_id", "decision", "notes"],
                "properties": {
                  "system_id": { "type": "string" },
                  "reviewer_id": { "type": "string" },
                  "decision": { "type": "string" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Oversight event logged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "event_id": { "type": "string" },
                    "system_id": { "type": "string" },
                    "logged_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/oversight/history": {
      "get": {
        "operationId": "getOversightHistory",
        "summary": "Oversight history",
        "description": "Retrieve oversight event history for a system. Costs $0.02/query.",
        "tags": ["Compliance"],
        "parameters": [
          { "name": "system_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "System identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Oversight history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "system_id": { "type": "string" },
                    "events": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/incident": {
      "post": {
        "operationId": "reportIncident",
        "summary": "Report compliance incident",
        "description": "Report an AI system compliance incident. Costs $0.02/report.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["system_id", "severity", "description", "affected_users"],
                "properties": {
                  "system_id": { "type": "string" },
                  "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                  "description": { "type": "string" },
                  "affected_users": { "type": "integer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Incident reported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "incident_id": { "type": "string" },
                    "system_id": { "type": "string" },
                    "status": { "type": "string" },
                    "reported_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/incidents": {
      "get": {
        "operationId": "getIncidents",
        "summary": "Incident registry",
        "description": "Retrieve the incident registry for a system. Costs $0.02/query.",
        "tags": ["Compliance"],
        "parameters": [
          { "name": "system_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "System identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Incident registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "system_id": { "type": "string" },
                    "incidents": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/compliance/transparency": {
      "post": {
        "operationId": "transparencyReport",
        "summary": "Transparency report",
        "description": "Generate a transparency report for an AI system. Costs $0.08/report.",
        "tags": ["Compliance"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["system_id", "period", "include"],
                "properties": {
                  "system_id": { "type": "string" },
                  "period": { "type": "string", "example": "2026-Q1" },
                  "include": { "type": "array", "items": { "type": "string" }, "example": ["incidents", "oversight", "fairness"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transparency report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report_id": { "type": "string" },
                    "system_id": { "type": "string" },
                    "period": { "type": "string" },
                    "sections": { "type": "object" },
                    "generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/drift/check": {
      "post": {
        "operationId": "driftCheck",
        "summary": "DriftGuard check (DRG-100-DriftBound)",
        "description": "Check for model drift between reference and current windows. Costs $0.01/check.",
        "tags": ["Drift"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id", "reference_window", "current_window"],
                "properties": {
                  "model_id": { "type": "string" },
                  "reference_window": { "type": "object" },
                  "current_window": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Drift check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model_id": { "type": "string" },
                    "drift_detected": { "type": "boolean" },
                    "drift_score": { "type": "number", "format": "float" },
                    "bound": { "type": "number", "format": "float" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/drift/certificate": {
      "get": {
        "operationId": "getDriftCertificate",
        "summary": "Drift certificate",
        "description": "Retrieve a drift certificate by ID. Costs $0.01/cert.",
        "tags": ["Drift"],
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Drift certificate ID" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Drift certificate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "certificate_id": { "type": "string" },
                    "model_id": { "type": "string" },
                    "drift_score": { "type": "number", "format": "float" },
                    "issued_at": { "type": "string", "format": "date-time" },
                    "valid_until": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/inference": {
      "post": {
        "operationId": "chatInference",
        "summary": "Chat inference with hallucination guard",
        "description": "LLM chat completion with built-in hallucination guard and safety guarantees. Costs $0.015/call.",
        "tags": ["Inference"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/ChatMessage" },
                    "example": [{ "role": "user", "content": "What is formal verification?" }]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": { "type": "string" },
                    "hallucination_bound": { "type": "number", "format": "float" },
                    "verified": { "type": "boolean" },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": { "type": "integer" },
                        "completion_tokens": { "type": "integer" },
                        "total_tokens": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/inference/stream": {
      "post": {
        "operationId": "streamInference",
        "summary": "Streaming inference with chain-of-thought",
        "description": "Streaming LLM inference via Server-Sent Events (SSE) with reasoning trace. Costs $0.025/call.",
        "tags": ["Inference"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["messages"],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/ChatMessage" },
                    "example": [{ "role": "user", "content": "Explain formal verification step by step." }]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream of completion chunks and chain-of-thought",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream. Each event is a JSON object with a 'type' field ('thinking', 'content', or 'done')."
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/inference/embeddings": {
      "post": {
        "operationId": "inferenceEmbeddings",
        "summary": "Generate embeddings",
        "description": "Generate text embeddings using the inference engine. Costs $0.01/call.",
        "tags": ["Inference"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input"],
                "properties": {
                  "input": { "type": "string" },
                  "model": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embeddings result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "embedding": { "type": "array", "items": { "type": "number" } },
                    "dimensions": { "type": "integer" },
                    "model": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/inference/classify": {
      "post": {
        "operationId": "inferenceClassify",
        "summary": "Text classification via inference",
        "description": "Classify text using the inference engine. Costs $0.01/call.",
        "tags": ["Inference"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "labels": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Classification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "label": { "type": "string" },
                    "confidence": { "type": "number", "format": "float" },
                    "scores": { "type": "object" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/inference/models": {
      "get": {
        "operationId": "listInferenceModels",
        "summary": "List available inference models",
        "description": "List all available inference models. Free endpoint.",
        "tags": ["Free", "Inference"],
        "responses": {
          "200": {
            "description": "Available models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "type": { "type": "string" },
                          "context_length": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/compress": {
      "post": {
        "operationId": "compressData",
        "summary": "HELIX tensor compression",
        "description": "Compress data using HELIX tensor compression. Free tier and paid pro tier available.",
        "tags": ["Free", "Inference"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["data"],
                "properties": {
                  "data": { "type": "string", "description": "Data to compress" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compressed output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "compressed": { "type": "string" },
                    "original_size": { "type": "integer" },
                    "compressed_size": { "type": "integer" },
                    "ratio": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/v1/agents/plan": {
      "post": {
        "operationId": "planAgentGoal",
        "summary": "Autonomous agent goal planning",
        "description": "Decompose a goal into an action plan for autonomous agent execution. Costs $0.015/call.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["goal"],
                "properties": {
                  "goal": { "type": "string", "example": "Deploy a web service with zero downtime" },
                  "constraints": {
                    "type": "object",
                    "description": "Optional constraints for the plan (e.g., time limits, resource caps)",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Goal decomposition and action plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "goal": { "type": "string" },
                    "steps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "step": { "type": "integer" },
                          "action": { "type": "string" },
                          "description": { "type": "string" }
                        }
                      }
                    },
                    "estimated_complexity": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/intent-classify": {
      "post": {
        "operationId": "classifyAgentIntent",
        "summary": "Agent intent classification",
        "description": "Classify agent intent from natural language text. Returns the top-3 intent classifications. Costs $0.005/call.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string", "example": "I need to fetch user data and store it in the database" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Top-3 intent classifications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "text": { "type": "string" },
                    "intents": {
                      "type": "array",
                      "maxItems": 3,
                      "items": {
                        "type": "object",
                        "properties": {
                          "intent": { "type": "string" },
                          "confidence": { "type": "number", "format": "float" }
                        }
                      }
                    },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/agents/reputation": {
      "post": {
        "operationId": "getAgentReputation",
        "summary": "Agent reputation and trust score",
        "description": "Get the A2A trust score and compliance status for an agent. Costs $0.010/call.",
        "tags": ["Agents"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string", "example": "my-agent-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent reputation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "trust_score": { "type": "number", "format": "float" },
                    "compliance_status": { "type": "string", "enum": ["compliant", "non_compliant", "unknown"] },
                    "interactions": { "type": "integer" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/summarize": {
      "post": {
        "operationId": "summarizeText",
        "summary": "Text summarization",
        "description": "Generate an extractive summary of the provided text. Costs $0.010/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": {
                    "type": "string",
                    "example": "Formal verification is the act of proving or disproving the correctness of intended algorithms underlying a system with respect to a certain formal specification or property, using formal methods of mathematics."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extractive summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": { "type": "string" },
                    "original_length": { "type": "integer" },
                    "summary_length": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/sentiment": {
      "post": {
        "operationId": "analyzeSentiment",
        "summary": "Sentiment analysis",
        "description": "Classify the sentiment of the provided text. Costs $0.005/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string", "example": "This API is incredibly reliable and easy to use." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sentiment classification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
                    "confidence": { "type": "number", "format": "float" },
                    "scores": {
                      "type": "object",
                      "properties": {
                        "positive": { "type": "number", "format": "float" },
                        "negative": { "type": "number", "format": "float" },
                        "neutral": { "type": "number", "format": "float" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/ner": {
      "post": {
        "operationId": "textNer",
        "summary": "Named entity recognition",
        "description": "Extract named entities from text. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Named entities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "text": { "type": "string" },
                          "label": { "type": "string" },
                          "start": { "type": "integer" },
                          "end": { "type": "integer" },
                          "confidence": { "type": "number", "format": "float" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/translate": {
      "post": {
        "operationId": "textTranslate",
        "summary": "Text translation",
        "description": "Translate text to a target language. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text", "target_language"],
                "properties": {
                  "text": { "type": "string" },
                  "target_language": { "type": "string", "example": "es" },
                  "source_language": { "type": "string", "example": "en" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Translation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "translated_text": { "type": "string" },
                    "source_language": { "type": "string" },
                    "target_language": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/classify": {
      "post": {
        "operationId": "textClassify",
        "summary": "Text classification",
        "description": "Classify text into predefined or custom categories. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "labels": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Classification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "label": { "type": "string" },
                    "confidence": { "type": "number", "format": "float" },
                    "scores": { "type": "object" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/embed": {
      "post": {
        "operationId": "textEmbed",
        "summary": "Text embeddings",
        "description": "Generate text embeddings for semantic similarity and search. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "embedding": { "type": "array", "items": { "type": "number" } },
                    "dimensions": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/keywords": {
      "post": {
        "operationId": "textKeywords",
        "summary": "Keyword extraction",
        "description": "Extract keywords and key phrases from text. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "max_keywords": { "type": "integer", "example": 10 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keywords",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keywords": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "keyword": { "type": "string" },
                          "score": { "type": "number", "format": "float" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/similarity": {
      "post": {
        "operationId": "textSimilarity",
        "summary": "Text similarity scoring",
        "description": "Compute semantic similarity between two texts. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text_a", "text_b"],
                "properties": {
                  "text_a": { "type": "string" },
                  "text_b": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Similarity result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "similarity": { "type": "number", "format": "float" },
                    "method": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/rewrite": {
      "post": {
        "operationId": "textRewrite",
        "summary": "Text rewriting",
        "description": "Rewrite text in a different style or tone. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "style": { "type": "string", "example": "formal" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rewritten text",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rewritten_text": { "type": "string" },
                    "style": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/extract": {
      "post": {
        "operationId": "textExtract",
        "summary": "Structured data extraction",
        "description": "Extract structured data from unstructured text. Costs $0.02/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "schema": { "type": "object", "description": "Expected output schema" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted structured data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "extracted": { "type": "object" },
                    "confidence": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/detect-language": {
      "post": {
        "operationId": "textDetectLanguage",
        "summary": "Language detection",
        "description": "Detect the language of the provided text. Costs $0.01/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Language detection result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "language": { "type": "string", "example": "en" },
                    "confidence": { "type": "number", "format": "float" },
                    "alternatives": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/text/tokenize": {
      "post": {
        "operationId": "textTokenize",
        "summary": "Tokenization",
        "description": "Tokenize text into tokens. Costs $0.01/call.",
        "tags": ["Text"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokenization result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokens": { "type": "array", "items": { "type": "string" } },
                    "token_count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/metrics": {
      "get": {
        "operationId": "getMetrics",
        "summary": "Platform metrics",
        "description": "Returns platform metrics: endpoint count, pricing tiers, uptime. Free endpoint.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "Platform metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint_count": { "type": "integer" },
                    "uptime_percent": { "type": "number", "format": "float" },
                    "total_requests_24h": { "type": "integer" },
                    "active_agents": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/embed": {
      "get": {
        "operationId": "getHelixManifest",
        "summary": "HELIX compression service manifest",
        "description": "Returns the HELIX compression service manifest. Free endpoint.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "HELIX manifest",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/v1/bitnet/models": {
      "get": {
        "operationId": "getBitnetModels",
        "summary": "BitNet/HELIX model catalog",
        "description": "Returns a catalog of BitNet/HELIX compressed model downloads. Free endpoint.",
        "tags": ["Free"],
        "responses": {
          "200": {
            "description": "Model catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "size_mb": { "type": "integer" },
                          "compression": { "type": "string" },
                          "download_url": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/stripe/session": {
      "post": {
        "operationId": "createStripeSession",
        "summary": "Create Stripe Checkout session",
        "description": "Create a Stripe Checkout session for purchasing credit or prompt packs. No authentication required.",
        "tags": ["Payments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["price_id"],
                "properties": {
                  "price_id": { "type": "string", "description": "Stripe price ID" },
                  "success_url": { "type": "string" },
                  "cancel_url": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe Checkout session",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "url": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/v1/payments/stripe/prices": {
      "get": {
        "operationId": "getStripePrices",
        "summary": "List active Stripe prices",
        "description": "List all active Stripe prices for credit and prompt packs. No authentication required.",
        "tags": ["Payments"],
        "responses": {
          "200": {
            "description": "Active Stripe prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "amount": { "type": "integer" },
                          "currency": { "type": "string" },
                          "credits": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/pay/verify": {
      "post": {
        "operationId": "verifyPayment",
        "summary": "Verify payment and retrieve API key",
        "description": "Verify a completed payment and retrieve the associated API key. No authentication required.",
        "tags": ["Payments"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string", "description": "Stripe Checkout session ID" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment verified, API key returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": { "type": "boolean" },
                    "api_key": { "type": "string" },
                    "credits": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/v1/forge/leaderboard": {
      "get": {
        "operationId": "getForgeLeaderboard",
        "summary": "Model leaderboard",
        "description": "Browse the model leaderboard. Free endpoint.",
        "tags": ["Free", "Forge"],
        "responses": {
          "200": {
            "description": "Model leaderboard",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model_id": { "type": "string" },
                          "name": { "type": "string" },
                          "score": { "type": "number", "format": "float" },
                          "rank": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/forge/quarantine": {
      "get": {
        "operationId": "getForgeQuarantine",
        "summary": "Quarantined models",
        "description": "View quarantined models that failed verification. Free endpoint.",
        "tags": ["Free", "Forge"],
        "responses": {
          "200": {
            "description": "Quarantined models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "model_id": { "type": "string" },
                          "reason": { "type": "string" },
                          "quarantined_at": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/forge/verify": {
      "post": {
        "operationId": "verifyForgeModel",
        "summary": "Verify a model submission",
        "description": "Verify a model submission for the Forge marketplace. Requires API key.",
        "tags": ["Forge"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id"],
                "properties": {
                  "model_id": { "type": "string" },
                  "verification_type": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model_id": { "type": "string" },
                    "verified": { "type": "boolean" },
                    "issues": { "type": "array", "items": { "type": "string" } },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/forge/delta/submit": {
      "post": {
        "operationId": "submitForgeDelta",
        "summary": "Submit a model delta",
        "description": "Submit a model delta (incremental update) to the Forge marketplace. Requires API key.",
        "tags": ["Forge"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model_id", "delta"],
                "properties": {
                  "model_id": { "type": "string" },
                  "delta": { "type": "object" },
                  "description": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delta submitted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "delta_id": { "type": "string" },
                    "model_id": { "type": "string" },
                    "status": { "type": "string" },
                    "submitted_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/forge/badge/{model}": {
      "get": {
        "operationId": "getForgeBadge",
        "summary": "Model quality badge",
        "description": "Get a quality badge for a model. Free endpoint.",
        "tags": ["Free", "Forge"],
        "parameters": [
          { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Model identifier" }
        ],
        "responses": {
          "200": {
            "description": "Model badge",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "model_id": { "type": "string" },
                    "badge": { "type": "string", "enum": ["gold", "silver", "bronze", "none"] },
                    "score": { "type": "number", "format": "float" },
                    "verified": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/defi/optimize": {
      "post": {
        "operationId": "defiOptimize",
        "summary": "LP parameter optimization (DFP-100-OptimalTick)",
        "description": "Optimize liquidity provider parameters for DeFi positions. Fee: $0.08 + 0.2% of position size.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["protocol", "position", "risk_tolerance"],
                "properties": {
                  "protocol": { "type": "string", "example": "uniswap_v3" },
                  "position": {
                    "type": "object",
                    "properties": {
                      "token_a": { "type": "string", "example": "ETH" },
                      "token_b": { "type": "string", "example": "USDC" },
                      "amount_usd": { "type": "number", "example": 10000 }
                    }
                  },
                  "risk_tolerance": { "type": "number", "format": "float", "example": 0.5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Optimization result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "optimal_tick_lower": { "type": "integer" },
                    "optimal_tick_upper": { "type": "integer" },
                    "expected_apr": { "type": "number", "format": "float" },
                    "impermanent_loss_bound": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/risk-score": {
      "post": {
        "operationId": "defiRiskScore",
        "summary": "DeFi risk scoring (DFI-101-RiskScoreBound)",
        "description": "Compute a risk score for a DeFi position. Costs $0.08/call.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["protocol", "position", "market_conditions"],
                "properties": {
                  "protocol": { "type": "string" },
                  "position": { "type": "object" },
                  "market_conditions": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Risk score result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "risk_score": { "type": "number", "format": "float" },
                    "risk_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                    "factors": { "type": "array", "items": { "type": "object" } },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/oracle-verify": {
      "post": {
        "operationId": "defiOracleVerify",
        "summary": "Oracle guard (OGD-100-ManipulationBound)",
        "description": "Verify oracle integrity and detect price manipulation. Fee: $0.04 + 0.1% of tvl_at_risk.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["oracle_address", "price_feed", "reference_price", "asset", "tvl_at_risk"],
                "properties": {
                  "oracle_address": { "type": "string" },
                  "price_feed": { "type": "string" },
                  "reference_price": { "type": "number" },
                  "asset": { "type": "string" },
                  "tvl_at_risk": { "type": "number" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Oracle verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "oracle_valid": { "type": "boolean" },
                    "deviation": { "type": "number", "format": "float" },
                    "manipulation_bound": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/liquidation-check": {
      "post": {
        "operationId": "defiLiquidationCheck",
        "summary": "Liquid Shield (LQS-100-LiquidationBound)",
        "description": "Check liquidation risk for a DeFi position. Fee: $0.04 + 1% of net equity.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["position_id", "collateral_value", "debt_value", "collateral_factor"],
                "properties": {
                  "position_id": { "type": "string" },
                  "collateral_value": { "type": "number" },
                  "debt_value": { "type": "number" },
                  "collateral_factor": { "type": "number", "format": "float" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Liquidation check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "at_risk": { "type": "boolean" },
                    "health_factor": { "type": "number", "format": "float" },
                    "liquidation_price": { "type": "number" },
                    "margin_of_safety": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/bridge-verify": {
      "post": {
        "operationId": "defiBridgeVerify",
        "summary": "Bridge Proof (BRP-100-BridgeIntegrity)",
        "description": "Verify cross-chain bridge transaction integrity. Costs $0.08/verification.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["bridge_id", "source_chain", "dest_chain", "amount", "token"],
                "properties": {
                  "bridge_id": { "type": "string" },
                  "source_chain": { "type": "string" },
                  "dest_chain": { "type": "string" },
                  "amount": { "type": "number" },
                  "token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bridge verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bridge_valid": { "type": "boolean" },
                    "source_confirmed": { "type": "boolean" },
                    "dest_confirmed": { "type": "boolean" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/contract-audit": {
      "post": {
        "operationId": "defiContractAudit",
        "summary": "Contract Verify (CVR-100-AuditBound)",
        "description": "Automated smart contract security audit. Costs $0.15/audit.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["contract_id", "contract_type"],
                "properties": {
                  "contract_id": { "type": "string" },
                  "contract_type": { "type": "string", "example": "erc20" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contract_id": { "type": "string" },
                    "audit_passed": { "type": "boolean" },
                    "vulnerabilities": { "type": "array", "items": { "type": "object" } },
                    "risk_score": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/defi/yield-optimize": {
      "post": {
        "operationId": "defiYieldOptimize",
        "summary": "Yield Oracle (YLD-100-YieldConvergence)",
        "description": "Optimize yield strategy across DeFi protocols. Fee: $0.04 + 2% of alpha.",
        "tags": ["DeFi"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["principal_usd", "risk_tolerance"],
                "properties": {
                  "principal_usd": { "type": "number", "example": 10000 },
                  "risk_tolerance": { "type": "number", "format": "float", "example": 0.5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Yield optimization result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "strategy": { "type": "object" },
                    "expected_apr": { "type": "number", "format": "float" },
                    "risk_adjusted_return": { "type": "number", "format": "float" },
                    "proof": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/vrf/draw": {
      "post": {
        "operationId": "vrfDraw",
        "summary": "VRF Gaming draw (VRF-100)",
        "description": "Verifiable random function draw for gaming applications. Fee: $0.01 + 0.5% of pot_value_usd.",
        "tags": ["VRF"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["game_id", "round", "range_max", "pot_value_usd"],
                "properties": {
                  "game_id": { "type": "string" },
                  "round": { "type": "integer" },
                  "range_max": { "type": "integer" },
                  "pot_value_usd": { "type": "number" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "VRF draw result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draw_id": { "type": "string" },
                    "value": { "type": "integer" },
                    "proof": { "type": "string" },
                    "verified": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/vrf/verify-draw": {
      "post": {
        "operationId": "vrfVerifyDraw",
        "summary": "VRF Verify draw (VRF-101)",
        "description": "Verify a previous VRF draw. Included with draw fee.",
        "tags": ["VRF"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["draw_id", "expected_value"],
                "properties": {
                  "draw_id": { "type": "string" },
                  "expected_value": { "type": "integer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "VRF verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draw_id": { "type": "string" },
                    "valid": { "type": "boolean" },
                    "expected_value": { "type": "integer" },
                    "actual_value": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/sla/register": {
      "post": {
        "operationId": "registerSla",
        "summary": "Register an SLA",
        "description": "Register a service level agreement between agents. Costs $0.08/call.",
        "tags": ["SLA"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["provider_id", "consumer_id", "terms"],
                "properties": {
                  "provider_id": { "type": "string" },
                  "consumer_id": { "type": "string" },
                  "terms": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SLA registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sla_id": { "type": "string" },
                    "status": { "type": "string" },
                    "registered_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/sla/report": {
      "post": {
        "operationId": "reportSlaViolation",
        "summary": "Report SLA violation",
        "description": "Report an SLA violation. Costs $0.02/call.",
        "tags": ["SLA"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["sla_id", "violation_type"],
                "properties": {
                  "sla_id": { "type": "string" },
                  "violation_type": { "type": "string" },
                  "description": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Violation reported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report_id": { "type": "string" },
                    "sla_id": { "type": "string" },
                    "status": { "type": "string" },
                    "reported_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/sla/status": {
      "get": {
        "operationId": "getSlaStatus",
        "summary": "SLA status check",
        "description": "Check the status of an SLA. Costs $0.008/call.",
        "tags": ["SLA"],
        "parameters": [
          { "name": "sla_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "SLA identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "SLA status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sla_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["active", "violated", "expired"] },
                    "violations": { "type": "integer" },
                    "uptime_percent": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/escrow/create": {
      "post": {
        "operationId": "createEscrow",
        "summary": "Create agent-to-agent escrow",
        "description": "Create an escrow between two agents. Costs $0.04/call.",
        "tags": ["Escrow"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["payer_id", "payee_id", "amount", "currency"],
                "properties": {
                  "payer_id": { "type": "string" },
                  "payee_id": { "type": "string" },
                  "amount": { "type": "number" },
                  "currency": { "type": "string" },
                  "conditions": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Escrow created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "escrow_id": { "type": "string" },
                    "status": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/escrow/release": {
      "post": {
        "operationId": "releaseEscrow",
        "summary": "Release escrowed funds",
        "description": "Release escrowed funds to the payee. Costs $0.02/call.",
        "tags": ["Escrow"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["escrow_id"],
                "properties": {
                  "escrow_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Escrow released",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "escrow_id": { "type": "string" },
                    "status": { "type": "string", "example": "released" },
                    "released_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/escrow/dispute": {
      "post": {
        "operationId": "disputeEscrow",
        "summary": "Open escrow dispute",
        "description": "Open a dispute on an escrow. Costs $0.06/call.",
        "tags": ["Escrow"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["escrow_id", "reason"],
                "properties": {
                  "escrow_id": { "type": "string" },
                  "reason": { "type": "string" },
                  "evidence": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dispute opened",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dispute_id": { "type": "string" },
                    "escrow_id": { "type": "string" },
                    "status": { "type": "string", "example": "open" },
                    "opened_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/escrow/status": {
      "get": {
        "operationId": "getEscrowStatus",
        "summary": "Escrow status",
        "description": "Check the status of an escrow. Costs $0.008/call.",
        "tags": ["Escrow"],
        "parameters": [
          { "name": "escrow_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Escrow identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Escrow status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "escrow_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["pending", "released", "disputed", "refunded"] },
                    "amount": { "type": "number" },
                    "currency": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/reputation/record": {
      "post": {
        "operationId": "recordReputation",
        "summary": "Record agent interaction",
        "description": "Record an agent interaction in the reputation ledger. Costs $0.02/call.",
        "tags": ["Reputation"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "interaction_type", "outcome"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "interaction_type": { "type": "string" },
                  "outcome": { "type": "string", "enum": ["positive", "negative", "neutral"] },
                  "counterparty_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Interaction recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "record_id": { "type": "string" },
                    "agent_id": { "type": "string" },
                    "recorded_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/reputation/score": {
      "get": {
        "operationId": "getReputationScore",
        "summary": "Get reputation score",
        "description": "Get the reputation score for an agent. Costs $0.008/call.",
        "tags": ["Reputation"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Reputation score",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "score": { "type": "number", "format": "float" },
                    "total_interactions": { "type": "integer" },
                    "positive_ratio": { "type": "number", "format": "float" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/reputation/history": {
      "get": {
        "operationId": "getReputationHistory",
        "summary": "Reputation history",
        "description": "Get the reputation history for an agent.",
        "tags": ["Reputation"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Reputation history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "interaction_type": { "type": "string" },
                          "outcome": { "type": "string" },
                          "timestamp": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/shield/session": {
      "post": {
        "operationId": "shieldSession",
        "summary": "Initialize Shield session",
        "description": "Initialize an AAAA Shield session for post-quantum secure communication.",
        "tags": ["Shield"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "algorithm": { "type": "string", "example": "kyber-1024" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shield session initialized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "public_key": { "type": "string" },
                    "algorithm": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/shield/post-quantum": {
      "post": {
        "operationId": "shieldPostQuantum",
        "summary": "Post-quantum key exchange",
        "description": "Perform a post-quantum key exchange using Kyber or similar lattice-based algorithms.",
        "tags": ["Shield"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id", "public_key"],
                "properties": {
                  "session_id": { "type": "string" },
                  "public_key": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key exchange result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "shared_secret_hash": { "type": "string" },
                    "algorithm": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/shield/verify": {
      "post": {
        "operationId": "shieldVerify",
        "summary": "Verify Shield session",
        "description": "Verify the integrity of an AAAA Shield session.",
        "tags": ["Shield"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shield verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "valid": { "type": "boolean" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/shield/rotate": {
      "post": {
        "operationId": "shieldRotate",
        "summary": "Rotate Shield keys",
        "description": "Rotate the cryptographic keys for an AAAA Shield session.",
        "tags": ["Shield"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keys rotated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "new_public_key": { "type": "string" },
                    "rotated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/shield/status": {
      "get": {
        "operationId": "getShieldStatus",
        "summary": "Shield status",
        "description": "Get the status of an AAAA Shield session.",
        "tags": ["Shield"],
        "parameters": [
          { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Shield session ID" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Shield status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["active", "expired", "revoked"] },
                    "algorithm": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" },
                    "last_rotated": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/delegation/validate": {
      "post": {
        "operationId": "validateDelegation",
        "summary": "Validate UCAN delegation chain",
        "description": "Validate a UCAN delegation chain for correctness and authorization.",
        "tags": ["Delegation"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string", "description": "UCAN token to validate" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delegation validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": { "type": "boolean" },
                    "chain_depth": { "type": "integer" },
                    "issuer": { "type": "string" },
                    "audience": { "type": "string" },
                    "capabilities": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/delegation/chain": {
      "get": {
        "operationId": "getDelegationChain",
        "summary": "Get delegation chain",
        "description": "Get the full delegation chain for an agent.",
        "tags": ["Delegation"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Delegation chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "chain": { "type": "array", "items": { "type": "object" } },
                    "depth": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/delegation/revoke": {
      "post": {
        "operationId": "revokeDelegation",
        "summary": "Revoke delegation",
        "description": "Revoke a delegation, invalidating the entire sub-chain.",
        "tags": ["Delegation"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delegation revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": { "type": "boolean" },
                    "revoked_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/delegation/list": {
      "get": {
        "operationId": "listDelegations",
        "summary": "List delegations",
        "description": "List all delegations for an agent.",
        "tags": ["Delegation"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Delegations list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "delegations": { "type": "array", "items": { "type": "object" } },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/delegation/depth": {
      "get": {
        "operationId": "getDelegationDepth",
        "summary": "Get delegation depth",
        "description": "Get the delegation depth for an agent.",
        "tags": ["Delegation"],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Agent identifier" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Delegation depth",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string" },
                    "depth": { "type": "integer" },
                    "max_allowed": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ucan/create": {
      "post": {
        "operationId": "createUcan",
        "summary": "Create UCAN token",
        "description": "Create a new UCAN token with specified capabilities.",
        "tags": ["UCAN"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["issuer", "audience", "capabilities"],
                "properties": {
                  "issuer": { "type": "string" },
                  "audience": { "type": "string" },
                  "capabilities": { "type": "array", "items": { "type": "object" } },
                  "expiration": { "type": "integer", "description": "Unix timestamp" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "UCAN token created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": { "type": "string" },
                    "issuer": { "type": "string" },
                    "audience": { "type": "string" },
                    "expires_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ucan/verify": {
      "post": {
        "operationId": "verifyUcan",
        "summary": "Verify UCAN token",
        "description": "Verify a UCAN token and its delegation chain.",
        "tags": ["UCAN"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "UCAN verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": { "type": "boolean" },
                    "issuer": { "type": "string" },
                    "audience": { "type": "string" },
                    "capabilities": { "type": "array", "items": { "type": "object" } },
                    "expired": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ucan/revoke": {
      "post": {
        "operationId": "revokeUcan",
        "summary": "Revoke UCAN token",
        "description": "Revoke a UCAN token.",
        "tags": ["UCAN"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "UCAN revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revoked": { "type": "boolean" },
                    "revoked_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/ucan/delegate": {
      "post": {
        "operationId": "delegateUcan",
        "summary": "Create delegated UCAN",
        "description": "Create a delegated UCAN token from an existing token, narrowing capabilities.",
        "tags": ["UCAN"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["parent_token", "audience", "capabilities"],
                "properties": {
                  "parent_token": { "type": "string" },
                  "audience": { "type": "string" },
                  "capabilities": { "type": "array", "items": { "type": "object" } },
                  "expiration": { "type": "integer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delegated UCAN created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": { "type": "string" },
                    "parent_issuer": { "type": "string" },
                    "audience": { "type": "string" },
                    "depth": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/keys/generate": {
      "post": {
        "operationId": "generateKeys",
        "summary": "Generate cryptographic key pair",
        "description": "Generate a new cryptographic key pair for agent identity or encryption.",
        "tags": ["Keys"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "algorithm": { "type": "string", "example": "ed25519" },
                  "label": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key pair generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key_id": { "type": "string" },
                    "public_key": { "type": "string" },
                    "algorithm": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/keys/rotate": {
      "post": {
        "operationId": "rotateKeys",
        "summary": "Rotate keys",
        "description": "Rotate an existing key pair, generating a new key and deprecating the old one.",
        "tags": ["Keys"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["key_id"],
                "properties": {
                  "key_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keys rotated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "old_key_id": { "type": "string" },
                    "new_key_id": { "type": "string" },
                    "new_public_key": { "type": "string" },
                    "rotated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/keys/revoke": {
      "post": {
        "operationId": "revokeKeys",
        "summary": "Revoke keys",
        "description": "Revoke a key pair, marking it as permanently unusable.",
        "tags": ["Keys"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["key_id"],
                "properties": {
                  "key_id": { "type": "string" },
                  "reason": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Keys revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key_id": { "type": "string" },
                    "revoked": { "type": "boolean" },
                    "revoked_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/security/zero-day": {
      "post": {
        "operationId": "zeroDayAssessment",
        "summary": "Zero-day threat assessment",
        "description": "Perform a zero-day threat assessment. Costs $0.04/call.",
        "tags": ["Security"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["target"],
                "properties": {
                  "target": { "type": "string" },
                  "context": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Zero-day assessment result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "risk_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
                    "vulnerabilities": { "type": "array", "items": { "type": "object" } },
                    "recommendations": { "type": "array", "items": { "type": "string" } },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/credits/balance": {
      "get": {
        "operationId": "getCreditBalance",
        "summary": "Check credit balance",
        "description": "Check the remaining credit balance for the API key.",
        "tags": ["Credits"],
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Credit balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance": { "type": "number" },
                    "currency": { "type": "string", "example": "USD" },
                    "last_charged": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/credits/history": {
      "get": {
        "operationId": "getCreditHistory",
        "summary": "Credit usage history",
        "description": "Retrieve credit usage history for the API key.",
        "tags": ["Credits"],
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Credit history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "endpoint": { "type": "string" },
                          "amount": { "type": "number" },
                          "timestamp": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/credits/usage": {
      "get": {
        "operationId": "getCreditUsage",
        "summary": "Detailed usage breakdown",
        "description": "Get a detailed breakdown of credit usage by endpoint and time period.",
        "tags": ["Credits"],
        "security": [{ "ApiKeyAuth": [] }],
        "responses": {
          "200": {
            "description": "Usage breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": { "type": "string" },
                    "total_spent": { "type": "number" },
                    "by_endpoint": { "type": "object" },
                    "by_day": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/audit/log": {
      "post": {
        "operationId": "logAuditEvent",
        "summary": "Log audit event",
        "description": "Log an audit event. Costs $0.02/event.",
        "tags": ["Audit"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["event_type", "details"],
                "properties": {
                  "event_type": { "type": "string" },
                  "actor": { "type": "string" },
                  "details": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit event logged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "event_id": { "type": "string" },
                    "logged_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/audit/trail": {
      "get": {
        "operationId": "getAuditTrail",
        "summary": "Retrieve audit trail",
        "description": "Retrieve the audit trail. Costs $0.02/query.",
        "tags": ["Audit"],
        "parameters": [
          { "name": "actor", "in": "query", "schema": { "type": "string" }, "description": "Filter by actor" },
          { "name": "event_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by event type" }
        ],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Audit trail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "event_id": { "type": "string" },
                          "event_type": { "type": "string" },
                          "actor": { "type": "string" },
                          "details": { "type": "object" },
                          "timestamp": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "total": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/v1/audit/export": {
      "get": {
        "operationId": "exportAuditLog",
        "summary": "Export audit log",
        "description": "Export the full audit log. Costs $0.08/export.",
        "tags": ["Audit"],
        "security": [{ "ApiKeyAuth": [] }, { "X402PaymentProof": [] }],
        "responses": {
          "200": {
            "description": "Audit log export",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "export_id": { "type": "string" },
                    "events": { "type": "array", "items": { "type": "object" } },
                    "total": { "type": "integer" },
                    "exported_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcpEndpoint",
        "summary": "MCP server endpoint",
        "description": "Model Context Protocol (MCP) endpoint. Available tools: health, metrics, oracle_entropy, oracle_hallucination, ratchetgate_session, ratchetgate_register, ratchetgate_advance, inference, inference_stream.",
        "tags": ["Protocol"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP response",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/a2a": {
      "post": {
        "operationId": "a2aEndpoint",
        "summary": "A2A agent-to-agent endpoint",
        "description": "Google Agent-to-Agent (A2A) protocol endpoint. Supports methods: message/send, tasks/get.",
        "tags": ["Protocol"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method", "id"],
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "method": { "type": "string", "enum": ["message/send", "tasks/get"] },
                  "params": { "type": "object" },
                  "id": { "type": "string" }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "method": "message/send",
                "params": {
                  "message": {
                    "role": "user",
                    "parts": [{ "type": "text", "text": "Check health" }]
                  }
                },
                "id": "1"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A2A JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": { "type": "string" },
                    "result": { "type": "object" },
                    "id": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}