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_CONSTRAINTSin 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:
| Message | From | To |
|---|---|---|
MsgDepositToSubaccount | the wallet (sender) | a subaccount (recipient: owner and number) |
MsgWithdrawFromSubaccount | a subaccount (sender) | a wallet (recipient, any address) |
MsgCreateTransfer | a subaccount | another 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...# node, wallet, address: as in the order examples (Placing and cancelling orders)
from dydx_v4_client.node.message import subaccount
await node.deposit(wallet, address, subaccount(address, 1), 0, 100_000_000) # $100 in
await node.withdraw(wallet, subaccount(address, 1), address, 0, 50_000_000) # $50 back to the walletdydxprotocold tx sending deposit-to-subaccount KEY dydx1... 1 100000000 \
--from KEY --chain-id firstaccess-testnet-1 --node https://rpc.testnet.firstaccess.exchange:443 \
--gas auto --gas-adjustment 1.5 --gas-prices 25000000000adv4tntReading 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.../1A 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).