TransactionFlow

How to take a wallet from zero to trading on Flash Trade v2 and back out again. Every transaction-builder endpoint returns an unsigned, base64-encoded versioned transaction that you decode, sign, and submit yourself — exactly like v1. What's new in v2 is the deposit → delegate → trade → withdraw sequence, and that account/funds calls and trading calls submit to different RPC endpoints.

Overview

              ACCOUNT & FUNDS                                  TRADING
 ┌────────────────────────────────────────────┐       ┌──────────────────────────────────┐
 │ init-deposit-ledger                        │       │                                  │
 │ init-basket                                │       │                                  │
 │ deposit-direct        (move funds in)      │       │                                  │
 │ delegate-basket                            │──────►│ open / close / reverse           │
 │                                            │       │ add / remove collateral          │
 │                                            │       │ place / edit / cancel triggers   │
 │                                            │       │ place / edit / cancel limits     │
 │ request-withdrawal                         │◄──────│ (funds returned on withdrawal)   │
 │ execute-withdrawal    (recover if needed)  │       │                                  │
 └────────────────────────────────────────────┘       └──────────────────────────────────┘

• Account & funds calls: init-deposit-ledger, init-basket, deposit-direct, delegate-basket, request-withdrawal, execute-withdrawal. Sign and submit against your normal Solana RPC.

• Trading calls: all transaction-builder trading endpoints. Sign and submit against the v2 RPC endpoint.

All endpoints are under the /v2 prefix. See ApiReference for full request/response schemas.

Step 0: One-Time Account Setup

A wallet needs a deposit ledger and a basket before it can hold funds and positions. These are idempotent to build but only need to land once.

# Create the deposit ledger PDA
curl -X POST $FLASH_API_URL/v2/transaction-builder/init-deposit-ledger \
  -H 'Content-Type: application/json' \
  -d '{ "owner": "<WALLET>" }'

# Create the basket PDA
curl -X POST $FLASH_API_URL/v2/transaction-builder/init-basket \
  -H 'Content-Type: application/json' \
  -d '{ "owner": "<WALLET>" }'

Each returns { "transactionBase64": "…" }. Sign with the owner and submit to your Solana RPC.

Step 1: Deposit Funds

Move collateral from your wallet into the platform vault / deposit ledger.

curl -X POST $FLASH_API_URL/v2/transaction-builder/deposit-direct \
  -H 'Content-Type: application/json' \
  -d '{
    "owner": "<WALLET>",
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "100.0"
  }'

amount is in UI units (the server converts to native using the token's decimals, including Token-2022 scaling). The source ATA and token program (Token-2022 vs legacy SPL Token) are derived server-side from owner + tokenMint — no need to pass them.

Step 2: Delegate the Basket

Delegate the basket to enable trading.

curl -X POST $FLASH_API_URL/v2/transaction-builder/delegate-basket \
  -H 'Content-Type: application/json' \
  -d '{
    "payer": "<WALLET>",
    "owner": "<WALLET>"
  }'

After this confirms, the basket is delegated and you can trade.

Step 3: Trade

Build a trade. The request identifies the position by marketSymbol + side — no raw keys needed.

curl -X POST $FLASH_API_URL/v2/transaction-builder/open-position \
  -H 'Content-Type: application/json' \
  -d '{
    "inputTokenSymbol": "USDC",
    "outputTokenSymbol": "SOL",
    "inputAmountUi": "100.0",
    "leverage": 5.0,
    "tradeType": "LONG",
    "orderType": "MARKET",
    "owner": "<WALLET>",
    "slippagePercentage": "0.5"
  }'

The response includes the quote (leverage, entry/liq price, fees) and transactionBase64. Sign and submit to the v2 RPC.

Other trading actions follow the same pattern — see BuildTransaction:

• Close / partial close: close-position with inputUsdUi.

• Reverse: reverse-position flips to the opposite side atomically.

• Collateral: add-collateral / remove-collateral.

• Triggers: place-trigger-order, place-tp-sl, edit-trigger-order, cancel-trigger-order (pass orderId: 255 to cancel all).

• Limits: open with orderType: "LIMIT"; manage with edit-limit-order / cancel-limit-order.

Step 4: Decode, Sign, Submit

Identical mechanics to v1 — the payload is a base64 VersionedTransaction (v0).

import { VersionedTransaction, Connection, Keypair } from "@solana/web3.js";

const { transactionBase64 } = await res.json();
const tx = VersionedTransaction.deserialize(Buffer.from(transactionBase64, "base64"));

tx.sign([ownerKeypair]);

// Trades submit to the v2 RPC; account/funds ops submit to your Solana RPC.
const connection = new Connection(RPC_URL, "confirmed");
const sig = await connection.sendRawTransaction(tx.serialize());
await connection.confirmTransaction(sig, "confirmed");

Which RPC? Account & funds transactions go to your normal Solana RPC. Trading transactions must go to the v2 RPC endpoint. Submitting to the wrong endpoint will fail.

Step 5: Read Positions & Orders

Don't reconstruct state from the trade response — read it from the basket snapshot.

# One-shot
curl $FLASH_API_URL/v2/owner/<WALLET>

Or subscribe to the live WebSocket for basket (full state) and metrics (PnL/leverage/liq ticks) messages — see WebSocketStreaming. Decode the basketData bytes via the v2 client SDK; use positionMetrics / orderMetrics for UI-ready strings.

Step 6: Withdraw

Withdrawals are two-step (see ProtocolConcepts → Withdrawals).

# Step 1 — request. Starts the withdrawal and creates your receiving ATA.
# Defaults to including custody settlement.
curl -X POST $FLASH_API_URL/v2/transaction-builder/request-withdrawal \
  -H 'Content-Type: application/json' \
  -d '{
    "owner": "<WALLET>",
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "12.5",
    "includeCustodySettlement": true
  }'

After submitting Phase 1:

1. Poll until the withdrawal escrow account closes — that means funds landed in your receiving ATA.

2. For SOL, unwrap the WSOL ATA back to native SOL.

If the withdrawal doesn't complete automatically, recover with Step 2:

curl -X POST $FLASH_API_URL/v2/transaction-builder/execute-withdrawal \
  -H 'Content-Type: application/json' \
  -d '{
    "owner": "<WALLET>",
    "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "includeCustodySettlement": true
  }'

execute-withdrawal finishes the withdrawal in a single transaction and closes the escrow.

includeCustodySettlement. Set true (default) when the custody settlement receipt isn't already on-chain — the builder prepends the settlement instruction so the withdrawal succeeds. If a prior step already created/settled the receipt, set false to avoid a duplicate. When recovering with execute-withdrawal, set it based on whether the settlement receipt is still present and owned by the program.

Preview-Only Mode

open-position builds a quote without a transaction when you omit owner (transactionBase64 comes back null).

Blockhash Expiry

Built transactions embed a recent blockhash that expires in ~45s. If you hit "Blockhash not found / expired," re-call the builder to get a fresh transaction, then sign and submit immediately. The v2 trading endpoints proactively refresh the blockhash between calls so back-to-back builds don't collide.

Error Handling

• HTTP-level failures return { "error": "…" } (e.g. 400 invalid pubkey, 404 unknown market/symbol, 500 blockhash fetch failed).

• Trading compute failures come back 200 with { "err": "…" } in the body — always check for it.

• Trigger/limit builder validation failures return 400 { "error": "…" }.

See ErrorReference for the full matrix and recovery patterns.

Key Notes

• Two RPCs. Account & funds ops → Solana RPC. Trades → v2 RPC.

• Set up once. init-deposit-ledger, init-basket, delegate-basket are one-time per wallet (until you undelegate/withdraw fully).

• Positions live in the basket. Always read state via /v2/owner/{owner} or the WS — not from the trade response.

• UI vs native units. deposit-direct and request-withdrawal take UI amounts (server converts). Trading endpoints take UI amounts/prices throughout.