Skip to content
First Access Exchange

Accounts and subaccounts

Address and key

An account is a Cosmos address with the prefix dydx, from a secp256k1 key derived on the path m/44'/118'/0'/0/0 from a BIP-39 recovery phrase, as dYdX's CLI and clients derive it. The same phrase gives the same address everywhere.

An address has:

  • a wallet: its bank balances, USDC and the native token adv4tnt (18 decimals). The faucet and the bridge pay the wallet; transaction fees come out of it;
  • subaccounts, numbered 0 to 128,000: each holds USDC and positions, and every order belongs to one. Margin is computed per subaccount.

USDC is the chain's asset 0, with 6 decimals; read its denom from /dydxprotocol/assets/asset/0 rather than hard-coding it.

On the testnet it is ibc/2547906198C60129474CC58DEA82084E5B6D39E993D29E345D83925C2B988A7F: Circle's test USDC from Injective's testnet over the chain's IBC channel-0, credited as asset 0 directly (plain ICS-20; x/canonicalusdc is disabled). The faucet's USDC is the same denom (bridge).

One subaccount per chain market

Every chain market is isolated:

  • a subaccount holding a position in one chain market holds nothing else; an order that would open a second market's position in it is refused, and orders that would make it hold two are removed (ORDER_REMOVAL_REASON_VIOLATES_ISOLATED_SUBACCOUNT_CONSTRAINTS in the indexer);
  • a subaccount rests long-term orders on one chain-market book at a time.

So use one subaccount per market. The trading app uses subaccount perpetual id + 1 for each market (subaccount 0 unused); the number is derived, not stored, so the same key finds its positions on any device. Any other scheme works if each market gets its own subaccount.

Moving USDC

All three are x/sending messages, signed by the address, paying a gas fee:

MessageFromTo
MsgDepositToSubaccountthe wallet (sender)a subaccount (recipient: owner and number)
MsgWithdrawFromSubaccounta subaccount (sender)a wallet (recipient, any address)
MsgCreateTransfera subaccountanother subaccount, of any address

Each names the asset (asset_id 0, USDC) and the amount in quote quantums (micro-USDC). A withdrawal or transfer must leave the subaccount above its initial margin requirement. While a subaccount holds a company perpetual that is halted or settling, every deposit, withdrawal and transfer into or out of it is refused until its position is paid.

// client, subaccount: as in the order examples (Placing and cancelling orders)
await client.post.deposit(subaccount, 0, Long.fromNumber(100_000_000)); // $100 in
await client.post.withdraw(subaccount, 0, Long.fromNumber(50_000_000)); // $50 back to the wallet
await client.post.transfer(subaccount, 'dydx1...', 2, 0, Long.fromNumber(10_000_000)); // $10 to subaccount 2 of dydx1...

Reading balances

# The wallet's balances
curl -s https://api.testnet.firstaccess.exchange/cosmos/bank/v1beta1/balances/dydx1...
# One subaccount: its asset positions (USDC), perpetual positions and margin state
curl -s https://api.testnet.firstaccess.exchange/dydxprotocol/subaccounts/subaccount/dydx1.../1

A subaccount's asset_positions[].quantums is its USDC (negative for a leveraged long); perpetual_positions[].quantums is its signed size in contracts, with its funding index. The indexer adds equity, free collateral, entry prices and history (indexer API).