{
  "openapi": "3.1.0",
  "info": {
    "title": "Avaltix Agent API",
    "version": "1.1.0",
    "description": "Canonical read-only REST API for timestamped IA1/IA2/IA3 market forecasts and public evidence. Forecasts are probabilistic data, not financial advice. Free data must be cited as Avaltix (avaltix.io).",
    "termsOfService": "https://avaltix.io/legal/terms.php",
    "contact": {"name":"Avaltix support","email":"support@avaltix.io","url":"https://avaltix.io/agents/"}
  },
  "servers": [{"url":"https://avaltix.io","description":"Production"}],
  "externalDocs": {"description":"Agent quickstart and MCP tools","url":"https://avaltix.io/agents/"},
  "tags": [
    {"name":"Discovery","description":"Public discovery and schema demo"},
    {"name":"Forecasts","description":"Key-protected forecast data"},
    {"name":"Evidence","description":"Public methodology and expired outcomes"}
  ],
  "paths": {
    "/api/agent/v1/": {
      "get": {"tags":["Discovery"],"operationId":"discoverAgentApi","summary":"Discover the canonical API","security":[],"responses":{"200":{"description":"Live routes, tiers and MCP endpoint","content":{"application/json":{"schema":{"type":"object"}}}}}}
    },
    "/api/agent/v1/demo.php": {
      "get": {"tags":["Discovery"],"operationId":"getDemoPrediction","summary":"No-key delayed forecast demo","security":[],"parameters":[{"name":"symbol","in":"query","schema":{"type":"string","enum":["BTC/USD","ETH/USD","EUR/USD"],"default":"BTC/USD"}}],"responses":{"200":{"description":"60-minute-delayed multi-horizon forecast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
    },
    "/api/agent/v1/register.php": {
      "post": {"tags":["Discovery"],"operationId":"registerFreeKey","summary":"Create a free API key without human approval","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":190}},"additionalProperties":false}}},"responses":{"201":{"description":"Secret returned once; only SHA-256 hash is stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"400":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
      }
    },
    "/api/agent/v1/predictions.php": {
      "get": {"tags":["Forecasts"],"operationId":"getPredictions","summary":"Latest forecast per available timeframe","security":[{"bearerKey":[]}],"parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"example":"BTC/USD"},{"name":"candles","in":"query","schema":{"type":"string","enum":["1"]},"description":"Include 96 OHLCV candles for 15min and 1h"}],"responses":{"200":{"description":"Forecast envelope; free keys receive 15-minute-delayed data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastEnvelope"}}}},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
    },
    "/api/agent/v1/symbols.php": {
      "get": {"tags":["Forecasts"],"operationId":"listSymbols","summary":"List symbols and latest forecast timestamps","security":[{"bearerKey":[]}],"responses":{"200":{"description":"Universe with per-timeframe epoch timestamps","content":{"application/json":{"schema":{"type":"object","required":["ok","count","symbols","meta"],"properties":{"ok":{"const":true},"count":{"type":"integer"},"symbols":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"timeframes":{"type":"object","additionalProperties":{"type":"integer"}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"401":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
      }
    },
    "/api/agent/v1/track-record.php": {
      "get": {"tags":["Evidence"],"operationId":"getTrackRecord","summary":"Public current-protocol aggregate outcomes","description":"Returns every timeframe with win/loss/neutral counts, resolved and all-settlement rates, Wilson 95% intervals and maturity labels.","security":[],"parameters":[{"name":"symbol","in":"query","schema":{"type":"string"},"description":"Optional canonical symbol filter"}],"responses":{"200":{"description":"Current compatible protocol cohort only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackRecord"}}}},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
    },
    "/api/agent/v1/accuracy.php": {
      "get": {"tags":["Evidence"],"operationId":"getAccuracy","summary":"Track-record alias with symbol/timeframe filters","security":[],"parameters":[{"name":"symbol","in":"query","schema":{"type":"string"}},{"name":"tf","in":"query","schema":{"type":"string","enum":["1min","5min","15min","30min","1h","2h","3h","4h","6h","1d"]}}],"responses":{"200":{"description":"Filtered current-protocol evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackRecord"}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
    },
    "/api/agent/v1/verify.php": {
      "get": {"tags":["Evidence"],"operationId":"verifyPrediction","summary":"Inspect one expired prediction and its canonical settlement","security":[],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Stored forecast, market closes and settlement","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}
    }
  },
  "components": {
    "securitySchemes": {"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"avx_ag_<40 hex>","description":"Free key from POST /api/agent/v1/register.php"}},
    "responses": {"Problem":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},
    "schemas": {
      "Meta": {"type":"object","required":["source","license","disclaimer","tier","data_delay_min"],"properties":{"source":{"const":"Avaltix (avaltix.io)"},"license":{"type":"string"},"disclaimer":{"type":"string"},"tier":{"type":"string"},"data_delay_min":{"type":"integer"},"docs":{"type":"string","format":"uri"},"quickstart":{"type":"string","format":"uri"},"track_record":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"server_t":{"type":"integer"}}},
      "EngineForecast": {"type":"object","required":["tf","ts","horizon_min","target_t","age_s","ia1","ia2","ia3"],"properties":{"tf":{"type":"string"},"ts":{"type":"integer"},"horizon_min":{"type":"integer"},"target_t":{"type":"integer"},"age_s":{"type":"integer"},"status":{"type":"string"},"anchor_price":{"type":["number","null"]},"target_price":{"type":["number","null"]},"ia1":{"type":"object"},"ia2":{"type":"object"},"ia3":{"type":"object"}}},
      "ForecastEnvelope": {"type":"object","required":["ok","symbol","predictions","meta"],"properties":{"ok":{"const":true},"demo":{"type":"boolean"},"symbol":{"type":"string"},"price":{"type":["object","null"]},"predictions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/EngineForecast"}},"candles":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}},
      "Registration": {"type":"object","required":["ok","api_key","tier","limits","endpoints","meta"],"properties":{"ok":{"const":true},"api_key":{"type":"string","pattern":"^avx_ag_[0-9a-f]{40}$"},"important":{"type":"string"},"tier":{"const":"free"},"limits":{"type":"object"},"endpoints":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}},
      "TrackRecord": {"type":"object","required":["ok","protocol","totals","results","generated_at","meta"],"properties":{"ok":{"const":true},"protocol":{"type":"object","properties":{"id":{"type":"string"},"starts_at_utc":{"type":"string","format":"date-time"},"direction":{"type":"string"},"settlement":{"type":"string"},"status":{"type":"string"}}},"symbol":{"type":"string"},"totals":{"type":"object"},"results":{"type":"array","items":{"type":"object","properties":{"timeframe":{"type":"string"},"n_settled":{"type":"integer"},"outcomes":{"type":"object"},"resolved_win_rate":{"type":["number","null"]},"resolved_win_rate_ci95":{"type":["array","null"],"items":{"type":"number"}},"positive_outcome_rate":{"type":["number","null"]},"average_return_pct":{"type":["number","null"]},"maturity":{"type":"string","enum":["insufficient_sample","early_sample","growing_sample"]}}}},"generated_at":{"type":"string","format":"date-time"},"meta":{"$ref":"#/components/schemas/Meta"}}},
      "Problem": {"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"meta":{"$ref":"#/components/schemas/Meta"}}}
    }
  }
}