Docs

API reference

API overview

Base URL, conventions, units, pagination and the shared object types.

Base URL#

text
https://dapp.forgeus.science

All paths start with /v1. The base URL will change when the domain is set (TBD).

Conventions#

  • Public endpoints are GET, need no key, and send Access-Control-Allow-Origin: *.
  • Responses are JSON unless noted (CSV, RSS, notebook).
  • Returns, drawdowns and fitness are fractions: 0.0012 = 0.12%.
  • Genome thresholds and stops are in basis points.
  • Times are Unix seconds.
  • Hashes are lowercase hex SHA-256.
  • Lists that page take limit and before, and return next. Pass next as before to get the next page. No next means you reached the end.
  • Signed-in endpoints take Authorization: Bearer <token>. See Auth.
Note

Response blocks below are shapes: field names with their types, not real data.

Shared types#

Quote·ts
type Quote = {
  id: number;
  market: "ETH-USDC" | "BTC-USDC";
  block: number;      // Base block the pool was read at
  ts: number;         // unix seconds of that block
  sqrt_price: string; // slot0 sqrtPriceX96, decimal string
  price: number;      // USDC per base asset
};
Genome·ts
type Genome = {
  kind: "momentum" | "meanrev" | "breakout" | "trend";
  market: "ETH-USDC" | "BTC-USDC";
  lookback: number;      // 3..60 quotes
  threshold_bps: number; // 0..100
  size: number;          // 0.1..1
  stop_bps: number;      // 20..400
};
Trade·ts
type Trade = {
  strategy: string;  // circuit id, e.g. "f12-03"
  market: "ETH-USDC" | "BTC-USDC";
  quote_id: number;
  block: number;
  ts: number;
  price: number;
  from: number;      // position before, -1..1
  to: number;        // position after
  reason: "signal" | "stop" | "close";
};
Strategy·ts
type Strategy = {
  id: string;
  genome: Genome;
  parent: string | null;
  born: number;            // generation it was born in
  died: number | null;     // generation it was culled in
  status: "active" | "challenger" | "eliminated";
  gens: number;            // generations evaluated
  positive: number;        // generations with positive fitness
  cum_ret: number;
  cum_hold: number;        // cumulative hold return of its market
  worst_dd: number;
  trades: number;
  last_fitness: number | null;
  best_fitness: number | null;
};

The generation record is described field by field in Generations & the hash chain.

Endpoint groups#

GroupEndpoints
Status & live/v1/health, /v1/config, /v1/stats, /v1/live
Generationslist, detail, archive, trades, annotations
Strategies & lineage/v1/strategies, /v1/strategies/:id, /v1/lineage/:id
Trades & quotes/v1/trades, /v1/quotes
Research logsmutations, nulls, composition, survival
Evidence & chain/v1/evidence, /v1/chain
Exports, RSS & notebooksCSV, JSON, RSS, .ipynb
Authnonce, verify, me
Annotationsread and write notes
Governanceproposals and votes
Webhooksmanage webhooks, verify signatures

Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.