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

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

Registration provisions a VOOI-managed key on your Extended account so the API can place orders and request Extended withdrawals on your behalf. Your funds remain in your own Extended account.

<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?

Check whether your VOOI account already has Extended credentials via [`GET /user-exchange`](/docs/api-reference/user-exchange/get-connected-exchanges). It returns an array of `{ exchange, valid }` objects — an `extended` 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>

* **An `extended` entry with `valid: true`** — your account is already connected. No action needed.
* **No `extended` entry, or one with `valid: false`** — follow the steps below.

Extended does not require a prior deposit before registering, so there is no eligibility check to run first.

## Prerequisites

* An EVM wallet
* An active VOOI API token

## 1. Prepare registration

Call [`POST /user-exchange/{exchange}/register/prepare`](/docs/api-reference/user-exchange/prepare-exchange-registration) with your wallet address.

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 response contains:

* a short-lived `registrationToken`
* `signData` — a **three-item tuple** you sign in order: `[0]` and `[1]` are EIP-712 typed-data objects (account creation, then account registration), and `[2]` is an object `{ "message": "<text>", "type": "personalSign" }` whose `message` you sign with the `personal_sign` convention.

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

  {
    "address": "0xYourWalletAddress"
  }
  ```

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

Response shape:

```jsonc theme={null}
{
  "exchange": "extended",
  "registrationToken": "<opaque-token>",
  "signData": [
    { /* EIP-712 typed data — account creation */ },
    { /* EIP-712 typed data — account registration */ },
    { "message": "<plain-text message to sign>", "type": "personalSign" }
  ]
}
```

The two EIP-712 items each have `domain`, `message`, `primaryType`, and `types`. Their domain carries only a `name` (`"extended.exchange"`) and **no `chainId`**, so there is no network to match against and no wallet network switch is needed. The third item is an object with a `message` string and `type: "personalSign"` — you sign its `message`. See the API reference for the full schema.

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

## 2. Sign all three messages

Sign each item in order:

* `[0]` and `[1]` as EIP-712 typed data
* `[2]`'s `message` field as a plain-text message (Ethereum `personal_sign` convention), **not** as EIP-712 typed data

Pass the resulting signatures to the next step in the same order, `[sig0, sig1, sig2]`.

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

async function signRegistration(
  walletPrivateKey: Hex,
  signData: PrepareResponse['signData'],
): Promise<[Hex, Hex, Hex]> {
  const account = privateKeyToAccount(walletPrivateKey);
  const [creation, registration, apiKey] = signData;

  const signTyped = (item: typeof creation) =>
    account.signTypedData({
      domain: item.domain,
      message: item.message,
      primaryType: item.primaryType,
      types: item.types,
    });

  return [
    await signTyped(creation),
    await signTyped(registration),
    await account.signMessage({ message: apiKey.message }),
  ];
}
```

This step returns three signatures that will be used in the next request to complete registration.

## 3. Execute registration

Submit your wallet address, the `registrationToken`, and all three signatures (in order) to [`POST /user-exchange/{exchange}/register/execute`](/docs/api-reference/user-exchange/execute-exchange-registration).

VOOI submits the signed onboarding messages to Extended on your behalf — you do **not** broadcast anything on-chain.

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

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

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

Response on success:

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

`valid` reflects whether the stored credentials passed validation.

The VOOI referral code is applied to your Extended account automatically on registration — no client action is required. To apply a different code yourself, see [`POST /extended/use-referral-code`](/docs/api-reference/extended/apply-a-referral-code-to-the-extended-account).

<Note>
  Re-running the full prepare → execute flow is safe if a step fails. Call prepare again to get a fresh `registrationToken`, then sign and execute as above.
</Note>

**Possible errors:**

| Status | Message | Cause |
| - | - | - |
| `400 Bad Request` | `Registration token has expired` | The token from step 1 expired. Call the prepare endpoint again to get a new one. |
| `400 Bad Request` | `Account was created on Extended but credentials could not be issued. Please retry the registration flow.` | The account was created but the VOOI-managed key could not be issued. Re-run the full flow (re-prepare, then execute). |

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

## Next steps

<CardGroup cols={2}>
  <Card title="Start trading on Extended" 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>
</CardGroup>


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