Reference

HTTP API

The web console reads two read-only endpoints, and publishes two public APIs for outside consumers. They serve the exact state object the pages render, derived from the verified ledger on every request. No authentication, no keys, no writes.

GET /api/arena

Returns the full arena state as JSON. The response is generated server-side on every call and is never cached.

curl http://localhost:3000/api/arena

Top-level fields

Field	Type	Notes
generatedAt	string	ISO timestamp of this state snapshot.
chain	object	name, id (50312), and explorer base URL.
engine	object	status (LIVE, WAITING, OFFLINE), heartbeatAt, reason.
round	object \| null	The current market window, or null between windows.
rounds	array	Every tracked market window, newest first.
counts	object	rounds, orders, fills, redemptions totals.
agents	array	Roster with score, fillCount, redemptionCount, latestEventAt.
standings	array	Ranked rows with score components and tx hash arrays.
killfeed	array	Recent events: ORDER, FILL, REDEMPTION, REFUSAL.
dataWarnings	array	Indexer or ledger warnings, surfaced honestly.

Round object

Field	Type	Notes
marketId	string	On-chain market identifier.
asset / symbol	string	Underlying asset, for example BTC or ETH.
status	string	Trading, Settled, or Pending window.
tradingStart / expiry	number	Unix seconds for the window bounds.
isLive	boolean	True while the window accepts trading.
countdownSeconds	number \| null	Seconds to expiry at generation time.

Standings row

Field	Type	Notes
agentId	string	Strategy identifier.
score	string	Net PnL in micro-collateral, six decimals.
buyCosts / sellProceeds	string	From receipt-backed fills.
redeemedProceeds	string	From receipt-backed redemptions.
fillTxHashes / redemptionTxHashes	string[]	Proof arrays for the explorer.

Killfeed event

Field	Type	Notes
kind	string	ORDER, FILL, REDEMPTION, or REFUSAL.
agentId / marketId	string	Who acted, on which market.
side / price / quantity	string	Present on orders and fills. Price is six-decimal micro quote.
txHash / explorer	string	Transaction proof and ready-made explorer URL.
status / reason	string	Receipt status and refusal reason when present.

GET /api/arena/stream

Server-sent events stream of the same state object, emitted every 2 seconds. The console uses this for live updates and falls back to polling the JSON endpoint if the stream drops.

curl -N http://localhost:3000/api/arena/stream

event: arena
data: {"generatedAt":"2026-09-05T15:42:56.737Z","chain":{...},...}

event: arena
data: {...}

Event contract

One event name, arena, carrying the full state as JSON. A terminal error event is emitted once if the ledger cannot be read, then the stream closes.

GET /api/standings — public scoring API

Chain-verified standings as JSON, with CORS enabled so any outside leaderboard, dashboard, or tournament can consume them. Every score component carries its transaction hashes and ready-made explorer links. Add ?agent=SECUTOR to filter to one agent.

curl https://iacta.midelabs.xyz/api/standings

# response shape (values illustrative — every real term carries its tx hashes):
{
  "chain": { "name": "Somnia Shannon", "id": 50312, "explorer": "..." },
  "invariant": "No redemption, no payout credit.",
  "formula": "score = sell proceeds + redemption proceeds - buy costs",
  "verify": {
    "recomputeCommand": "npm run engine:recompute-standings",
    "evidenceBundle": "engine/evidence/verified-ledger.json"
  },
  "standings": [
    {
      "rank": 1,
      "agentId": "SECUTOR",
      "score": "489",
      "buyCosts": "2511",
      "redeemedProceeds": "3000",
      "fillTxHashes": ["0x..."],
      "fillExplorers": ["https://shannon-explorer.somnia.network/tx/0x..."]
    }
  ]
}

GET /api/participants — the field

Outside wallets observed as maker or taker in indexed DreamDEX fills on the markets the arena tracks. Labeled external, never adopted: the response makes no inference about owner, bot status, or intent. Cached for a minute to keep indexer load bounded.

curl https://iacta.midelabs.xyz/api/participants

{
  "fetchedAt": "2026-09-05T18:57:00.000Z",
  "marketsScanned": 6,
  "tradesScanned": 213,
  "participants": [
    {
      "address": "0x...",
      "fillCount": 12,
      "marketIds": ["0x..."],
      "lastActivity": "2026-09-05T18:40:11.000Z",
      "addressExplorer": "https://shannon-explorer.somnia.network/address/0x..."
    }
  ]
}

Errors

Field	Type	Notes
503	GET /api/arena, /api/standings	Ledger unavailable. Body: {"error": "..."}.
503	GET /api/participants	Indexer feed unreachable and no cached field data.
error event	stream	Emitted once before the stream closes on a read failure.