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

# Register on Lighter

> Register a VOOI-managed key to trade on Lighter through the VOOI API

Registration links your EVM wallet to Lighter by registering a VOOI-managed public key on your Lighter sub-account. Your funds remain in your own Lighter account. Once registered, the API can sign and submit transactions on your behalf.

<Info>
  This guide assumes that you already have an active VOOI API token. See [API Tokens](/docs/tokens) for how to obtain one.
</Info>

## Do you need to register?

Start by checking whether your VOOI account already has Lighter credentials via [`GET /user-exchange`](/docs/api-reference/user-exchange/get-connected-exchanges). It returns an array of `{ exchange, valid }` objects — a `lighter` entry with `valid: true` means your account is connected:

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/user-exchange
  Authorization: Bearer <token>
  ```

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

* **A `lighter` entry with `valid: true`** — your account is already connected. No action needed.
* **No `lighter` entry, or one with `valid: false`** — check your registration status on Lighter via [`GET /user-exchange/{exchange}/register/status`](/docs/api-reference/user-exchange/check-registration-status):

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/user-exchange/lighter/register/status?address=0xYourWalletAddress
  ```

  ```bash curl theme={null}
  curl "https://perps-api.vooi.io/user-exchange/lighter/register/status?address=0xYourWalletAddress"
  ```
</CodeGroup>

* **`isRegistered: true`** — your wallet has a Lighter sub-account and is eligible to register. Follow the steps below, or, if you already created a Lighter API key yourself, paste those credentials via [`POST /user-exchange/lighter`](/docs/api-reference/user-exchange/connect-lighter) (see [Use your own keys](/docs/exchanges)).
* **`isRegistered: false`** — your wallet has no Lighter sub-account yet. Deposit first (step 1 below) and the flag will flip once Lighter reflects the sub-account.

<Note>
  `isRegistered` reports "does this wallet have a Lighter sub-account" — in practice, "has it ever deposited to Lighter". It does **not** mean a VOOI-managed key is active on that sub-account. A wallet that deposited directly through the Lighter UI also flips the flag to `true` — the check reads Lighter's own state, not VOOI's.
</Note>

## Prerequisites

* An EVM wallet
* An active VOOI API token
* USDC deposited to Lighter from your wallet address (this creates your Lighter sub-account)

## 1. Deposit USDC to Lighter

Your wallet address must have a Lighter sub-account before you can register a VOOI-managed key. Depositing USDC creates one automatically.

You can deposit through the Lighter UI or use [`GET /deposit`](/docs/api-reference/deposit/get-deposit-transactions-for-signing) to receive ready-to-sign calldata.

### Using the deposit endpoint

<CodeGroup>
  ```bash Request theme={null}
  GET https://perps-api.vooi.io/deposit?exchange=lighter&chainId=42161&amount=5&address=0xYourWalletAddress
  Authorization: Bearer <token>
  ```

  ```bash curl theme={null}
  curl "https://perps-api.vooi.io/deposit?exchange=lighter&chainId=42161&amount=5&address=0xYourWalletAddress" \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

The response contains one or more transactions to sign and submit on Arbitrum One. Example:

```json theme={null}
{
  "transactions": [
    {
      "calldata": {
        "chainId": 42161,
        "data": "0xa9059cbb...",
        "to": "0x..."
      },
      "meta": { "amount": "5.0", "type": "transfer" }
    }
  ]
}
```

Sign and submit each transaction in the provided order using an EVM wallet such as MetaMask. If there are multiple transactions (e.g. an `approve` followed by a `transfer`), submit them one at a time and wait for each to confirm before sending the next.

The minimum deposit amount is 5 USDC. Lighter usually processes deposits within up to 10 minutes.

## 2. Prepare registration

Call [`POST /user-exchange/{exchange}/register/prepare`](/docs/api-reference/user-exchange/prepare-exchange-registration) with your wallet address and an API key index to generate the registration data.

The optional `referralCode` field binds a referral code to the new account at registration. Omit it and the VOOI code is applied; it cannot be changed afterwards. See [Points & rewards](/docs/points#referral-code).

The API key index identifies which key slot on your Lighter sub-account VOOI will register. We recommend choosing a value greater than 230, since lower slots can collide with keys Lighter's own apps use. If you use multiple integrations on the same Lighter account, give each a distinct value.

The API returns the following:

* a short-lived `registrationToken`
* a plain-text message to sign

<CodeGroup>
  ```bash Request theme={null}
  POST https://perps-api.vooi.io/user-exchange/lighter/register/prepare
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "address": "0xYourWalletAddress",
    "apiKeyIndex": 241
  }
  ```

  ```bash curl theme={null}
  curl -X POST https://perps-api.vooi.io/user-exchange/lighter/register/prepare \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"address": "0xYourWalletAddress", "apiKeyIndex": 241}'
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "exchange": "lighter",
  "registrationToken": "<opaque-token>",
  "signData": "<plain-text message to sign>"
}
```

`signData` is a plain-text string — not EIP-712 typed data.

The `registrationToken` expires in 10 minutes. If it expires before you complete registration, call this endpoint again to get a new token.

**Possible errors:**

| Status | Message | Cause |
| - | - | - |
| `409 Conflict` | `No deposits found for 0x.... Please deposit funds before registering.` | Your wallet has no Lighter sub-account yet. Complete step 1 first. |

## 3. Sign the message

Sign the `signData` string as a plain text message (Ethereum `personal_sign` convention), **not** as EIP-712 typed data.

```typescript theme={null}
import { type Hex } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

async function signRegistrationMessage(walletPrivateKey: Hex, message: string): Promise<Hex> {
  const account = privateKeyToAccount(walletPrivateKey);
  return account.signMessage({ message });
}
```

This step returns a signature that will be used in the next request to complete registration.

## 4. Execute registration

Submit your wallet address, the `registrationToken`, and the signature (wrapped in a single-element `signatures` array) to [`POST /user-exchange/{exchange}/register/execute`](/docs/api-reference/user-exchange/execute-exchange-registration).

VOOI submits the signed `ChangePubKey` to Lighter on your behalf — you do **not** broadcast it yourself. The only on-chain transaction you sign is the USDC deposit in step 1.

<CodeGroup>
  ```bash Request theme={null}
  POST https://perps-api.vooi.io/user-exchange/lighter/register/execute
  Authorization: Bearer <token>
  Content-Type: application/json

  {
    "address": "0xYourWalletAddress",
    "registrationToken": "<opaque-token>",
    "signatures": ["0x..."]
  }
  ```

  ```bash curl theme={null}
  curl -X POST https://perps-api.vooi.io/user-exchange/lighter/register/execute \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{"address": "0xYourWalletAddress", "registrationToken": "<opaque-token>", "signatures": ["0x..."]}'
  ```
</CodeGroup>

Response on success:

```json theme={null}
{ "exchange": "lighter", "valid": true }
```

**Possible errors:**

| Status | Message | Cause |
| - | - | - |
| `400 Bad Request` | `Registration token has expired` | The token from step 2 expired. Call the prepare endpoint again to get a new one. |

Your wallet is now connected to Lighter through VOOI. You can use the VOOI API to place orders, manage positions, and query account data on Lighter.

<Note>
  If the broker you signed up through charges builder fees on Lighter, a one-time builder-fee approval is required before your orders carry the broker record — a separate signed step. See [Approve flow fallback](/docs/broker#approve-flow-fallback). Connecting to a broker that doesn't use builder fees needs no extra approval.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Start trading on Lighter" icon="bolt" href="/docs/trading-orders">
    Place your first order
  </Card>

  <Card title="Connect your wallet to Hyperliquid" icon="plug" href="/docs/register-hyperliquid">
    Register on Hyperliquid
  </Card>

  <Card title="Connect your wallet to Extended" icon="plug" href="/docs/register-extended">
    Register on Extended
  </Card>
</CardGroup>


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