{
  "openapi": "3.1.0",
  "info": {
    "title": "E2 Local API",
    "version": "1.1.0-local",
    "description": "Local API over the verified E2 database. Intelligence endpoints are read-only. Swap endpoints proxy the official Uniswap Trading API and never sign for the user. No public availability or service-level commitment is implied."
  },
  "servers": [{ "url": "http://localhost:3000", "description": "Local development server" }],
  "paths": {
    "/api/v1/assets": { "get": { "summary": "List canonical assets and latest current-state intelligence", "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/assets/{address}": { "get": { "summary": "Get one canonical asset by exact chain-4663 contract address", "parameters": [{ "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }], "responses": { "200": { "$ref": "#/components/responses/Envelope" }, "404": { "description": "Canonical asset not found" } } } },
    "/api/v1/markets": { "get": { "summary": "List indexed, onchain-verified Uniswap markets", "parameters": [{ "$ref": "#/components/parameters/AssetFilter" }], "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/references": { "get": { "summary": "List reconciled references and integrity states", "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/depth": { "get": { "summary": "List five-band immediate depth and capacity completeness", "parameters": [{ "$ref": "#/components/parameters/AssetFilter" }], "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/freshness": { "get": { "summary": "Read independent reference, inventory, depth and live-quote freshness clocks", "responses": { "200": { "description": "Current local freshness state" } } } },
    "/api/v1/market-health": { "get": { "summary": "List E2 market-health primitives and definitions", "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/opportunities": { "get": { "summary": "List opportunity states, explicitly null while history is incomplete", "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/history/status": { "get": { "summary": "Read exact targeted-history checkpoints and missing windows", "responses": { "200": { "$ref": "#/components/responses/Envelope" } } } },
    "/api/v1/swap/token": {
      "get": {
        "summary": "Resolve chain-4663 token metadata by exact address",
        "parameters": [{ "name": "address", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Address" } }],
        "responses": { "200": { "description": "Exact-address token metadata" }, "400": { "description": "Invalid address" } }
      }
    },
    "/api/v1/swap/quote": {
      "post": {
        "summary": "Request an official Uniswap BEST_PRICE quote for any chain-4663 token pair",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuoteRequest" } } } },
        "responses": { "200": { "description": "Resolved tokens, route, price impact, slippage, reference premium, approval and execution journey" }, "400": { "description": "Invalid request or unavailable route" }, "503": { "description": "Trading API credential is not configured" } }
      }
    },
    "/api/v1/swap/execute": {
      "post": {
        "summary": "Prepare a classic wallet transaction or submit a wallet-signed UniswapX order",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapExecuteRequest" } } } },
        "responses": { "200": { "description": "Unsigned classic transaction or submitted UniswapX order identity" }, "400": { "description": "Invalid or expired quote journey" }, "503": { "description": "Trading API credential is not configured" } }
      }
    }
  },
  "components": {
    "parameters": {
      "AssetFilter": { "name": "asset", "in": "query", "required": false, "description": "Exact canonical chain-4663 contract address", "schema": { "$ref": "#/components/schemas/Address" } }
    },
    "responses": {
      "Envelope": { "description": "A provenance-complete E2 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }
    },
    "schemas": {
      "Address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" },
      "SwapQuoteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["tokenIn", "tokenOut", "inputAmount", "slippageBps", "swapper"],
        "properties": {
          "tokenIn": { "$ref": "#/components/schemas/Address" },
          "tokenOut": { "$ref": "#/components/schemas/Address" },
          "inputAmount": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$", "description": "Exact input amount in display units" },
          "slippageBps": { "type": "integer", "minimum": 1, "maximum": 5000 },
          "swapper": { "$ref": "#/components/schemas/Address" }
        }
      },
      "SwapExecuteRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["quote", "swapper"],
        "properties": {
          "quote": { "type": "object", "description": "Unmodified execution journey returned by /swap/quote" },
          "swapper": { "$ref": "#/components/schemas/Address" },
          "permitData": { "type": ["object", "null"], "description": "Permit2 typed data from the quote" },
          "signature": { "type": ["string", "null"], "description": "Wallet signature when the quoted journey requires it" }
        }
      },
      "Envelope": {
        "type": "object",
        "required": ["schemaVersion", "data", "meta"],
        "properties": {
          "schemaVersion": { "const": "1.0.0" },
          "data": { "description": "Endpoint-specific data. Missing numeric evidence is null, not an invented zero." },
          "meta": { "$ref": "#/components/schemas/Metadata" }
        }
      },
      "Metadata": {
        "type": "object",
        "required": ["provenance", "block", "retrievalTimestamp", "completeness", "referenceStatus"],
        "properties": {
          "provenance": { "type": "array", "minItems": 1, "items": { "type": "string" } },
          "block": { "type": "object", "required": ["number", "hash"], "properties": { "number": { "type": ["integer", "null"] }, "hash": { "type": ["string", "null"] } } },
          "retrievalTimestamp": { "type": "string", "format": "date-time" },
          "completeness": { "type": "object", "required": ["status", "scope", "missing"], "properties": { "status": { "enum": ["complete", "partial", "unavailable"] }, "scope": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" } } } },
          "referenceStatus": { "type": ["string", "null"] }
        }
      }
    }
  }
}