{
  "openapi": "3.1.0",
  "info": {
    "title": "Toreva",
    "version": "0.1.0",
    "description": "Non-custodial execution primitives for DeFi on Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. Data transactions are free; value-moving transactions are 2 bps (0.02%). Local signing only — Toreva never holds funds and never transmits private keys.",
    "termsOfService": "https://toreva.com/legal",
    "contact": {
      "name": "Toreva developer relations",
      "email": "dev@toreva.com",
      "url": "https://github.com/toreva/kit"
    },
    "license": {
      "name": "MIT (SDK / CLI / examples)",
      "url": "https://github.com/toreva/kit/blob/main/LICENSE"
    }
  },
  "servers": [
    { "url": "https://gateway.toreva.com", "description": "Production HTTP relay" },
    { "url": "https://mcp.toreva.com", "description": "Production MCP server (HTTP transport)" },
    { "url": "stdio://npx -y @toreva/mcp", "description": "Local stdio MCP transport (npm package)" }
  ],
  "tags": [
    { "name": "perps", "description": "Perpetual futures execution and queries (Jupiter Perps / Pacifica / Drift / Flash Trade)" },
    { "name": "earn", "description": "Yield strategies and staking" },
    { "name": "scan", "description": "Wallet scanning and balance/portfolio queries" },
    { "name": "simulate", "description": "Pre-flight simulation (free)" }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Toreva auth token issued via `npx toreva login` (device-code flow) or programmatic enrollment. Authenticates the caller's Toreva identity; does NOT carry signing authority. Wallet keypair is held locally by the caller and never transits Toreva."
      }
    },
    "schemas": {
      "WalletAddress": {
        "type": "string",
        "minLength": 32,
        "maxLength": 88,
        "description": "Solana wallet address (base58)."
      },
      "PerpsOpenInput": {
        "type": "object",
        "required": ["token", "sizeUsd", "leverage", "collateralToken", "collateralAmount", "walletAddress"],
        "properties": {
          "token": { "type": "string", "description": "Token to take a position on (e.g. SOL, BTC, ETH)." },
          "sizeUsd": { "type": "number", "description": "Position size in USD notional." },
          "leverage": { "type": "number", "minimum": 1, "maximum": 101 },
          "collateralToken": { "type": "string" },
          "collateralAmount": { "type": "number" },
          "walletAddress": { "$ref": "#/components/schemas/WalletAddress" },
          "maxSlippageBps": { "type": "integer", "minimum": 0, "maximum": 1000 },
          "venue": { "type": "string", "enum": ["jupiter-perps", "pacifica", "drift", "flash"], "description": "Optional venue override; otherwise routed by best-execution." },
          "stopLoss": { "type": "number", "description": "Optional stop-loss trigger price." },
          "takeProfit": { "type": "number", "description": "Optional take-profit trigger price." },
          "marginMode": { "type": "string", "enum": ["cross", "isolated"] },
          "builderCode": { "type": "string", "description": "Pacifica Builder Program code for fee share." },
          "clientRequestId": { "type": "string", "description": "Idempotency key. Re-sending the same value returns the original tx; never double-fires." }
        }
      },
      "Receipt": {
        "type": "object",
        "required": ["requestId", "timestamp", "venue", "transactions"],
        "properties": {
          "requestId": { "type": "string", "description": "Toreva-side request identifier." },
          "timestamp": { "type": "string", "format": "date-time" },
          "venue": { "type": "string" },
          "transactions": { "type": "array", "items": { "type": "string", "description": "On-chain Solana tx signature, verifiable on Solana explorer." } },
          "positionState": {
            "type": "object",
            "properties": {
              "sizeUsd": { "type": "string" },
              "fillPrice": { "type": "string" },
              "liquidationPrice": { "type": "string" }
            }
          },
          "fees": {
            "type": "object",
            "properties": {
              "torevaBps": { "type": "number", "description": "Toreva execution fee in basis points on value-moving transactions (current default: 2; 1 for EVA-token holders via TOR-staking discount path)." },
              "venueBps": { "type": "number" },
              "totalBps": { "type": "number" }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "retryable": { "type": "boolean" }
        }
      }
    }
  },
  "paths": {
    "/relay": {
      "post": {
        "summary": "MCP-tool dispatch via HTTP relay",
        "description": "All Toreva MCP tools (perps_long, perps_close, perps_simulate, etc.) dispatch through this endpoint. The relay routes to the appropriate venue adapter (Jupiter / Pacifica / Drift / Flash) based on best-execution, builds the on-chain transaction, and returns it UNSIGNED. The caller signs locally with their wallet keypair and submits.",
        "tags": ["perps"],
        "security": [{ "bearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "payload"],
                "properties": {
                  "type": { "type": "string", "description": "Message type, e.g. perps.open_long" },
                  "toolName": { "type": "string" },
                  "payload": { "type": "object" },
                  "requestId": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "401": { "description": "Unauthorized" },
          "429": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retry." } } }
        }
      }
    },
    "/api/v1/perps/build-tx": {
      "post": {
        "summary": "Build perp transaction (UNSIGNED)",
        "description": "Returns the unsigned Solana transaction(s) for an open / close / margin-adjust action. Caller signs locally; Toreva never sees the private key.",
        "tags": ["perps"],
        "security": [{ "bearer": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PerpsOpenInput" }
            }
          }
        },
        "responses": {
          "200": { "description": "OK; returns unsigned tx + receipt scaffold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } },
          "400": { "description": "Bad request" },
          "401": { "description": "Unauthorized" }
        }
      }
    }
  }
}