# Endpoints Overview

### Authentication

No API key required. All endpoints are publicly accessible.

***

### Rate Limits

REST endpoints have 10 requests per second.

**Exceeded limits return:**

* `429 Too Many Requests` — per-owner limit reached

### Read-Only Endpoints (GET)

| Path                            | Description                               |
| ------------------------------- | ----------------------------------------- |
| `/health`                       | Health check with account counts          |
| `/tokens`                       | All supported tokens with metadata        |
| `/prices`                       | Current prices for all tokens             |
| `/prices/{symbol}`              | Current price for a single token          |
| `/perpetuals`                   | All perpetuals config accounts            |
| `/perpetuals/{pubkey}`          | Single perpetuals account                 |
| `/pools`                        | All pools                                 |
| `/pools/{pubkey}`               | Single pool                               |
| `/custodies`                    | All custodies                             |
| `/custodies/{pubkey}`           | Single custody                            |
| `/markets`                      | All markets                               |
| `/markets/{pubkey}`             | Single market                             |
| `/positions`                    | All positions (optional `?owner=` filter) |
| `/positions/{pubkey}`           | Single position — raw data                |
| `/orders`                       | All orders (optional `?owner=` filter)    |
| `/orders/{pubkey}`              | Single order — raw data                   |
| `/positions/owner/{owner}`      | Enriched positions for a wallet           |
| `/orders/owner/{owner}`         | Enriched orders for a wallet              |
| `/pool-data`                    | All pool snapshots (cached, 15s refresh)  |
| `/pool-data/{pool_pubkey}`      | Single pool snapshot                      |
| `/pool-data/status/initialized` | Cache initialization status               |

***

### Transaction Builder Endpoints (POST)

| Path                                     | Description                                         |
| ---------------------------------------- | --------------------------------------------------- |
| `/transaction-builder/open-position`     | Preview + build open position transaction           |
| `/transaction-builder/close-position`    | Preview + build close position transaction          |
| `/transaction-builder/add-collateral`    | Preview + build add collateral transaction          |
| `/transaction-builder/remove-collateral` | Preview + build remove collateral transaction       |
| `/transaction-builder/reverse-position`  | Preview + build reverse (flip) position transaction |

***

### Preview Endpoints (POST)

| Path                        | Description                                  |
| --------------------------- | -------------------------------------------- |
| `/preview/limit-order-fees` | Preview fees for a limit order               |
| `/preview/exit-fee`         | Preview exit fee for closing a position      |
| `/preview/tp-sl`            | Preview take-profit / stop-loss calculations |
| `/preview/margin`           | Preview adding or removing margin            |

***

### Health & Tokens

#### GET /health

bash

```bash
curl https://flashapi.trade/health
```

json

```json
{
  "status": "ok",
  "accounts": {
    "perpetuals": 1,
    "pools": 1,
    "custodies": 7,
    "markets": 11,
    "positions": 542,
    "orders": 128
  }
}
```

***

#### GET /tokens

Returns all supported tokens with metadata: symbol, mint address, decimals, and price feed IDs.

bash

```bash
curl https://flashapi.trade/tokens
```

json

```json
[
  {
    "symbol": "SOL",
    "mintKey": "So11111111111111111111111111111111111111112",
    "decimals": 9,
    "usdPrecision": 2,
    "tokenPrecision": 2,
    "isStable": false,
    "isVirtual": false,
    "lazerId": 123456,
    "pythTicker": "Solana",
    "pythPriceId": "ef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d",
    "isToken2022": false
  }
]
```

***

### Prices

#### GET /prices

bash

```bash
curl https://flashapi.trade/prices
```

json

```json
{
  "SOL": {
    "price": "14852000000",
    "exponent": "-8",
    "price_ui": "148.52",
    "timestamp_us": "1707900000000000"
  }
}
```

| Field          | Description                                  |
| -------------- | -------------------------------------------- |
| `price`        | Raw integer from the oracle                  |
| `exponent`     | Decimal shift — divide by `10^abs(exponent)` |
| `price_ui`     | Human-readable price — use this for display  |
| `timestamp_us` | Last update time in microseconds since epoch |

#### GET /prices/{symbol}

bash

```bash
curl https://flashapi.trade/prices/SOL
```

Symbol is case-insensitive: `SOL`, `BTC`, `ETH`, etc.

***

### Raw Account Data

These endpoints return on-chain account data as JSON. Useful for building custom UIs or running your own calculations.

```
GET /perpetuals          # Global protocol config (usually 1)
GET /pools               # All liquidity pools
GET /custodies           # All token custody accounts
GET /markets             # All tradeable markets
```

Each supports `/{pubkey}` for a single account lookup.

***

### Positions (Raw)

```
GET /positions                    # All positions
GET /positions?owner={pubkey}     # Filter by wallet
GET /positions/{pubkey}           # Single position
```

***

### Orders (Raw)

```
GET /orders                       # All orders
GET /orders?owner={pubkey}        # Filter by wallet
GET /orders/{pubkey}              # Single order
```

***

### Enriched Positions

Returns computed, human-readable position data with PnL, leverage, liquidation prices, and more. Use this for building trading UIs.

```
GET /positions/owner/{owner}?includePnlInLeverageDisplay=true
```

| Parameter                     | Required | Description                                             |
| ----------------------------- | -------- | ------------------------------------------------------- |
| `owner`                       | yes      | Wallet pubkey (base58)                                  |
| `includePnlInLeverageDisplay` | yes      | Include PnL in leverage calculation (`true` or `false`) |

**Example response:**

json

```json
[
  {
    "key": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "positionAccountData": "qryP5HpA99AAAAAA...",
    "sideUi": "Long",
    "marketSymbol": "SOL",
    "collateralSymbol": "USDC",
    "entryPriceUi": "148.52",
    "sizeAmountUi": "3.37",
    "sizeUsdUi": "500.00",
    "collateralAmountUi": "100.00",
    "collateralUsdUi": "100.00",
    "isDegen": null,
    "pnl": {
      "profitUsd": "1250000",
      "lossUsd": "0",
      "exitFeeUsd": "400000",
      "borrowFeeUsd": "150000"
    },
    "pnlWithFeeUsdUi": "11.95",
    "pnlPercentageWithFee": "11.95",
    "liquidationPriceUi": "120.30",
    "leverageUi": "5.00"
  }
]
```

**Field notes:**

* `sideUi`, `marketSymbol`, and other enriched fields may be `null` if enrichment fails (e.g., market delisted or price unavailable). `key` and `positionAccountData` are always present for fallback raw decoding.
* `positionAccountData` is base64-encoded raw Anchor account bytes — decode with `program.coder.accounts.decode('position', data)` in JS/TS.
* `sizeAmountUiKmb` formats large numbers: `1500` → `"1.50K"`, `2500000` → `"2.50M"`.
* `isDegen` is `true` for degen mode positions, otherwise omitted.
* `pnl.profitUsd` / `pnl.lossUsd` are raw native values (6 decimals). Use `pnlWithFeeUsdUi` for display.
* Positions are sorted by size, largest first.

***

### Enriched Orders

```
GET /orders/owner/{owner}
```

| Parameter | Required | Description            |
| --------- | -------- | ---------------------- |
| `owner`   | yes      | Wallet pubkey (base58) |

Returns limit orders, take-profit orders, and stop-loss orders grouped by order account.

**Example response:**

json

```json
[
  {
    "key": "ABC123...",
    "limitOrders": [
      {
        "sideUi": "Long",
        "symbol": "SOL",
        "sizeUsdUi": "500.00",
        "entryPriceUi": "148.52",
        "leverageUi": "5.00",
        "liquidationPriceUi": "120.30",
        "limitTakeProfitPriceUi": "-",
        "limitStopLossPriceUi": "-"
      }
    ],
    "takeProfitOrders": [
      {
        "type": "TP",
        "symbol": "SOL",
        "sizeUsdUi": "500.00",
        "triggerPriceUi": "160.00"
      }
    ],
    "stopLossOrders": [
      {
        "type": "SL",
        "symbol": "SOL",
        "sizeUsdUi": "500.00",
        "triggerPriceUi": "130.00"
      }
    ]
  }
]
```

**Field notes:**

* `limitTakeProfitPriceUi` and `limitStopLossPriceUi` are `"-"` when not set.
* `type` is `"TP"` for take-profit, `"SL"` for stop-loss.
* `leverage` is an empty string `""` for TP/SL orders.

***

### Pool Data

Pre-computed pool metrics including AUM, LP stats, and custody utilization. Cached and refreshed every 15 seconds.

```
GET /pool-data                          # All pools
GET /pool-data/{pool_pubkey}            # Single pool
```