{
  "openapi": "3.0.0",
  "info": {
    "title": "Ver Protocol Compiler API",
    "description": "Deterministic BOT Chain protocol compiler and wallet-safety API. Compiles smart contracts into Protocol Graphs and maps natural-language intent to ABI-verified, simulated EVM calldata.",
    "version": "1.0.6",
    "contact": { "name": "Ver Protocol", "url": "https://verprotocol.vercel.app" }
  },
  "servers": [{ "url": "https://verprotocol.vercel.app" }],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service healthy",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/compile": {
      "get": {
        "summary": "Compile a contract into a deterministic Protocol Graph",
        "description": "Fetches verified contract artifacts and returns a structured graph: roles, functions, events, dependencies, proxy/implementation resolution.",
        "operationId": "compile",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Required BOT Chain contract address (0x...)."
          }
        ],
        "responses": {
          "200": {
            "description": "Protocol graph + mermaid + trace",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "429": { "description": "Rate limited" },
          "500": { "description": "Compile error" }
        }
      },
      "post": {
        "summary": "Compile a contract into a deterministic Protocol Graph",
        "operationId": "compilePost",
        "requestBody": {
          "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" } } } } }
        },
        "responses": { "200": { "description": "Protocol graph" } }
      }
    },
    "/api/compile-intent": {
      "post": {
        "summary": "Map natural-language intent to ABI-verified EVM calldata",
        "description": "Accepts one complete approve AMOUNT SYMBOL to ADDRESS or transfer AMOUNT SYMBOL to ADDRESS request. No conditions, negations, compound actions or AI fallback. Symbol and exact token units must match the target. Sender simulation and valid token return data are required for signability.",
        "operationId": "compileIntent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chainId": { "type": "integer", "enum": [968, 196], "description": "BOT Chain is primary; 196 is compatibility-only." },
                  "contractAddress": { "type": "string", "description": "Target contract (0x...)" },
                  "intent": { "type": "string", "description": "Natural language intent" },
                  "sender": { "type": "string", "description": "Optional sender for eth_call simulation" }
                },
                "required": ["contractAddress", "intent"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulation passed; unsigned preparation still requires independent wallet validation and user confirmation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "functionName": { "type": "string" },
                    "args": { "type": "array" },
                    "encodedCalldata": { "type": "string" },
                    "simulationStatus": { "enum": ["success", "reverted", "skipped", "failed", "unavailable"] },
                    "signable": { "type": "boolean" },
                    "blockingReasons": { "type": "array", "items": { "type": "string" } },
                    "sender": { "type": "string" },
                    "preparedAt": { "type": "string", "format": "date-time" },
                    "expiresAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "422": { "description": "Intent compiled but cannot be signed or was blocked" },
          "429": { "description": "Rate limited" },
          "400": { "description": "Invalid request" },
          "503": { "description": "Preparation dependency unavailable" }
        }
      }
    },
    "/api/wallet/prepare": {
      "post": {
        "summary": "Prepare and simulate an unsigned wallet transaction",
        "description": "Deterministic single ERC-20 approval/transfer only. Requires matching token symbol, exact precision and a successful sender simulation including valid token return data. A signable result is not an audit or execution guarantee. Wallet must check active account/chain, decoded calldata, expiry, and get explicit user confirmation.",
        "operationId": "prepareWalletTransaction",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "additionalProperties": false,
            "required": ["chainId", "contractAddress", "intent", "sender"],
            "properties": {
              "chainId": { "type": "integer", "enum": [968, 196], "description": "BOT Chain is primary; 196 is compatibility-only." },
              "contractAddress": { "type": "string" },
              "intent": { "type": "string", "minLength": 1, "maxLength": 1000 },
              "sender": { "type": "string" },
              "value": { "type": "string", "pattern": "^[0-9]+$" }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Simulation succeeded; wallet checks and user confirmation still required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedTransaction" } } } },
          "400": { "$ref": "#/components/responses/Blocked" },
          "413": { "$ref": "#/components/responses/Blocked" },
          "422": { "description": "Preparation blocked; inspect signable and blockingReasons, never success alone", "content": { "application/json": { "schema": { "type": "object", "required": ["signable", "blockingReasons"], "properties": { "signable": { "type": "boolean", "enum": [false] }, "blockingReasons": { "type": "array", "items": { "type": "string" } }, "simulationStatus": { "type": "string", "enum": ["skipped", "reverted", "failed", "unavailable"] } } } } } },
          "429": { "$ref": "#/components/responses/Blocked" },
          "503": { "$ref": "#/components/responses/Blocked" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Blocked": { "description": "Invalid, oversized, rate-limited or unavailable request; non-signable JSON. Rate limits include Retry-After seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedError" } } } }
    },
    "schemas": {
      "BlockedError": {
        "type": "object", "required": ["success", "signable", "risk", "blockingReasons", "error"],
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "signable": { "type": "boolean", "enum": [false] },
          "risk": { "type": "string", "enum": ["blocked"] },
          "simulationStatus": { "type": "string", "enum": ["skipped"] },
          "blockingReasons": { "type": "array", "items": { "type": "string" } },
          "error": { "type": "string" }
        }
      },
      "PreparedTransaction": {
        "type": "object", "required": ["success", "signable", "simulationStatus", "risk", "blockingReasons", "chainId", "sender", "preparedAt", "expiresAt", "requiresUserConfirmation", "transaction"],
        "properties": {
          "success": { "type": "boolean", "enum": [true] },
          "signable": { "type": "boolean", "enum": [true] },
          "simulationStatus": { "type": "string", "enum": ["success"] },
          "risk": { "type": "string", "enum": ["review"] },
          "blockingReasons": { "type": "array", "maxItems": 0, "items": { "type": "string" } },
          "chainId": { "type": "integer", "enum": [968, 196] },
          "sender": { "type": "string" },
          "preparedAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time", "description": "60-second preparation lifetime; wallet must discard expired results." },
          "requiresUserConfirmation": { "type": "boolean", "enum": [true] },
          "transaction": {
            "type": "object", "required": ["chainId", "from", "to", "data", "value"],
            "properties": { "chainId": { "type": "integer", "enum": [968, 196] }, "from": { "type": "string" }, "to": { "type": "string" }, "data": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" }, "value": { "type": "string", "pattern": "^0+$" } }
          }
        }
      }
    }
  }
}