{
  "openapi": "3.1.0",
  "info": {
    "title": "unCoded Backtesting API",
    "version": "1.0.0",
    "description": "Read-only, public access to unCoded's crypto trading-bot backtesting data: over 10,000 historical backtests across 80+ exchanges, with returns, win rates, drawdowns and trade-level detail. Backtests use 1-second to 1-minute base candles with an intrabar fill model. No authentication is required for these GET endpoints. unCoded is a non-custodial, self-hosted automated trading bot operated by ArrowTrade AG (Switzerland).",
    "contact": {
      "name": "unCoded",
      "url": "https://uncoded.ch"
    },
    "license": {
      "name": "Public backtest data, attribution requested",
      "url": "https://uncoded.ch/llms.txt"
    }
  },
  "servers": [
    {
      "url": "https://uncoded.ch",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Human-readable documentation",
    "url": "https://uncoded.ch/docs"
  },
  "tags": [
    { "name": "Backtests", "description": "Historical strategy backtests" },
    { "name": "Reference", "description": "Available strategy modes and trading symbols" }
  ],
  "paths": {
    "/api/backtesting/backtests": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "listBacktests",
        "summary": "List backtests",
        "description": "Returns a paginated list of completed backtests.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 20 }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page index.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of backtests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Backtest" }
                }
              }
            }
          }
        }
      }
    },
    "/api/backtesting/backtests/top": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "getTopBacktests",
        "summary": "Top-performing backtests",
        "description": "Returns the best-performing backtests ranked by return. Used to surface outperformers versus buy-and-hold.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page index.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "A ranked list of backtests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Backtest" }
                }
              }
            }
          }
        }
      }
    },
    "/api/backtesting/backtests/{id}": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "getBacktest",
        "summary": "Get a single backtest",
        "description": "Returns the full record for one backtest, including headline KPIs and configuration.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Backtest identifier.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The backtest record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Backtest" }
              }
            }
          },
          "404": { "description": "Backtest not found." }
        }
      }
    },
    "/api/backtesting/backtests/{id}/trades": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "getBacktestTrades",
        "summary": "Trade list for a backtest",
        "description": "Returns the individual trades executed during a backtest.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Backtest identifier.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Trade records for the backtest.",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      }
    },
    "/api/backtesting/backtests/{id}/equity": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "getBacktestEquity",
        "summary": "Equity curve for a backtest",
        "description": "Returns the equity-over-time series for a backtest.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Backtest identifier.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Equity curve points.",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      }
    },
    "/api/backtesting/backtests/{id}/daily-stats": {
      "get": {
        "tags": ["Backtests"],
        "operationId": "getBacktestDailyStats",
        "summary": "Daily statistics for a backtest",
        "description": "Returns aggregated per-day statistics for a backtest.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Backtest identifier.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Daily statistics.",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      }
    },
    "/api/backtesting/modes": {
      "get": {
        "tags": ["Reference"],
        "operationId": "listModes",
        "summary": "List strategy modes",
        "description": "Returns the available trading strategy modes used by backtests.",
        "responses": {
          "200": {
            "description": "Available strategy modes.",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      }
    },
    "/api/backtesting/symbols": {
      "get": {
        "tags": ["Reference"],
        "operationId": "listSymbols",
        "summary": "List trading symbols",
        "description": "Returns the trading symbols (e.g. BTCUSDT) available in the backtest dataset.",
        "responses": {
          "200": {
            "description": "Available symbols.",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Backtest": {
        "type": "object",
        "description": "A single historical backtest result.",
        "required": ["id", "symbol", "mode_name", "status", "created_at"],
        "properties": {
          "id": { "type": "string", "description": "Unique backtest identifier." },
          "description": { "type": "string", "description": "Optional human-readable label." },
          "symbol": { "type": "string", "description": "Traded symbol, e.g. BTCUSDT." },
          "mode_name": { "type": "string", "description": "Strategy mode used for the run." },
          "status": { "type": "string", "description": "Run status.", "enum": ["queued", "running", "completed", "failed"] },
          "return_pct": { "type": ["number", "null"], "description": "Total return of the strategy in percent." },
          "fulfilled_trades": { "type": ["integer", "null"], "description": "Number of completed trades." },
          "win_rate": { "type": ["number", "null"], "description": "Share of winning trades (0-1 or percent depending on context)." },
          "final_value": { "type": ["number", "null"], "description": "Portfolio value at the end of the run." },
          "total_profit": { "type": ["number", "null"], "description": "Absolute profit in quote currency." },
          "start_balance": { "type": ["number", "null"], "description": "Starting balance." },
          "max_drawdown": { "type": ["number", "null"], "description": "Maximum peak-to-trough drawdown." },
          "profit_factor": { "type": ["number", "null"], "description": "Gross profit divided by gross loss." },
          "sharpe_ratio": { "type": ["number", "null"], "description": "Sharpe ratio of the run." },
          "total_fees": { "type": ["number", "null"], "description": "Total trading fees paid." },
          "start_price": { "type": ["number", "null"], "description": "Asset price at the start of the window (for buy-and-hold comparison)." },
          "end_price": { "type": ["number", "null"], "description": "Asset price at the end of the window (for buy-and-hold comparison)." },
          "created_at": { "type": "string", "format": "date-time", "description": "When the backtest was created." },
          "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When the backtest completed." }
        }
      }
    }
  }
}