ApiReference

REST + WebSocket API for the Flash Trade v2 perpetuals engine — the same Flash perpetuals model with near-instant, gasless trade execution. All endpoints are under the /v2 path prefix.

How v2 differs from v1. v2 positions and orders live inside a single per-owner Basket account (one position per market) instead of standalone Position/Order accounts. You identify a position with a friendly (owner, marketSymbol, side) tuple — the backend resolves market pubkeys for you. Funds move through a deposit → delegate → trade → withdraw lifecycle. See ProtocolConcepts and TransactionFlow.

---

Error Format

All error responses use the same JSON shape:

{
  "error": "descriptive error message"
}

Trading endpoints that compute a quote return errors inside the response body under err (HTTP 200) when the computation fails but the request was well-formed:

{
  "err": "Computation failed — check symbols, prices, and account data"
}

Trigger-order / limit-order builder endpoints return validation failures as HTTP 400 with { "error": "…" }.

HTTP Status Codes

Code	Meaning
200	Success
101	WebSocket upgrade
400	Bad request / validation error / invalid pubkey
404	Resource not found (account, price symbol, pool)
429	Too many requests (per-owner WebSocket limit)
500	Internal server error / compute error / blockhash fetch failed
503	Service unavailable (price missing, global connection limit)

---

Health

GET /v2/health

Returns v2 service status, cached account counts, and the live pool-config provenance.

Response 200:

{
  "status": "ok",
  "accounts": {
    "pools": 1,
    "custodies": 6,
    "markets": 8,
    "baskets": 1200,
    "deposit_ledgers": 1300
  },
  "config": {
    "source": "cdn",
    "version": "5864c583de7b9d17c5571c53cd679f572b340dad",
    "env": "mainnet",
    "branch": "main",
    "publishedAt": "2026-06-03T10:00:00Z",
    "loadedAtUnix": 1717407600,
    "pools": 1,
    "markets": 8,
    "tokens": 6
  }
}

---

Raw Accounts

These endpoints return raw Anchor-deserialized on-chain account data as JSON. The shapes mirror the v2 Anchor IDL structs and are not documented field-by-field here — see the v2 program IDL for exact definitions.

v2 has no /raw/perpetuals (no perpetuals account) and no /raw/positions or /raw/orders — positions and orders are held inside the per-owner Basket (see Baskets and Streaming).

Pools

GET /v2/raw/pools

Returns all v2 pool accounts.

Response 200:

[
  { "pubkey": "…", "account": { /* raw Anchor-deserialized pool account */ } }
]

GET /v2/raw/pools/{pubkey}

Parameter	In	Type	Required	Description
pubkey	path	string	yes	Pool account public key (base58)

Response 200: Raw pool account JSON. Response 404: { "error": "pool … not found" }

Custodies

GET /v2/raw/custodies

Returns all custody accounts.

GET /v2/raw/custodies/{pubkey}

Parameter	In	Type	Required	Description
pubkey	path	string	yes	Custody account public key (base58)

Markets

GET /v2/raw/markets

Returns all market accounts.

GET /v2/raw/markets/{pubkey}

Parameter	In	Type	Required	Description
pubkey	path	string	yes	Market account public key (base58)

Baskets

GET /v2/raw/baskets/{pubkey}

Returns a single raw basket account — the per-owner account that holds all of a wallet's v2 positions and orders. Most integrators should use the decoded GET /v2/owner/{owner} snapshot instead.

Parameter	In	Type	Required	Description
pubkey	path	string	yes	Basket account public key (base58)

Response 200: Raw basket account JSON. Response 404: { "error": "basket … not found" }

---

Tokens

GET /v2/tokens

Returns all supported v2 tokens (deduplicated across pools).

Response 200:

[
  {
    "symbol": "SPY",
    "mintKey": "…",
    "decimals": 6,
    "isStable": false,
    "isVirtual": false,
    "lazerId": 128,
    "pythTicker": "SPY/USD",
    "isToken2022": true
  }
]

---

Prices

Real-time prices sourced from Pyth Lazer, filtered to the tokens present in the v2 pool config (e.g. equity tokens like SPY, MSTR, CRCL).

GET /v2/prices

Returns a map of symbol → price for all v2 tokens.

Response 200:

{
  "SPY": {
    "price": 54812000000,
    "exponent": -8,
    "confidence": 0,
    "priceUi": 548.12,
    "timestampUs": 1717407600000000,
    "marketSession": "open"
  }
}

Field	Type	Description
price	number	Raw integer price (apply exponent)
exponent	number	Power-of-ten exponent (e.g. -8)
confidence	number	Always 0 for Pyth Lazer spot prices
priceUi	number	Convenience price × 10^exponent
timestampUs	number	Price timestamp in microseconds
marketSession	string	"open", "closed", etc. — relevant for equity hours

GET /v2/prices/{symbol}

Parameter	In	Type	Required	Description
symbol	path	string	yes	Token symbol (e.g. SPY, MSTR)

Response 200: A single MbPriceResponse (shape above). Response 404: symbol not in the v2 config, or no price yet.

---

Pool Data

Aggregated, cached pool statistics (TVL, utilization, LP price, per-custody and per-market caps).

GET /v2/pool-data

Returns statistics for all v2 pools.

Response 200:

{ "pools": [ { /* pool stats */ } ] }

When the cache hasn't populated yet, returns { "pools": [] }.

GET /v2/pool-data/{pool_pubkey}

Parameter	In	Type	Required	Description
pool_pubkey	path	string	yes	Pool account pubkey

Response 200: Single pool statistics object. Response 404: unknown pool pubkey.

---

Transaction Builder — Trading

All transaction-builder endpoints return a base64-encoded versioned Solana transaction (unsigned). The client signs and submits.

Trading responses reuse the same response DTOs as v1 (OpenPositionResponseDto, ClosePositionResponseDto, etc.). The field meanings are identical to v1 ApiReference; only the request shape changes (friendly marketSymbol + side instead of raw keys).

Open Position

POST /v2/transaction-builder/open-position

Opens a new position or increases an existing one. Supports market and limit orders and optional TP/SL attachment. Omit owner for preview-only mode (response has transactionBase64: null).

Request body:

{
  "inputTokenSymbol": "USDC",
  "outputTokenSymbol": "SOL",
  "inputAmountUi": "100.0",
  "leverage": 5.0,
  "tradeType": "LONG",
  "orderType": "MARKET",
  "limitPrice": "150.00",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "slippagePercentage": "0.5",
  "takeProfit": "160.00",
  "stopLoss": "130.00"
}

Field	Type	Required	Description
inputTokenSymbol	string	yes	Collateral token symbol (e.g. USDC, SOL)
outputTokenSymbol	string	yes	Target market token symbol (e.g. SOL, BTC)
inputAmountUi	string	yes	Input amount, human-readable
leverage	number	yes	Desired leverage multiplier
tradeType	enum	yes	"LONG" or "SHORT" (SWAP is not supported on v2)
orderType	enum	no	"MARKET" (default) or "LIMIT"
limitPrice	string	no	Trigger price for limit orders (UI format)
owner	string	no	Wallet pubkey. Omit for preview-only mode
slippagePercentage	string	no	Slippage tolerance % (default "0.5")
takeProfit	string	no	TP trigger price (UI). Appends a TP trigger instruction
stopLoss	string	no	SL trigger price (UI). Appends an SL trigger instruction

Response 200: OpenPositionResponseDto — same shape as v1 open-position. transactionBase64 is null in preview-only mode; takeProfitQuote / stopLossQuote are present when takeProfit/stopLoss are supplied.

Limit orders: placing a limit order is done through this endpoint with orderType: "LIMIT" + limitPrice. Editing/cancelling limit orders uses the dedicated endpoints below.

Close Position

POST /v2/transaction-builder/close-position

Closes a position fully or partially.

Request body:

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "inputUsdUi": "500.00",
  "withdrawTokenSymbol": "USDC",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "slippagePercentage": "0.5"
}

Field	Type	Required	Description
marketSymbol	string	yes	Target market token symbol
side	enum	yes	"LONG" or "SHORT" — selects which position to close
inputUsdUi	string	yes	USD amount to close (full size = full close; less = partial)
withdrawTokenSymbol	string	yes	Token to withdraw into (display hint; actual = collateral custody)
owner	string	yes	Owner wallet pubkey
slippagePercentage	string	no	Slippage tolerance % (default "0.5")

Response 200: ClosePositionResponseDto (same shape as v1 close-position).

Reverse Position

POST /v2/transaction-builder/reverse-position

Atomically closes the current position and opens an equal-leverage position on the opposite side in a single transaction. Close proceeds settle into the opposite side's collateral custody; a 2% haircut absorbs price drift between quote and execution.

Request body:

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "leverage": 5.0,
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "slippagePercentage": "0.5"
}

Field	Type	Required	Description
marketSymbol	string	yes	Target market token symbol
side	enum	yes	Current side. The new position is the opposite
leverage	number	yes	Leverage for the new (opposite-side) position
owner	string	yes	Owner wallet pubkey
slippagePercentage	string	no	Slippage tolerance % (default "0.5")

Response 200: ReversePositionResponseDto (combined close+open quote + unsigned tx).

---

Transaction Builder — Collateral

Add Collateral

POST /v2/transaction-builder/add-collateral

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "depositAmountUi": "50.0",
  "depositTokenSymbol": "USDC",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "slippagePercentage": "0.5"
}

Field	Type	Required	Description
marketSymbol	string	yes	Market token symbol
side	enum	yes	"LONG" or "SHORT"
depositAmountUi	string	yes	Amount to add (in deposit token)
depositTokenSymbol	string	yes	Deposit token symbol
owner	string	yes	Owner wallet pubkey
slippagePercentage	string	no	Slippage tolerance % (default 0.5)

Response 200: AddCollateralResponseDto.

Remove Collateral

POST /v2/transaction-builder/remove-collateral

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "withdrawAmountUsdUi": "25.00",
  "withdrawTokenSymbol": "USDC",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "slippagePercentage": "0.5"
}

Field	Type	Required	Description
marketSymbol	string	yes	Market token symbol
side	enum	yes	"LONG" or "SHORT"
withdrawAmountUsdUi	string	yes	USD amount of collateral to remove
withdrawTokenSymbol	string	yes	Token to receive (display hint)
owner	string	yes	Owner wallet pubkey
slippagePercentage	string	no	Slippage tolerance % (default 0.5)

Response 200: RemoveCollateralResponseDto.

---

Transaction Builder — Trigger & Limit Orders

These endpoints return { "transactionBase64": "…" } on success and 400 { "error": "…" } on validation failure.

Place Trigger Order

POST /v2/transaction-builder/place-trigger-order

Places a single TP or SL trigger order on an existing position.

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "triggerPriceUi": "160.00",
  "sizeAmountUi": "0.5",
  "isStopLoss": false,
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

Field	Type	Required	Description
marketSymbol	string	yes	Market token symbol
side	enum	yes	"LONG" or "SHORT"
triggerPriceUi	string	yes	Trigger price (UI)
sizeAmountUi	string	yes	Delta size to close when triggered (UI)
isStopLoss	boolean	yes	true = stop-loss, false = take-profit
owner	string	yes	Owner wallet pubkey

Place TP/SL (atomic)

POST /v2/transaction-builder/place-tp-sl

Places a take-profit and/or stop-loss in one transaction.

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "takeProfitUi": "160.00",
  "stopLossUi": "140.00",
  "sizeAmountUi": "0.5",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

takeProfitUi and stopLossUi are each optional — supply one or both. sizeAmountUi is the close size used for whichever trigger(s) are included.

Edit Trigger Order

POST /v2/transaction-builder/edit-trigger-order

Replaces both the trigger price and close size of an existing trigger order (no "keep existing" semantics — supply both).

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "orderId": 0,
  "isStopLoss": false,
  "triggerPriceUi": "170.00",
  "sizeAmountUi": "0.5",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

Field	Type	Required	Description
orderId	number	yes	Slot index of the trigger order (0–4)
isStopLoss	boolean	yes	true for an SL slot, false for TP
triggerPriceUi	string	yes	New trigger price (UI)
sizeAmountUi	string	yes	New close size (UI)

Cancel Trigger Order

POST /v2/transaction-builder/cancel-trigger-order

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "orderId": 0,
  "isStopLoss": false,
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

orderId is the slot to cancel (0–4). Pass 255 to cancel all trigger orders for this market+side.

Edit Limit Order

POST /v2/transaction-builder/edit-limit-order

Edit a limit order's price, size, TP, or SL. Per on-chain semantics: for limitPriceUi and sizeAmountUi, omit (or send "0") to keep existing. TP and SL do not persist across an edit — send takeProfitUi/stopLossUi to set them; "0" or omitting them removes them. To keep an existing TP/SL, re-send its current value.

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "orderId": 0,
  "limitPriceUi": "150.00",
  "sizeAmountUi": "0.5",
  "takeProfitUi": "160.00",
  "stopLossUi": "140.00",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

Field	Type	Required	Description
orderId	number	yes	Slot index of the limit order (0–4)
limitPriceUi	string	no	New limit price (UI). Omit to keep
sizeAmountUi	string	no	New size (UI). Omit to keep
takeProfitUi	string	no	New TP (UI). Sets the TP; "0"/omit removes it (re-send to keep)
stopLossUi	string	no	New SL (UI). Sets the SL; "0"/omit removes it (re-send to keep)

Cancel Limit Order

POST /v2/transaction-builder/cancel-limit-order

{
  "marketSymbol": "SOL",
  "side": "LONG",
  "orderId": 0,
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

Cancels the limit order at orderId (0–4), returning reserved collateral and freeing the slot.

---

Transaction Builder — Account Setup & Funds

These transactions submit to your Solana RPC. Each returns { "transactionBase64": "…" }. The typical first-time lifecycle is: init-deposit-ledger → init-basket → deposit-direct → delegate-basket → trade. See TransactionFlow.

Deposit (Direct)

POST /v2/transaction-builder/deposit-direct

Transfers tokens from the owner into the platform vault / deposit ledger.

{
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "100.0"
}

Field	Type	Required	Description
owner	string	yes	Owner wallet pubkey
tokenMint	string	yes	SPL mint of the deposited token
amount	string	yes	Amount in UI units (converted server-side)

The source token account and token program are derived server-side from owner + tokenMint: funds are pulled from the owner's associated token account (ATA) for the mint, and the correct token program (Token-2022 vs legacy SPL Token) is resolved from the pool config.

Init Basket

POST /v2/transaction-builder/init-basket

Creates the owner's Basket PDA. { "owner": "…" } → { "transactionBase64": "…" }.

Init Deposit Ledger

POST /v2/transaction-builder/init-deposit-ledger

Creates the owner's deposit-ledger PDA. { "owner": "…" } → { "transactionBase64": "…" }.

Delegate Basket

POST /v2/transaction-builder/delegate-basket

Delegates the owner's basket so it can be traded.

{
  "payer": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}

Field	Type	Required	Description
payer	string	yes	Fee payer
owner	string	yes	Basket owner

Request Withdrawal

POST /v2/transaction-builder/request-withdrawal

Starts a withdrawal and releases the funds. Built as one transaction whose first instruction idempotently creates the owner's receiving ATA.

{
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "12.5",
  "includeCustodySettlement": true
}

Field	Type	Required	Description
owner	string	yes	Owner wallet pubkey (fee payer)
tokenMint	string	yes	Mint of the token to withdraw
amount	string	yes	Amount in UI units
includeCustodySettlement	boolean	no	Prepend a custody-settlement request when the settlement receipt is missing (default true)

After submitting, poll until the withdrawal escrow closes (which completes the transfer). For SOL, unwrap the WSOL ATA afterward. See TransactionFlow → Withdrawals.

Execute Withdrawal (resume/recover)

POST /v2/transaction-builder/execute-withdrawal

Finishes the withdrawal in a single transaction — used to recover a withdrawal that didn't complete automatically. Transfers escrowed funds to the owner and closes the escrow.

{
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "includeCustodySettlement": true
}

Field	Type	Required	Description
owner	string	yes	Owner wallet pubkey
tokenMint	string	yes	Mint of the token to withdraw
includeCustodySettlement	boolean	no	Prepend a custody-settlement execution when the settlement receipt is still on-chain (default true)

---

Streaming

v2 exposes a wallet's positions and orders as a single basket snapshot, available as a one-shot HTTP fetch or a live WebSocket. See WebSocketStreaming for the message protocol and field-level detail.

GET /v2/owner/{owner}

One-shot fetch of the same payload streamed over the WebSocket.

Parameter	In	Type	Required	Description
owner	path	string	yes	Owner wallet pubkey

Response 200: MbBasketSnapshotDto:

{
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb",
  "basketPubkey": "…",
  "basketData": "base64-encoded-raw-basket-bytes…",
  "positionMetrics": { "<marketPubkey>": { /* MbPositionMetricsDto */ } },
  "orderMetrics": { "<marketPubkey>": { /* MbOrderMetricsDto */ } }
}

Decode basketData with the v2 client SDK to get native PositionMeta[] / OrderMeta[]; use positionMetrics / orderMetrics for UI-ready strings (PnL, leverage, formatted prices).

GET /v2/owner/{owner}/ws

WebSocket stream of the owner's basket. See WebSocketStreaming.

Parameter	In	Type	Required	Description
owner	path	string	yes	Owner wallet pubkey
updateIntervalMs	query	number	no	Metrics refresh interval in ms (default 1000, min 100, max 10000)

---

Enum Reference

TradeType

Serialized SCREAMING_SNAKE_CASE. Note: SWAP is not supported on v2.

Value	Description
LONG	Long position
SHORT	Short position

OrderType

Value	Description
MARKET	Market order (executes immediately)
LIMIT	Limit order (executes at trigger price)

---

Quick Reference: All v2 Endpoints

Method	Path	Tag
GET	/v2/health	V2 Health
GET	/v2/raw/pools	V2 Raw Accounts
GET	/v2/raw/pools/{pubkey}	V2 Raw Accounts
GET	/v2/raw/custodies	V2 Raw Accounts
GET	/v2/raw/custodies/{pubkey}	V2 Raw Accounts
GET	/v2/raw/markets	V2 Raw Accounts
GET	/v2/raw/markets/{pubkey}	V2 Raw Accounts
GET	/v2/raw/baskets/{pubkey}	V2 Raw Accounts
GET	/v2/tokens	V2 Tokens
GET	/v2/prices	V2 Prices
GET	/v2/prices/{symbol}	V2 Prices
GET	/v2/pool-data	V2 Pool Data
GET	/v2/pool-data/{pool_pubkey}	V2 Pool Data
POST	/v2/transaction-builder/open-position	V2 Trading
POST	/v2/transaction-builder/close-position	V2 Trading
POST	/v2/transaction-builder/reverse-position	V2 Trading
POST	/v2/transaction-builder/add-collateral	V2 Collateral
POST	/v2/transaction-builder/remove-collateral	V2 Collateral
POST	/v2/transaction-builder/place-trigger-order	V2 Trigger Orders
POST	/v2/transaction-builder/place-tp-sl	V2 Trigger Orders
POST	/v2/transaction-builder/edit-trigger-order	V2 Trigger Orders
POST	/v2/transaction-builder/cancel-trigger-order	V2 Trigger Orders
POST	/v2/transaction-builder/edit-limit-order	V2 Trigger Orders
POST	/v2/transaction-builder/cancel-limit-order	V2 Trigger Orders
POST	/v2/transaction-builder/deposit-direct	V2 Account Setup
POST	/v2/transaction-builder/init-basket	V2 Account Setup
POST	/v2/transaction-builder/init-deposit-ledger	V2 Account Setup
POST	/v2/transaction-builder/delegate-basket	V2 Account Setup
POST	/v2/transaction-builder/request-withdrawal	V2 Account Setup
POST	/v2/transaction-builder/execute-withdrawal	V2 Account Setup
GET	/v2/owner/{owner}	V2 Streaming
GET	/v2/owner/{owner}/ws	V2 Streaming