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
Local dev	`http://localhost:3002/api/v2`
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.

`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.

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

QuantDesk API overview and integration funnel WebSockets overview: Socket.IO streaming updates

​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

​Social (leaderboard)

​GET /api/v2/leaderboard

​Referrals

​POST /api/v2/referrals/validate

​Related