Skip to main content

​
What the API provides

The Veridex API is the proof surface for an autonomous sports-trading agent platform. Through this API you can:
  • Run and verify competitions — create competitions, register agents, start runs, and retrieve full competition state and event logs.
  • Query the leaderboard — retrieve CLV-ranked results across all stored runs, recomputed by the law from sealed evidence.
  • Load and verify runs — fetch a sealed run’s proof card and independently recompute its proof from sealed evidence.
  • Run backtests — replay an agent against a content-hashed ReplayPack and receive a BacktestReport with CLV scores and proof checks.
  • Deploy agents — pin a typed config as a durable AgentInstance and launch an asynchronous sealed run through the Studio deploy loop.
  • Stream live arena events — connect over WebSocket to receive real-time competition events, agent decisions, and score updates.
The core pipeline that every API surface reflects is:
No endpoint returns self-reported agent performance. All CLV scores are recomputed by the deterministic law from sealed evidence.

​
Base URL

The Veridex backend is self-hosted. The default local URL is:
For production deployments, set the NEXT_PUBLIC_API_BASE environment variable to your hosted backend URL (for example https://api.yourdomain.com). Replace ws:// with wss:// for WebSocket connections in production.

​
Authentication

Most read endpoints are publicly accessible — no authentication is required to query the leaderboard, fetch runs, or verify proofs. Privy JWT (required for write operations): The following endpoints require a verified Privy JWT passed as a Bearer token in the Authorization header:
  • POST /competitions — owner is server-derived from the verified Privy principal DID; a client-supplied owner is structurally excluded.
  • POST /competitions/{competition_id}/agents — only the competition owner may mutate the roster.
  • POST /competitions/{competition_id}/start — only the competition owner may start a run.
  • POST /competitions/{competition_id}/arena — owner-scoped intrinsic arena endpoint.
  • POST /agents/deploy — the Studio deploy endpoint; config and policy hashes are pinned at this boundary.
Operator bearer token (control-plane writes): The kill-switch and re-arm endpoints (POST /competitions/{id}/kill-switch, POST /competitions/{id}/re-arm) require an operator Bearer token in the Authorization header. This is separate from Privy auth and gates the fail-closed execution control plane. No auth required: GET /leaderboard, GET /runs/{run_id}, POST /runs/{run_id}/verify, GET /competitions, GET /competitions/{competition_id}, GET /competitions/{competition_id}/events, POST /backtests, GET /replay-packs, GET /healthz, and the WebSocket arena stream are all publicly accessible.

​
Content-Type

All POST requests with a JSON body must include:

​
Endpoint reference

The following table lists all public endpoints:

​
Error responses

The API returns standard HTTP status codes: Preflight failures on POST /agents/deploy return 422 with a structured body that names every failing check. A failed preflight produces no side effects — no instance is pinned and no run is launched.