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

# Quickstart

> From authentication to your first order using VOOI Perps API

This guide covers the minimum steps required to authenticate, connect an exchange, explore markets, and place your first order.

## Base URL

```text theme={null}
https://perps-api.vooi.io
```

## 1. Create an API token

VOOI Perps API uses Ed25519 signatures to issue access tokens.

Your public key is registered once, either through [VOOI Ultra](https://ultra.vooi.io/) during sign-up or through the broker application that onboarded you. To create a token, sign the token request with the matching private key. Use the returned bearer token for every request that requires authentication.

```bash theme={null}
curl -X POST https://perps-api.vooi.io/user/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "userId":    "0191f6b3-2d4a-7c8e-9f01-2a3b4c5d6e7f",
    "timestamp": <current Unix ms>,
    "signature": "<128-char hex Ed25519 signature over createToken:<timestamp>:::<userId>>"
  }'
```

The `timestamp` must be the current time in milliseconds, within ±2 minutes of server time.

The response contains the bearer token. Use it as `Authorization: Bearer vooi_…` on every authenticated request. You can verify the token with [`GET /user`](/docs/api-reference/user/get-current-user-info).

See [API Tokens](/docs/tokens) for message templates, signing examples, and error details.

## 2. Connect an exchange

Before trading, connect at least one supported exchange.

```bash theme={null}
curl -X POST https://perps-api.vooi.io/user-exchange/hyperliquid \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiWalletPrivateKey": "0x...",
    "userAddress": "0xYourWalletAddress"
  }'
```

There are two ways to connect an exchange account:

* Use your own exchange credentials and submit them through the VOOI API. See [Use your own keys](/docs/exchanges) for the self-managed flow.
* Use a VOOI-managed registration flow, where supported. For this flow, see [Register on Hyperliquid](/docs/register-hyperliquid), [Register on Lighter](/docs/register-lighter), [Register on Extended](/docs/register-extended), or [Register on Robinhood](/docs/register-robinhood); Aster and Ondo support it too. Binance, Bybit, and MEXC connect via your own API key only (see [Use your own keys](/docs/exchanges)).

## 3. Explore markets

Use [`GET /exchange/markets`](/docs/api-reference/exchange/get-available-trading-markets) to retrieve available markets, prices, leverage limits, 24h volume, and precision data.

Authentication is not required for this endpoint.

Most list endpoints also accept the `exchanges` query parameter to filter results by venue.

```bash theme={null}
curl "https://perps-api.vooi.io/exchange/markets?exchanges=hyperliquid"
curl -H "Authorization: Bearer <token>" \
  "https://perps-api.vooi.io/exchange/positions?exchanges=hyperliquid&exchanges=aster"
```

Valid values are `hyperliquid`, `lighter`, `aster`, `extended`, `binance`, `robinhood`, `bybit`, `mexc`, and `ondo`. If omitted, the response includes all available or connected exchanges, depending on the endpoint.

## 4. Place your first order

**Important:** Before placing an order, make sure the selected exchange account has an available balance. If not, [fund the account](/docs/deposits) first.

Use [`POST /exchange/orders`](/docs/api-reference/exchange/create-a-new-order) to place an order.

Example: minimal market buy order.

```bash theme={null}
curl -X POST https://perps-api.vooi.io/exchange/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "hyperliquid",
    "asset":    "ETH",
    "side":     "buy",
    "size":     "0.01"
  }'
```

Response: `{ "status": "ok" }`.

See [Orders](/docs/trading-orders) for bracket TP/SL, batch create, and cancel flows.

If you want to estimate execution before placing an order, see [Quotes and slippage](/docs/trading-quotes).

## 5. Check your position

After the order is executed, use [`GET /exchange/positions`](/docs/api-reference/exchange/get-open-positions) to check the resulting position.

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://perps-api.vooi.io/exchange/positions
```

Each row includes `side`, `size`, `entryPrice`, `leverage`, `liquidationPrice`, `unrealizedPnl`, and more.

See [Positions and accounts](/docs/trading-positions) for balances, leverage, and account settings.

## Next steps

* [API Tokens](/docs/tokens) – token creation, signing, and token-related errors
* [Quotes and slippage](/docs/trading-quotes) – preview execution before placing orders
* [Orders](/docs/trading-orders) – place and manage orders
* [Positions and accounts](/docs/trading-positions) – check positions, balances, and leverage


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.