API Keys and Nonces

The docs overload the word "key" in several ways. This table pins the meanings down once; later sections assume these definitions.

Term	What it is	Example
Master wallet	The EVM wallet that owns the Sodex account. Deposits and addAPIKey / revokeAPIKey must be signed by this wallet.	EVM address 0xAbC...123
Master wallet private key	The 32-byte ECDSA private key of the master wallet. Holding it grants full control of the account. Reserve it for account-level actions such as API key registration, revocation, and builder-fee approval; use a dedicated API key for routine trading.	0x1234...cdef (32 bytes, hex)
API key	A named, revocable signing credential attached to the master account (or a sub-account) via addAPIKey. Each master account can hold up to 5 API keys. API keys are for signing trading actions — they cannot query account data. Using an API key (rather than the master wallet) for day-to-day trading is the recommended workflow.	a row with name="api-key-01", publicKey=0x3d45...8256
API key name	The human-readable string that identifies one API key. Must match ^[0-9a-zA-Z_-]{1,36}$ and cannot be default. Passed in the X-API-Key HTTP header (despite the header's name, the value is the key name, not a public key or private key).	"api-key-01"
API key public key	The EVM address registered for that API key. Stored on-chain when you call addAPIKey and also echoed in query responses.	0x3d4595c8742d0a58173a9963c05755b59a8f8256
API key private key	The 32-byte ECDSA private key whose public address matches the API key's public key. Held by the client; used to sign every request that presents that API key's name in X-API-Key.	0xabcd...7890 (32 bytes, hex)

Which key signs what

Action	Who signs	Which private key
addAPIKey / addPermissionedAPIKey / approveBuilderFee / revokeAPIKey	Master wallet	Master wallet's private key
All other trading actions (e.g. newOrder, cancelOrder, newTwapOrder, cancelTwapOrder, transferAsset)	A registered API key (recommended), or the master wallet	The selected signer's private key

Recommended workflow: use the master wallet's private key only for account-level actions such as registering or revoking API keys and approving builder fees. For all normal trading requests, sign with a dedicated API key's private key. This lets you keep the master wallet offline and rotate signing credentials without moving funds.

Direct master-wallet signing is supported but not recommended for routine trading. Omit X-API-Key when using the master wallet; when the header names an API key, the signature must match that key.

Header naming caveat — the HTTP header X-API-Key carries the name of the key, not the key value. The corresponding private key is used to produce X-API-Sign; the private key itself is never sent over the wire.

API keys

A master account can approve or revoke API keys to sign on behalf of the master account or any of the sub-accounts. Each master account can have at most 5 API keys.

Sodex currently supports EVM addresses as API key public keys. The client holds the API key's private key and uses it to sign each request; the server verifies the signature against the API key's registered public key.

API keys are only used to sign. To query account data associated with a master or sub-account, pass the actual accountID of that account — API keys are not lookup identifiers. See Get account ID for how to retrieve your account ID.

Register a trading API key

Use two separate wallets: the master wallet authorizes registration, and the API key wallet signs subsequent orders. The registered publicKey is the API key wallet's EVM address, not its private key. Keep both private keys local and never put them in source control or logs.

Create a dedicated EVM key pair using your wallet or key-management tooling and store its private key securely as SODEX_API_KEY_PRIVATE_KEY. Choose a key name matching ^[0-9a-zA-Z_-]{1,36}$; default is reserved. If you already have a registered, unexpired trading key, verify it using the query below and skip registration.

Activate and fund your testnet trading account before running this example. It submits a real registration on Testnet (chain ID 138565).

This example registers an ordinary trading key without builder or permissions. It expires after 24 hours. Install the dependencies, save the code as register-api-key.ts, and configure the environment:

npm install viem tsx
export BASE_URL='https://testnet-gw.sodex.dev'
export USER_ADDRESS='YOUR_MASTER_WALLET_ADDRESS'
curl -sS "$BASE_URL/api/v1/perps/accounts/$USER_ADDRESS/state" \
  -H 'Accept: application/json'
# Use data.aid from the successful account-state response.
export ACCOUNT_ID='YOUR_ACCOUNT_ID'
export SODEX_API_KEY_NAME='quickstart-key'
# Set SODEX_MASTER_PRIVATE_KEY and SODEX_API_KEY_PRIVATE_KEY securely.
npx tsx register-api-key.ts

import { concatHex } from "viem";
import { privateKeyToAccount } from "viem/accounts";

async function main() {
  const accountID = Number(process.env.ACCOUNT_ID);
  const name = process.env.SODEX_API_KEY_NAME;
  const masterKey = process.env.SODEX_MASTER_PRIVATE_KEY;
  const apiKey = process.env.SODEX_API_KEY_PRIVATE_KEY;
  if (!Number.isSafeInteger(accountID) || accountID <= 0) {
    throw new Error("Set an exact account ID from account state; use an SDK for larger IDs");
  }
  if (!name || !/^[0-9a-zA-Z_-]{1,36}$/.test(name) || name === "default") {
    throw new Error("Set a valid, non-reserved API key name");
  }
  if (!masterKey || !apiKey) throw new Error("Set both local private keys");
  const master = privateKeyToAccount(masterKey as `0x${string}`);
  const tradingKey = privateKeyToAccount(apiKey as `0x${string}`);
  if (master.address === tradingKey.address) throw new Error("Use a separate trading key");
  const nonce = BigInt(Date.now());
  const expiresAt = Number(nonce) + 24 * 60 * 60 * 1000;
  const signature = await master.signTypedData({
    domain: { name: "universal", version: "1", chainId: 138565,
      verifyingContract: "0x0000000000000000000000000000000000000000" },
    types: { AddAPIKey: [
      { name: "accountID", type: "uint64" },
      { name: "name", type: "string" },
      { name: "keyType", type: "uint8" },
      { name: "publicKey", type: "bytes" },
      { name: "expiresAt", type: "uint64" },
      { name: "nonce", type: "uint64" },
    ] },
    primaryType: "AddAPIKey",
    message: { nonce, accountID: BigInt(accountID), name,
      keyType: 1, publicKey: tradingKey.address, expiresAt: BigInt(expiresAt) },
  });
  // Normalize viem's recovery byte (27/28) to the wire format (0/1).
  const recovery = Number.parseInt(signature.slice(-2), 16);
  const wireSignature = (signature.slice(0, -2) +
    (recovery >= 27 ? recovery - 27 : recovery).toString(16).padStart(2, "0")) as `0x${string}`;
  const response = await fetch(
    `https://testnet-gw.sodex.dev/api/v1/user/${master.address}/api-keys`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json", "Accept": "application/json",
        "X-API-Chain": "138565", "X-API-Nonce": nonce.toString(),
        "X-API-Sign": concatHex(["0x02", wireSignature]),
      },
      body: JSON.stringify({ accountID, name, type: 1,
        publicKey: tradingKey.address, expiresAt }),
    },
  );
  const result = await response.json();
  if (!response.ok || result.code !== 0) {
    throw new Error(result.error ?? `Registration failed: HTTP ${response.status}`);
  }
  console.log("Registration accepted; query API keys before placing an order.");
}

main().catch((error) => { console.error(error.message); process.exitCode = 1; });

Registration uses the master wallet, the universal domain, and signature prefix 0x02. The EIP-712 message calls the key type keyType, while the HTTP body calls it type. The nonce belongs in both the signed message and the header, not the HTTP body. See Add API Key signing for the original structures.

Confirm registration

Use the same master wallet address, account ID, and key name:

curl -sS --get "$BASE_URL/api/v1/user/$USER_ADDRESS/api-keys" \
  --data-urlencode "accountID=$ACCOUNT_ID" \
  --data-urlencode "name=$SODEX_API_KEY_NAME" \
  -H 'Accept: application/json'

Check code == 0, then confirm the key's name, publicKey, and future expiresAt in both data.spot and data.perps. Registration succeeds only when both engines accept it; indexed queries may lag. If the response is ambiguous or the key is not visible yet, query again before retrying registration. Do not trade until the key appears for the intended account in both engines.

Keep SODEX_API_KEY_NAME and SODEX_API_KEY_PRIVATE_KEY for trading; the master private key is not needed for orders. See Sodex nonces for nonce coordination and Revoke API Key when rotating or retiring a key.

Sodex nonces

Similar to Hyperliquid, on Sodex the 100 highest nonces are stored per signing address. Every new transaction must have a nonce larger than the smallest nonce in this set and must never have been used before.

Nonces are tracked per signing address:

• For trading actions signed by an API key, this is the API key's public key (EVM address) — the one you registered via addAPIKey. Direct master-wallet signing uses the master wallet's address instead.

• For addAPIKey / revokeAPIKey, this is the master wallet's address, which has its own independent nonce counter.

Nonces must be within (T - 2 days, T + 1 day), where T is the Unix millisecond timestamp on the block of the transaction.

The following steps may help port over an automated strategy from a centralized exchange:

1. Use a separate API key per trading process. Nonces are tracked per signing address (see above), so two sub-accounts that both sign with the same API key share a single nonce tracker — concurrent strategies on each sub-account will race on the nonce. Create one API key per sub-account to avoid this.

2. The trading logic tasks send orders and cancels to the batching task.

3. For each batch of orders or cancels, fetch and increment an atomic counter that ensures a unique nonce for the address. The atomic counter can be fast-forwarded to current Unix milliseconds if needed.

This structure is robust to out-of-order transactions within 2 seconds, which should be sufficient for an automated strategy geographically near an API server.

Signing requests

Authentication & Signing