# SKILL

Flash Trade is a pool-to-peer perpetual futures DEX on Solana. Up to 100x leverage (500x Degen Mode), Pyth oracle pricing, virtual asset support (forex, commodities, equities).

**Program ID (Mainnet):** `FLASH6Lo6h3iasJKWDs2F8TkW2UKf3s15C8PMGuVfgBn`\
**Program ID (Devnet):** `FTPP4jEWW1n8s2FEccwVfS9KCPjpndaswg7Nkkuz4ER4`

## Integration Surfaces (Choose Your Path)

| Surface            | Best For                                 | Language    | Complexity |
| ------------------ | ---------------------------------------- | ----------- | ---------- |
| **REST API**       | Apps, bots, dashboards, any language     | Any (HTTP)  | Low        |
| **WebSocket**      | Real-time position/order/price feeds     | Any (WS)    | Low        |
| **MCP Server**     | AI agent integrations                    | MCP clients | Low        |
| **TypeScript SDK** | Direct on-chain control, custom programs | TypeScript  | High       |

## Quick Start (REST API)

```bash
# Set your API base URL
export FLASH_API_URL="https://flashapi.trade"

# Get all markets
curl $FLASH_API_URL/raw/markets

# Get current prices
curl $FLASH_API_URL/prices

# Get wallet positions (enriched with PnL)
curl $FLASH_API_URL/positions/owner/<WALLET_PUBKEY>

# Open position (returns preview + unsigned transaction)
curl -X POST $FLASH_API_URL/transaction-builder/open-position \
  -H "Content-Type: application/json" \
  -d '{
    "inputTokenSymbol": "USDC",
    "outputTokenSymbol": "SOL",
    "inputAmountUi": "100.0",
    "leverage": 5.0,
    "tradeType": "LONG",
    "owner": "<WALLET_PUBKEY>"
  }'
```

## Intent Router

| Intent                        | REST API Path                                               | SDK Method                              | Reference                                                                               |
| ----------------------------- | ----------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| List markets/pools/custodies  | `GET /raw/markets`                                          | `PoolConfig.fromIdsByName()`            | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Get oracle prices             | `GET /prices`                                               | `ViewHelper.getOraclePrice()`           | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Get wallet positions + PnL    | `GET /positions/owner/{owner}`                              | `ViewHelper.getPositionData()`          | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Get wallet orders             | `GET /orders/owner/{owner}`                                 | —                                       | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Open position                 | `POST /transaction-builder/open-position`                   | `client.openPosition()`                 | [TransactionFlow](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)    |
| Close position                | `POST /transaction-builder/close-position`                  | `client.closePosition()`                | [TransactionFlow](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)    |
| Reverse position              | `POST /transaction-builder/reverse-position`                | —                                       | [TransactionFlow](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)    |
| Add/remove collateral         | `POST /transaction-builder/add-collateral`                  | `client.addCollateral()`                | [TransactionFlow](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)    |
| Place TP/SL                   | `POST /transaction-builder/place-trigger-order`             | `client.placeTriggerOrder()`            | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Place limit order             | `POST /transaction-builder/open-position` (orderType=LIMIT) | `client.placeLimitOrder()`              | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Preview fees/PnL              | `POST /preview/*`                                           | `ViewHelper.*`                          | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| Stream positions live         | `WS /owner/{owner}/ws`                                      | —                                       | [WebSocketStreaming](https://docs.flash.trade/flash-trade/flash-trade/broken-reference) |
| Pool stats (AUM, utilization) | `GET /pool-data`                                            | `ViewHelper.getAssetsUnderManagement()` | [ApiReference](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       |
| AI agent integration          | MCP tools                                                   | —                                       | [McpIntegration](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)     |

## Critical Rules

* **Minimum collateral >$10 after fees** for limit orders, TP, and SL. Use $11-12+ when TP/SL is needed.
* **Blockhash expiry \~60s** — sign and submit transactions promptly after building.
* **SOL positions use JitoSOL** as underlying collateral on-chain.
* **Pyth prices are mainnet only** — devnet returns stale/zero.
* **Max 5 trigger orders** (TP or SL) per market position.
* **All amounts are UI format** (human-readable, e.g., "100.0") in API requests.
* **No authentication required** — API is public. WebSocket has per-owner connection limits (5).
* **One position per market per side per wallet.** Multiple orders for the same market+side merge into one position — you cannot hold independent positions at different entry prices.
* **Wallet balances not available via Flash Trade API** — use Solana RPC `getTokenAccountsByOwner` to check balances before building transactions.

## REST API Scope

The REST API covers **trading operations only**:

* Positions: open, close, reverse
* Collateral: add, remove
* Trigger orders: place, edit, cancel TP/SL
* Previews: fees, margin, TP/SL projections
* Data: markets, pools, prices, positions, orders, pool stats

**Not available via REST API (requires** [**TypeScript SDK**](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)**):**

* LP operations (add/remove liquidity, compounding)
* FLP staking (deposit, unstake, collect rewards)
* FLASH token staking
* Limit order edit/cancel (SDK uses `editLimitOrder` with `sizeAmount=0` to cancel)

**Implicit operations via REST (no dedicated endpoint):**

* **Increase size:** Call `open-position` on a market where you already have a position — the API detects the existing position and calls `increaseSize` internally.
* **Decrease size:** Call `close-position` with a partial `inputUsdUi` amount — the API calls `decreaseSize` internally.
* **Place limit order:** Call `open-position` with `orderType: "LIMIT"` and `limitPrice` — the API builds a `placeLimitOrder` instruction.

## Workflow Routing

| Workflow             | Trigger                                                              | File                            |
| -------------------- | -------------------------------------------------------------------- | ------------------------------- |
| **SetupIntegration** | Getting started, setup, connect, configure                           | `Workflows/SetupIntegration.md` |
| **QueryData**        | Read markets, positions, prices, orders, pool data                   | `Workflows/QueryData.md`        |
| **BuildTransaction** | Open, close, reverse position, add/remove collateral, trigger orders | `Workflows/BuildTransaction.md` |
| **ManagePositions**  | Position lifecycle, monitoring, TP/SL management, risk               | `Workflows/ManagePositions.md`  |

## Documentation Map

| File                                                                                       | Content                                                       |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| [ApiReference.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       | Complete REST API — all endpoints, request/response DTOs      |
| [TransactionFlow.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)    | Build → sign → submit lifecycle with multi-language examples  |
| [WebSocketStreaming.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference) | Real-time WebSocket streaming                                 |
| [McpIntegration.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)     | AI agent integration via MCP server                           |
| [SdkReference.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)       | TypeScript SDK (advanced, direct on-chain)                    |
| [ProtocolConcepts.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)   | Domain knowledge — pools, markets, fees, leverage, degen mode |
| [ErrorReference.md](https://docs.flash.trade/flash-trade/flash-trade/broken-reference)     | All 69 error codes with solutions                             |

**Templates & Examples:**

* [templates/api-trading-bot.py](https://docs.flash.trade/flash-trade/flash-trade/broken-reference) — Production Python trading bot (REST API)
* [examples/api-quickstart/](https://docs.flash.trade/flash-trade/flash-trade/broken-reference) — Quick start in cURL, TypeScript, Python
* [examples/websocket-bot/](https://docs.flash.trade/flash-trade/flash-trade/broken-reference) — Real-time position monitor (TypeScript + Python)

## Examples

**Example 1: Build a trading bot (REST API)**

```
User: "Build a Python bot that monitors SOL price and opens a long when it dips below $140"
→ Invokes SetupIntegration workflow (API setup)
→ Invokes QueryData workflow (price polling)
→ Invokes BuildTransaction workflow (open position)
→ References: ApiReference.md, TransactionFlow.md
```

**Example 2: Real-time position dashboard**

```
User: "Create a dashboard showing all my positions with live PnL"
→ Invokes QueryData workflow (get positions)
→ References: WebSocketStreaming.md (live updates), ApiReference.md (enriched positions)
```

**Example 3: AI agent that trades**

```
User: "Give my Claude agent the ability to trade on Flash Trade"
→ Invokes SetupIntegration workflow (MCP server setup)
→ References: McpIntegration.md
```