API reference
API overview
Base URL, conventions, units, pagination and the shared object types.
Base URL#
text
https://dapp.forgeus.scienceAll paths start with /v1. The base URL will change when the domain is set (TBD).
Conventions#
- Public endpoints are
GET, need no key, and sendAccess-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
limitandbefore, and returnnext. Passnextasbeforeto get the next page. Nonextmeans 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#
| Group | Endpoints |
|---|---|
| Status & live | /v1/health, /v1/config, /v1/stats, /v1/live |
| Generations | list, detail, archive, trades, annotations |
| Strategies & lineage | /v1/strategies, /v1/strategies/:id, /v1/lineage/:id |
| Trades & quotes | /v1/trades, /v1/quotes |
| Research logs | mutations, nulls, composition, survival |
| Evidence & chain | /v1/evidence, /v1/chain |
| Exports, RSS & notebooks | CSV, JSON, RSS, .ipynb |
| Auth | nonce, verify, me |
| Annotations | read and write notes |
| Governance | proposals and votes |
| Webhooks | manage webhooks, verify signatures |
Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.