Skip to main content
Before you can place orders or manage collateral on UpsideMAX, 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. Registration also enrolls the account in a Market Deployer in the same atomic operation, so there is no “registered but not enrolled” state and no separate enrollUserToMarketDeployer call is needed for that deployer:
  • marketDeployerId omitted — the account joins the default Market Deployer. If the default Market Deployer does not exist yet, the account is registered without joining one and enrolledMarketDeployerId is 0.
  • marketDeployerId = N (N > 0) — the account joins Market Deployer N. If it does not exist, the whole registration is rejected and no account is created.
  • marketDeployerId = 0 — the account is registered without joining any Market Deployer.
Registration requires a valid single-use invitation code, on Mainnet and Devnet alike. Pass inviteCode at the envelope top level — alongside action, signature, and nonce — not inside the action object. The invitation code is not included in the signed payload.

​
Endpoint

​
Request

​
Action Fields

​
string
required
type (required) — Must be the fixed string "registerAccount".
​
string
required
address (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).
​
int32
marketDeployerId — The Market Deployer to join at registration, a JSON number in [0, 2147483647]. Omit to join the default Market Deployer; 0 registers without joining one. A value outside the range returns 400 INVALID_PARAM. A string such as "1" cannot be encoded as uint32 for signing and returns 401 SIGNATURE_INVALID.
Whether marketDeployerId is present selects the EIP-712 struct you sign. The two cannot be mixed — signing with the other struct returns 401 SIGNATURE_INVALID.See Authentication for the typed-path signing procedure.

​
Envelope-Level Fields

​
string
inviteCode — A 6-character alphanumeric invitation code. Required on Mainnet and Devnet. 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.

​
Response

accountId and enrolledMarketDeployerId sit directly under response; this action has no data object.
​
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.
​
int
The Market Deployer the account joined in this registration. 0 means it joined none — either the request passed 0, or it omitted the field and the default Market Deployer does not exist yet.
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.
A new account starts with no balance. The account exists only after this action returns a successful response with an accountId; funds sent to the address or its Market Deployer margin before then are not credited. Deposit funds on Mainnet (for Devnet funds, contact the UpsideMAX team), move chain-level funds into the Market Deployer with lockCollateral, and check userAccount until marginAvailableForOrder is non-zero before trading.

​
Errors

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 Info API instead of re-registering.

​
Next Steps

1

Save your accountId

Store the returned accountId securely in your application config or database. All collateral and position operations reference it.
2

Enroll in other Market Deployers

Registration enrolls you in one Market Deployer (enrolledMarketDeployerId). To trade contracts of another Market Deployer, call enrollUserToMarketDeployer.
3

Confirm your margin

Poll userAccount until margin is available in the Market Deployer you joined.
4

Place your first order

Use the order action to open a perpetual position.