> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocx.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Read public market data, sign in with your wallet, fund a venue, and place your first order — in minutes.

This guide takes you from zero to your first order. You will read public market
data (no credentials), sign in with your wallet, move collateral into a venue,
and place a trade. All requests go through the API gateway, referred to here as
`{BASE_URL}`.

<Info>
  Prices and sizes are decimal **strings**. Send and parse them as strings to
  keep full precision.
</Info>

## 1. Read public market data

No authentication is needed for market data. List the linear markets and pull a
book snapshot.

<CodeGroup>
  ```bash curl theme={null}
  # list perp / futures / spot markets
  curl -s "{BASE_URL}/perps/markets"

  # order book snapshot for one market
  curl -s "{BASE_URL}/perps/orderbook/BTC-PERP?depth=10"

  # 24h ticker: mark, change, volume, open interest, funding
  curl -s "{BASE_URL}/perps/market-stats?marketId=BTC-PERP"
  ```

  ```js JavaScript theme={null}
  const markets = await fetch(`${BASE_URL}/perps/markets`).then(r => r.json());
  const book = await fetch(
    `${BASE_URL}/perps/orderbook/BTC-PERP?depth=10`,
  ).then(r => r.json());
  console.log(markets[0], book.bids[0], book.asks[0]);
  ```
</CodeGroup>

Example market-stats response:

```json theme={null}
{
  "marketId": "BTC-PERP",
  "baseSymbol": "BTC",
  "markPrice": "68210.5",
  "change24hPct": "1.42",
  "volume24hUsd": "18422100",
  "openInterestUsd": "9231000",
  "funding1hPct": "0.0021"
}
```

<Tip>
  For live values, subscribe to the SSE stream `{BASE_URL}/perps/book-stream?marketId=BTC-PERP`
  instead of polling — it pushes a snapshot then incremental updates.
</Tip>

## 2. Sign in with your wallet

Open a session with SIWE. Request a nonce, sign the message in your wallet, then
verify. See [Authentication](/get-started/authentication) for the full flow.

```bash theme={null}
NONCE=$(curl -s -X POST {BASE_URL}/auth/nonce \
  -H 'Content-Type: application/json' \
  -d '{"walletAddress":"0xabc..."}' | jq -r .nonce)

# build + sign the SIWE message with $NONCE → $MSG, $SIG
curl -s -c cookies.txt -X POST {BASE_URL}/auth/siwe \
  -H 'Content-Type: application/json' \
  -d "{\"message\":\"$MSG\",\"signature\":\"$SIG\"}"
```

The `-c cookies.txt` jar now holds your session cookie; pass `-b cookies.txt` on
authenticated calls.

## 3. Fund a venue

Deposits land in your `wallet` bucket. Move collateral into the venue you want to
trade — here, `perps`.

<Steps>
  <Step title="Check your balances">
    ```bash theme={null}
    curl -s -b cookies.txt {BASE_URL}/wallet/balance
    ```

    ```json theme={null}
    { "walletBalance": "2000.00", "perpsBalance": "0", "optionsBalance": "0", "pendingWithdrawalTotal": "0" }
    ```
  </Step>

  <Step title="Transfer wallet → perps">
    ```bash theme={null}
    curl -s -b cookies.txt -X POST {BASE_URL}/wallet/transfer \
      -H 'Content-Type: application/json' \
      -d '{"from":"wallet","to":"perps","amount":"500"}'
    ```

    Transfers are atomic. Move funds back to `wallet` before withdrawing.
  </Step>
</Steps>

## 4. Preview, then place your first order

Always dry-run first. `preview` returns your notional, estimated fee, fee role,
your volume tier, and whether the order passes the margin check — with no side
effects.

<CodeGroup>
  ```bash curl theme={null}
  # dry-run
  curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders/preview \
    -H 'Content-Type: application/json' \
    -d '{"marketId":"BTC-PERP","side":"buy","type":"limit","price":"68000","quantity":"0.05"}'

  # place a post-only limit order
  curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders \
    -H 'Content-Type: application/json' \
    -d '{"marketId":"BTC-PERP","side":"buy","type":"limit","price":"68000","quantity":"0.05","timeInForce":"gtc","postOnly":true,"clientOrderId":"my-first-order"}'
  ```

  ```js JavaScript theme={null}
  const order = await fetch(`${BASE_URL}/perps/orders`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    credentials: "include",
    body: JSON.stringify({
      marketId: "BTC-PERP",
      side: "buy",
      type: "limit",
      price: "68000",
      quantity: "0.05",
      timeInForce: "gtc",
      postOnly: true,
      clientOrderId: "my-first-order",
    }),
  }).then(r => r.json());
  ```
</CodeGroup>

<Note>
  Use `clientOrderId` for idempotent client-side tracking. `postOnly` keeps you
  on the maker side (the order is rejected if it would take liquidity), and
  `reduceOnly` prevents an order from increasing your position.
</Note>

## 5. Watch your orders, positions, and fills

<CodeGroup>
  ```bash curl theme={null}
  curl -s -b cookies.txt "{BASE_URL}/perps/orders/open"
  curl -s -b cookies.txt "{BASE_URL}/perps/positions"
  curl -s -b cookies.txt "{BASE_URL}/perps/trades"
  ```

  ```js JavaScript theme={null}
  // live: book + your fills + your positions for one market
  const es = new EventSource(
    `${BASE_URL}/perps/stream/events?marketId=BTC-PERP`,
    { withCredentials: true },
  );
  es.addEventListener("snapshot", e => init(JSON.parse(e.data).payload));
  es.addEventListener("delta",    e => apply(JSON.parse(e.data).payload));
  ```
</CodeGroup>

To exit, cancel resting orders or close the position:

```bash theme={null}
curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders/cancel-all \
  -H 'Content-Type: application/json' -d '{"marketId":"BTC-PERP"}'

curl -s -b cookies.txt -X POST {BASE_URL}/perps/positions/close \
  -H 'Content-Type: application/json' -d '{"marketId":"BTC-PERP"}'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication & API keys" icon="key" href="/get-started/authentication">
    Provision scoped keys for bots and market makers.
  </Card>

  <Card title="Methodology" icon="function" href="/methodology/overview">
    Understand marks, funding, and the options surface.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/get-started/architecture">
    See how the gateway, engines, and streams fit together.
  </Card>

  <Card title="Market data API" icon="chart-line" href="/api-reference/rest">
    Pull the option board, order books, and marks over REST.
  </Card>
</CardGroup>