> 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/protocolconcepts.md).

# ProtocolConcepts

Flash Trade **v2** uses the same trading mechanics as [v1](broken://pages/5898f32f96bbe05db541a0ff287425c4174e16e6) (pool-to-peer, oracle pricing, leverage, fees, TP/SL, limit orders). What changes for an integrator is **where positions are stored** and **how funds move in and out**. This page covers the v2-specific concepts you need before calling the API.

## Two Kinds of Calls

The v2 API has two groups of endpoints:

* **Account & funds endpoints** (`init-*`, `deposit-direct`, `delegate-basket`, `request-withdrawal`, `execute-withdrawal`) — set up your wallet and move collateral in and out.
* **Trading endpoints** — open, close, and manage positions and orders (fast and gasless).

Each returns an unsigned transaction you sign and submit. The two groups submit to different RPC endpoints — see [TransactionFlow](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/transactionflow.md).

## Key Entities

### Basket

The defining difference from v1. Each wallet has a single **Basket** PDA that holds **all** of its v2 positions and orders — one position per market. There are no standalone Position or Order accounts.

Because of this, the API identifies a position by a friendly tuple — `(owner, marketSymbol, side)` — and resolves the underlying market pubkey internally. Each market is one side (long and short are separate markets), so a wallet can hold one long and one short per symbol, and `(marketSymbol, side)` is always unambiguous.

The basket must be **delegated** before trading. The snapshot and WebSocket endpoints return the basket's positions and orders already decoded as `positionMetrics` / `orderMetrics` (UI-ready strings) — use those directly. The raw basket bytes are also included (base64) for clients that prefer to decode native `PositionMeta[]` / `OrderMeta[]` with the v2 client SDK.

### Deposit Ledger

A per-owner PDA that tracks a wallet's deposited balances available as collateral. Funds enter via `deposit-direct` and are drawn down when opening positions / adding collateral.

### Custody & Platform Vault

As in v1, each token has a **custody** that holds pooled liquidity. v2 additionally uses a **platform vault** per mint (the token account that deposits land in and withdrawals are paid from) and a **custody settlement receipt** used to reconcile custody ↔ vault balances during withdrawals (see [Withdrawal Lifecycle](#withdrawal-lifecycle)).

### Market

Same as v1: a `(target custody, lock/collateral custody, side)` triple. The backend resolves market pubkeys from `marketSymbol` + `side` against the live pool config.

## Account Lifecycle

A wallet must be set up once before it can trade:

```
init-deposit-ledger   ─┐
init-basket           ─┼─ one-time setup
deposit-direct        ─┘
delegate-basket       ─── enable trading
   │
   ▼
open/close/reverse, collateral, trigger & limit orders   (fast, gasless)
   │
   ▼
request-withdrawal    ─── pull funds back out
```

See [TransactionFlow](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/transactionflow.md) for the full request/response sequence.

## Delegation

`delegate-basket` is a one-time step that enables trading on your basket.

## Withdrawals

Withdrawals happen in **two steps**:

1. **`request-withdrawal`** — starts the withdrawal and idempotently creates the owner's receiving ATA.
2. Funds are released automatically into the owner's ATA. Poll until the **withdrawal escrow account closes** — that means the withdrawal completed.

If the withdrawal doesn't complete automatically, **`execute-withdrawal`** finishes it in a single transaction (optionally including the custody settlement via `includeCustodySettlement`).

For SOL, the receiving token is WSOL; unwrap the WSOL ATA back to native SOL after the withdrawal completes.

## Pricing & Markets

v2 uses the same Pyth Lazer feeds as v1, filtered to the tokens in the v2 pool config — notably equity tokens (e.g. SPY, MSTR, CRCL) that trade on market hours. The `/v2/prices` payload includes a `marketSession` field so clients can reflect open/closed equity sessions.

## Program IDs

| Component            | Pubkey                                         |
| -------------------- | ---------------------------------------------- |
| v2 program (mainnet) | `FTv2RxXarPfNta45HTTMVaGvjzsGg27FXJ3hEKWBhrzV` |
| v2 program (devnet)  | `FMTgsEDaPPfJi1PKD67McLTC5n833T4irbBP53LLxtvj` |

## Differences from v1 at a Glance

| Concept           | v1                              | v2                                                  |
| ----------------- | ------------------------------- | --------------------------------------------------- |
| Position storage  | Standalone Position accounts    | Stored in a per-owner **Basket** (one per market)   |
| Order storage     | Standalone Order accounts       | Stored in the Basket                                |
| Position identity | Position PDA / raw keys         | `(owner, marketSymbol, side)` tuple                 |
| Funds movement    | Direct                          | deposit → delegate → trade → withdraw lifecycle     |
| Swaps             | Supported (`SWAP`)              | Not supported                                       |
| Streaming         | `positions` + `orders` messages | `basket` + `metrics` messages (decode basket bytes) |


---

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