> ## 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.

# Use your own keys

> Connect an existing exchange account by pasting its API credentials into VOOI

Paste credentials you already hold for Hyperliquid, Aster, Lighter, Robinhood, Extended, Binance, Bybit, MEXC, or Ondo to let VOOI trade on your behalf.

<Info>
  **Prerequisites:** an active VOOI API token. See [API Tokens](/docs/tokens) to obtain one, then include it as `Authorization: Bearer <token>` on every request below.
</Info>

## Hyperliquid

<Note>
  Prefer to skip the Hyperliquid UI? [Register on Hyperliquid](/docs/register-hyperliquid) lets VOOI provision an agent wallet for you.
</Note>

1. Go to [Hyperliquid API Management](https://app.hyperliquid.xyz/API).
2. Generate an **API wallet**. This is a separate key from your main wallet — it is what VOOI will use for trading, and keeping it separate limits risk if the key is ever compromised.
3. Send the credentials to [`POST /user-exchange/hyperliquid`](/docs/api-reference/user-exchange/connect-hyperliquid):

   ```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" }'
   ```

## Aster

<Note>
  Prefer to skip the signing flow? [Register on Aster](/docs/register-aster) lets VOOI provision an agent for you.
</Note>

Aster credentials describe a signer: the private key of an agent wallet you have already approved on Aster (`privateKey`), that agent's address (`signer`), and your main wallet address (`user`). Most callers should use the [registration flow](/docs/register-aster) instead, which provisions an approved agent for you.

Send the credentials to [`POST /user-exchange/aster`](/docs/api-reference/user-exchange/connect-aster):

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

## Lighter

<Note>
  Prefer to skip the Lighter UI? [Register on Lighter](/docs/register-lighter) lets VOOI provision a key for you.
</Note>

1. Go to [Lighter API Keys](https://app.lighter.xyz/apikeys).
2. Create an API key.
3. Find your Lighter account index:

   ```text theme={null}
   https://mainnet.zklighter.elliot.ai/api/v1/accountsByL1Address?l1_address=0xYourWalletAddress
   ```
4. Send the credentials to [`POST /user-exchange/lighter`](/docs/api-reference/user-exchange/connect-lighter):

   ```bash theme={null}
   curl -X POST https://perps-api.vooi.io/user-exchange/lighter \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{ "accountIndex": 123, "apiKeyIndex": 5, "privateKey": "0x..." }'
   ```

## Robinhood

<Note>
  Robinhood runs on Lighter's infrastructure, so it uses the same credential shape as Lighter. Prefer to skip the UI? [Register on Robinhood](/docs/register-robinhood) lets VOOI provision a key for you.
</Note>

Robinhood credentials are the same triple as Lighter's: your account index (`accountIndex`), an API key slot (`apiKeyIndex`), and that key's private key (`privateKey`). Send them to [`POST /user-exchange/robinhood`](/docs/api-reference/user-exchange/connect-robinhood):

```bash theme={null}
curl -X POST https://perps-api.vooi.io/user-exchange/robinhood \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "accountIndex": 123, "apiKeyIndex": 5, "privateKey": "0x..." }'
```

## Extended

<Note>
  Prefer to skip handling Stark keys? [Register on Extended](/docs/register-extended) lets VOOI provision the L2 keypair and API key for you, and is the recommended path.
</Note>

Extended is a Starknet-settled DEX, so its credentials are different from the EVM venues: a Starknet L2 keypair plus an Extended account and API key. You supply `accountId` (your Extended account, a positive integer), `apiKey`, the L2 keypair (`l2PrivateKey` and `l2PublicKey`, hex), and `vaultId` (a positive-integer string). Most callers should use the [registration flow](/docs/register-extended) instead, which provisions all of these for you.

Send the credentials to [`POST /user-exchange/extended`](/docs/api-reference/user-exchange/connect-extended):

```bash theme={null}
curl -X POST https://perps-api.vooi.io/user-exchange/extended \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": 12345, "apiKey": "...", "l2PrivateKey": "0x...", "l2PublicKey": "0x...", "vaultId": "67890" }'
```

## Binance

Binance is a centralized venue, so its credentials are a standard Binance USDⓈ-M futures **API key and secret** — not a wallet key. Create the key in your Binance account with futures trading enabled, then send it to [`POST /user-exchange/binance`](/docs/api-reference/user-exchange/connect-binance):

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

<Note>
  Binance has no VOOI-managed registration flow — connecting your own API key is the only path. VOOI also does not expose deposits, withdrawals, or transfers for Binance; move funds through Binance directly.
</Note>

## Bybit

Bybit credentials are a standard **API key and secret**. The account must be a **Unified Trading Account** — a classic account is rejected — and the key must carry derivatives trading permission and must not be read-only or expired. Send them to [`POST /user-exchange/bybit`](/docs/api-reference/user-exchange/connect-bybit):

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

<Note>
  Bybit requires a one-time trading agreement before it accepts any order on a traditional-asset market. See [Bybit trading agreements](/docs/trading-orders#bybit-trading-agreements).
</Note>

## MEXC

MEXC credentials are a standard **API key and secret**. The key needs three futures permissions — **View Account Details**, **View Order Details**, and **Order Placing**. A key missing any of them is rejected on connect with a `400` naming the ones to turn on. Send the credentials to [`POST /user-exchange/mexc`](/docs/api-reference/user-exchange/connect-mexc):

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

## Ondo

Ondo credentials are an **API key id and secret** (`apiKeyId`, not `apiKey`). Send them to [`POST /user-exchange/ondo`](/docs/api-reference/user-exchange/connect-ondo):

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

<Note>
  Ondo also supports a VOOI-managed registration flow, which signs a challenge with your wallet and provisions the API key for you — see [Registration flows](#registration-flows).
</Note>

## Registration flows

Several venues let VOOI provision credentials for you instead of you pasting your own. Those flows share one pair of endpoints, [`POST /user-exchange/{exchange}/register/prepare`](/docs/api-reference/user-exchange/prepare-exchange-registration) and [`POST /user-exchange/{exchange}/register/execute`](/docs/api-reference/user-exchange/execute-exchange-registration), and are available on **Aster, Hyperliquid, Lighter, Robinhood, Extended, and Ondo**. Binance, Bybit, and MEXC are API-key only.

The prepare call accepts an optional `referralCode` that is bound to the new account at registration; omit it and the VOOI code is applied. See the per-venue guides ([Hyperliquid](/docs/register-hyperliquid), [Lighter](/docs/register-lighter), [Aster](/docs/register-aster), [Extended](/docs/register-extended), [Robinhood](/docs/register-robinhood)) for the signing steps.

## Verify and disconnect

* [`GET /user-exchange`](/docs/api-reference/user-exchange/get-connected-exchanges) — list the exchanges currently connected to your VOOI account. Each row carries a `valid` flag (see below).
* [`DELETE /user-exchange/{exchange}`](/docs/api-reference/user-exchange/disconnect-an-exchange) — remove a connection.

### Credential validity

Every connect endpoint above performs a live check against the venue before returning, and there are two distinct failure paths:

* **Malformed body** — a bad key format, an invalid wallet address, or a missing field is rejected with `400 Bad Request` during validation. Nothing is stored.
* **Venue-rejected credentials** — a well-formed body whose credentials the venue itself rejects returns `401 Unauthorized`. In this case the connection *is* recorded, with `valid: false`, so it shows up on `/user-exchange` until you re-connect or remove it.

Once stored, the connection stays `valid: true` until VOOI sees the venue reject those credentials at trade or read time (key revoked, agent expired, account closed). At that point `valid` flips to `false` and the connection is **silently excluded** from the accounts, positions, orders, and trades endpoints and the SSE updates stream — as if that exchange were not connected. The entry still appears on [`GET /user-exchange`](/docs/api-reference/user-exchange/get-connected-exchanges) with `valid: false`, so a UI can prompt the user to re-connect.

To recover, call the connect endpoint again with fresh credentials, or [`DELETE /user-exchange/{exchange}`](/docs/api-reference/user-exchange/disconnect-an-exchange) and start over.

## Next steps

<CardGroup cols={2}>
  <Card title="Place your first trade" icon="rocket" href="/docs/trading-orders">
    Orders, cancels, and bracket TP/SL
  </Card>

  <Card title="Broker API" icon="handshake" href="/docs/broker">
    Register users and pull their trading statistics
  </Card>
</CardGroup>


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