V2 API endpoints

QuantDesk’s backend gateway exposes a V2 namespace for aggregated on-chain state and social surfaces. Field-level request and response shapes live in Swagger (/api/docs/); this page explains what each route is for and how to use it safely.

Base path

Environment	Base URL
Self-hosted / dev	`$QD_API/api/v2` (set `QD_API` to your gateway origin)
Production	`https://api.quantdesk.app/api/v2`

Legacy /api/v1 routes are deprecated for new integrations.

Authentication

Route group	Auth required
`/portfolio/*`	Yes — wallet session or Bearer token (see Authentication)
`/referrals/validate`	Yes
`/markets/orderbook/:market`	No
`/leaderboard`	No

Portfolio (unified state)

These routes return portfolio state aggregated by the backend gateway (indexed from on-chain PortfolioAccount data). For lowest latency, parse the account buffer directly via RPC.

`GET /api/v2/portfolio`

Returns the full unified portfolio: balances, positions, and open orders in one payload.

curl -s -H "Authorization: Bearer $QD_TOKEN" \
  "$QD_API/api/v2/portfolio" | jq .

Common response codes

Code	Meaning
`200`	Portfolio found
`404`	`PORTFOLIO_NOT_FOUND` — wallet has not initialized a V2 portfolio yet
`401`	Missing or expired auth

`GET /api/v2/portfolio/positions`

Positions slice only — useful when you already cache balances elsewhere.

`GET /api/v2/portfolio/orders`

Open orders slice only — pairs well with the orderbook route for depth context.

[!TIP] For sub-millisecond on-chain reads, parse the PortfolioAccount buffer directly. See Parsing the PortfolioAccount buffer.

Markets (crankless orderbook)

`GET /api/v2/markets/orderbook/:market`

Returns global BST depth for a market symbol (for example SOL-PERP).

curl -s "$QD_API/api/v2/markets/orderbook/SOL-PERP" | jq .

Response shape (conceptual)

Field	Meaning
`success`	Request succeeded
`source`	`redis` (hot path) or `supabase` (fallback snapshot)
`data`	Bid/ask levels from the on-chain slab monitor

The gateway tries Redis first for sub-millisecond delivery, then falls back to the market_orderbooks table if the cache is cold.

Markets (registry SSOT)

Epic 14 adds registry-driven market discovery. Symbols, oracle feeds, leverage caps, and session rules come from one SSOT — not scattered env keys.

Route	Purpose
`GET /markets`	List/filter by `asset_class` (`crypto`, `index`, …)
`GET /markets/asset-classes`	Per-class counts for terminal tabs
`GET /markets/:symbol`	Single market metadata
`GET /markets/leverage-tiers`	Asset-class leverage caps
`GET /markets/resolve/:symbol`	Ticker → registry symbol
`GET /markets/registry/:symbol`	Full registry row

See Perpetual market coverage.

Backtesting

Exposes the strategy simulation and backtesting lifecycle under /api/v2/backtest/* routes.

Route group	Purpose
`GET /backtest/datasets`	Dataset catalog (`dataset_id`, version)
`POST /backtest/runs`	Submit simulation job (fees/slippage/funding required)
`GET /backtest/runs/:id`	Run metrics and performance telemetry (incl. DSR)
`POST /backtest/runs/:run_id/deploy-gate/check`	Simulation gate check pass/fail
`POST /backtest/compliance/scan`	Compliance and execution check before queueing

X stream

Epic 16 social ingest — separate from news and market data.

Route	Purpose
`GET /x/feed`	Normalized posts by KOL list
`GET /x/alerts`	Symbol-linked alert events
`GET /x/context`	Social feed and context cache

See X stream and social alerts.

Data plane routes

Epic 15 adds backend-facing market data routes backed by the authoritative hub tables.

Route	Purpose
`GET /market-stats`	Snapshot of last price, 24h change, volume, OI, and TradFi `cash_open` state
`GET /candles`	Historical OHLCV for a symbol and resolution
`GET /news`	Tagged article feed filtered by symbol or source
`GET /reference/perps`	Hyperliquid / Coinalyze reference context
`GET /data-health`	Collector freshness and stale-symbol summary

Use these routes for UI hydration, operational tooling, and reproducible dataset workflows. For live UI refresh, pair GET /market-stats with the websocket event documented in WebSockets overview.

`GET /api/v2/leaderboard`

Ranks active Quant Vault leaders by realized P&L from market_maker_vaults. Query parameters:

Param	Default	Description
`limit`	`10`	Page size
`offset`	`0`	Pagination offset

curl -s "$QD_API/api/v2/leaderboard?limit=5" | jq '.data[] | {leader, total_pnl, strategy}'

Each row includes vault_address, leader, total_pnl, strategy, and is_active. When a vault leader has a published flex card, the row may also include:

Field	Meaning
`flex_card_id`	Link to verified flex card
`run_id`	Gate-verified backtest run
`badges`	Server-computed proof labels (see below)

curl -s "$QD_API/api/v2/leaderboard?limit=5" | jq '.data[] | {leader, total_pnl, badges, flex_card_id}'

Rows without flex linkage omit badges — rank alone is not verification.

Flex cards

Publish and read gate-verified backtest proof cards.

Method	Path	Auth
`POST`	`/api/v2/social/flex-cards`	Yes
`GET`	`/api/v2/social/flex-cards/:flex_card_id`	No

Publish body (conceptual)

Field	Required	Description
`run_id`	Yes	Completed backtest that passed deploy gate
`title`	Yes	Display title (max 120 chars)
`description`	No	Optional blurb

Failed gate → 403 DEPLOY_GATE_FAILED. Success → 201 with card payload including badges[].

curl -s -X POST \
  -H "Authorization: Bearer $QD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"RUN_UUID","title":"BTC MR — verified"}' \
  "$QD_API/api/v2/social/flex-cards" | jq .

Badge meanings: see Proof badges glossary and Verified flex charter.

Referrals

`POST /api/v2/referrals/validate`

Checks whether assigning a referrer would create a circular loop before you submit an on-chain SetReferrer transaction.

curl -s -X POST \
  -H "Authorization: Bearer $QD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"referrerAddress": "LEADER_WALLET_PUBKEY"}' \
  "$QD_API/api/v2/referrals/validate" | jq .

Field	Meaning
`isLoop: true`	Referral rejected — circular chain detected
`isLoop: false`	Safe to proceed on-chain

API overview — integration funnel and resilience posture
Building on QuantDesk — place_order_v2 on-chain tutorial
Errors and rate limits — V2 hardened program errors
Unified portfolio architecture — why one PDA matters

SDK & APIs

V2 API endpoints (narrative reference)

V2 API endpoints

Base path

Authentication

Portfolio (unified state)

`GET /api/v2/portfolio`

`GET /api/v2/portfolio/positions`

`GET /api/v2/portfolio/orders`

Markets (crankless orderbook)

`GET /api/v2/markets/orderbook/:market`

Markets (registry SSOT)

Backtesting

X stream

Data plane routes

`GET /api/v2/leaderboard`

Flex cards

Referrals

`POST /api/v2/referrals/validate`

​V2 API endpoints

​Base path

​Authentication

​Portfolio (unified state)

​GET /api/v2/portfolio

​GET /api/v2/portfolio/positions

​GET /api/v2/portfolio/orders

​Markets (crankless orderbook)

​GET /api/v2/markets/orderbook/:market

​Markets (registry SSOT)

​Backtesting

​X stream

​Data plane routes

​Social (flex cards and leaderboard)

​GET /api/v2/leaderboard

​Flex cards

​Referrals

​POST /api/v2/referrals/validate

​Related

V2 API endpoints

Base path

Authentication

Portfolio (unified state)

`GET /api/v2/portfolio`

`GET /api/v2/portfolio/positions`

`GET /api/v2/portfolio/orders`

Markets (crankless orderbook)

`GET /api/v2/markets/orderbook/:market`

Markets (registry SSOT)

Backtesting

X stream

Data plane routes

Social (flex cards and leaderboard)

`GET /api/v2/leaderboard`

Flex cards

Referrals

`POST /api/v2/referrals/validate`

Related