Replay API

REST API for the replay service: create sessions, submit trades, query leaderboards and journey progress.

Authentication

All endpoints except the leaderboard require a Bearer token, obtained via POST /api/auth/login.

Telegram users are auto-logged-in and bound via initData inside the Mini App (see @tradetrace_official_bot).

Authorization: Bearer <token>

Endpoints

POST/api/replay/sessionauth required

Field	Type	Required	Description
timeframe	string	no (1h)	"15m" \| "1h" \| "1d"
train_bars	int	no (300)	50–1000, bars to practise
leverage	float	no (5.0)	0 < lev ≤ 20
initial_balance	float	no (1000000)	> 0
mode	string	no (practice)	"practice" \| "journey"

Errors: 401 Unauthorized · 422 Validation Error · 503 liquidity pool exhausted

Sample response

{
  "session_id": 128,
  "trace_id": "b3f2c1a0-7d44-4e21-9f6a-2c8ab05d7411",
  "alias": "PK-4F2A",
  "timeframe": "1h",
  "total_bars": 400,
  "visible_bars": 100,
  "train_bars": 300,
  "bars": [{ "i": 0, "t": "2020-01-01T00:00:00+00:00",
             "o": 1001.2, "h": 1008.5, "l": 998.1, "c": 1004.9, "v": 98.3 }]
}

GET/api/replay/sessionsauth required

Errors: 401 Unauthorized

Sample response

{
  "total": 2,
  "items": [{
    "id": 128, "alias": "PK-4F2A", "timeframe": "1h",
    "status": "COMPLETED", "mode": "practice", "n_trades": 6,
    "net_return_pct": 0.0421, "max_drawdown_pct": -0.0312, "sharpe": 1.87,
    "started": "2026-10-29", "finished": "2026-10-29"
  }]
}

GET/api/replay/sessions/{sid}auth required

Field	Type	Required	Description
sid	int	yes	session id (path)

Errors: 401 Unauthorized · 404 not found / not yours

Sample response

{
  "session_id": 128, "alias": "PK-4F2A", "timeframe": "1h",
  "status": "COMPLETED",
  "metrics": { "net_return_pct": 0.0421, "sharpe": 1.87,
               "max_drawdown_pct": -0.0312, "win_rate": 0.5,
               "profit_factor": 1.62, "n_trades": 6 },
  "bars": [{ "i": 0, "o": 1001.2, "h": 1008.5, "l": 998.1, "c": 1004.9, "v": 98.3 }],
  "trades": [{ "bar_index": 104, "side": 1, "qty": 10, "price": 1012.4,
               "fee": 4.05, "position_after": 10, "meta": null }],
  "equity_curve": [{ "bar_index": 100, "equity": 1000000.0, "position": 0 }],
  "reveal": { "symbol": "ETHUSDT", "reveal_code": "R-7C21",
              "start": "2023-05-14 00:00:00", "end": "2023-05-28 00:00:00" }
}

POST/api/replay/finishauth required

Field	Type	Required	Description
trace_id	string	yes	trace from /session
trades[].bar	int	yes	bar index ≥ 0
trades[].side	int	yes	+1 long / -1 short
trades[].qty	float	yes	> 0
trades[].reason	string\|null	no	free-form tag
client_final_balance	float	yes	client-side final equity claim

Errors: 401 Unauthorized · 404 no ACTIVE session for this trace · 422 replay check failed (claimed balance mismatch) / validation

Sample response

{
  "ok": true,
  "session_id": 128,
  "metrics": { "final_balance": 1042100.0, "net_return_pct": 0.0421,
               "max_drawdown_pct": -0.0312, "sharpe": 1.87, "win_rate": 0.5,
               "profit_factor": 1.62, "n_trades": 6 },
  "reveal": { "symbol": "ETHUSDT", "reveal_code": "R-7C21",
              "start": "2023-05-14 00:00:00", "end": "2023-05-28 00:00:00" }
}

GET/api/replay/dailyauth required

Errors: 401 Unauthorized

Sample response

{
  "date": "2026-10-29",
  "trace_id": "5e8a01c4-…",
  "alias": "PK-9B03",
  "timeframe": "1h",
  "bars": [{ "i": 0, "t": "2020-01-01T00:00:00+00:00",
             "o": 872.1, "h": 879.4, "l": 869.8, "c": 875.6, "v": 120.4 }],
  "visible_bars": 100,
  "done": false
}

GET/api/replay/daily/leaderboardpublic

Field	Type	Required	Description
day	string	no (today)	YYYY-MM-DD query param

Sample response

{
  "date": "2026-10-29",
  "items": [{
    "username": "kou", "display_name": "Kou",
    "net_return_pct": 0.121, "sharpe": 2.4, "n_trades": 8
  }]
}

POST/api/replay/daily/finishauth required

Field	Type	Required	Description
body	object	yes	same body as POST /finish

Errors: 400 trace does not match today's challenge · 401 Unauthorized · 404 no ACTIVE session · 409 already entered today · 422 replay check failed / validation

Sample response

{
  "ok": true,
  "session_id": 130,
  "metrics": { "final_balance": 1121000.0, "net_return_pct": 0.121, … },
  "reveal": { "symbol": "SOLUSDT", "reveal_code": "R-31D9", … }
}

GET/api/replay/journeyauth required

Errors: 401 Unauthorized

Sample response

{
  "balance": 1234500.0,
  "won": false,
  "lost": false,
  "next_initial": 1234500.0
}