> For the complete documentation index, see [llms.txt](https://docs.flash.trade/flash-trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.trade/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/apireference.md).

# 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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/protocolconcepts.md) and [TransactionFlow](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/transactionflow.md).

***

## Error Format

All error responses use the same JSON shape:

```json
{
  "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:

```json
{
  "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`:**

```json
{
  "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](#baskets) and [Streaming](#streaming)).

### Pools

#### `GET /v2/raw/pools`

Returns all v2 pool accounts.

**Response `200`:**

```json
[
  { "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}`](#streaming) 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`:**

```json
[
  {
    "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`:**

```json
{
  "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`:**

```json
{ "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](broken://pages/35eca89a4b4108fc2b9c662813af62f5560a6062); 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:**

```json
{
  "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](broken://pages/35eca89a4b4108fc2b9c662813af62f5560a6062). `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:**

```json
{
  "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:**

```json
{
  "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`

```json
{
  "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`

```json
{
  "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.

```json
{
  "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.

```json
{
  "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).

```json
{
  "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`

```json
{
  "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.

```json
{
  "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`

```json
{
  "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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/transactionflow.md).

### Deposit (Direct)

#### `POST /v2/transaction-builder/deposit-direct`

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/transactionflow.md).

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

```json
{
  "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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/websocketstreaming.md) 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`:

```json
{
  "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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/websocketstreaming.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flash.trade/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/apireference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.