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

# registerAccount: Register Your Wallet on Upside

> Register your wallet address with Upside to receive a unique accountId required for all subsequent trading and collateral operations.

Before you can place orders or manage collateral on Upside , you must register your wallet address using the `registerAccount` action. A successful registration returns a unique `accountId` — a decimal integer that identifies your account across every subsequent API call. You only need to register once per wallet address.

<Note>
  In gated environments, registration requires a valid invite code. Pass `inviteCode` at the **envelope top level** — alongside `action`, `signature`, and `nonce` — not inside the `action` object. The invite code is **not** included in the signed payload.
</Note>

## Request

```text theme={"system"}
POST https://dev.upsidemax.xyz/exchange
Content-Type: application/json
```

```json theme={"system"}
{
  "action": {
    "type": "registerAccount",
    "address": "0x7b94aeea275c43ab537a8cd55f7551688c6521ad"
  },
  "signature": { "r": "0x...", "s": "0x...", "v": 28 },
  "nonce": 1778572816871,
  "inviteCode": "A3K9Q2"
}
```

### Action Fields

<ParamField body="type" type="string" required>
  Must be the fixed string `"registerAccount"`.
</ParamField>

<ParamField body="address" type="string" required>
  The wallet address you are registering. Must be `0x`-prefixed and contain exactly 40 lowercase hexadecimal characters (EIP-55 checksummed addresses are also accepted).
</ParamField>

### Envelope-Level Fields

<ParamField body="inviteCode" type="string">
  A 6-character alphanumeric invite code. **Required** in gated environments; silently ignored in open environments. Do **not** include this field inside `action` — it must sit at the top level of the request body alongside `action`, `signature`, and `nonce`. It is not part of the signature.
</ParamField>

## Response

```json theme={"system"}
{
  "status": "ok",
  "requestId": "req-144115188075855882",
  "response": {
    "type": "registerAccount",
    "accountId": "3"
  }
}
```

<ResponseField name="accountId" type="string">
  Your new account's unique identifier, encoded as a decimal string representing an int64. Store this value — you will need it for collateral operations, order placement, and any action that references your account.
</ResponseField>

<Tip>
  Even though `accountId` is returned as a string, it is a 64-bit integer. Use a big-integer or string type in your client to avoid precision loss in JavaScript environments.
</Tip>

## Error Reference

| Error                    | HTTP Status | Cause                                                                                |
| ------------------------ | ----------- | ------------------------------------------------------------------------------------ |
| `ACCOUNT_ALREADY_EXISTS` | 400         | The provided `address` is already registered. Each wallet can only hold one account. |
| `INVITE_CODE_INVALID`    | 403         | The `inviteCode` was not found or has already been used.                             |
| `inviteCode required`    | 400         | The environment requires an invite code but none was provided.                       |

<Warning>
  If you attempt to register the same wallet address twice, the server returns `ACCOUNT_ALREADY_EXISTS`. To retrieve an existing account's `accountId`, query the read API instead of re-registering.
</Warning>

## Next Steps

<Steps>
  <Step title="Save your accountId">
    Store the returned `accountId` securely in your application config or database. All collateral and position operations reference it.
  </Step>

  <Step title="Enroll in a market deployer">
    You are automatically enrolled in the default market deployer on registration. To trade contracts in additional environments, call [`enrollUserToMarketDeployer`](/exchange/enroll-user-to-market-deployer).
  </Step>

  <Step title="Lock collateral">
    Deposit collateral into your chosen market deployer with [`lockCollateral`](/exchange/lock-collateral) before placing any orders.
  </Step>

  <Step title="Place your first order">
    Once collateral is in place, use the [`order`](/exchange/order) action to open a perpetual position.
  </Step>
</Steps>