Accounts & trading modes

Carbon's account model has one more level than a typical exchange. Get it right and balances, permissions, and isolation all fall into place.

The three levels

Level	Identifier	What it is
Account	wallet address	Your owner identity — the wallet that signs in. Holds no positions itself.
Subaccount	subaccountAddress	An on-chain PartyA. Positions live here. One wallet can own many.
Virtual Account (VA)	VA address	A margin-isolated container inside a subaccount, for isolated (tradfi) positions.

Almost every trading and balance endpoint takes a subaccountAddress, not your wallet — the wallet authorizes, the subaccount trades.

Discover accounts with GET /v1/accounts/subaccounts, balances with /v1/accounts/subaccount/balance, and isolated VAs with /v1/accounts/subaccount/isolated-vas.

Crypto vs tradfi

A subaccount trades in one mode, which fixes the margin model and which positions are allowed:

	Crypto	TradFi
Margin	Cross — one shared pool backs all positions	Isolated — each position has its own margin
Allowed	Cross only	Isolated only
Container	Subaccount	Virtual Account per position/group
Risk	Shared; liquidation considers the whole subaccount	Ring-fenced per VA

Hard rule today: crypto = only cross, tradfi = only isolated. No mixing.

Cross (crypto)

All positions draw from the shared pool. Open one by simply not isolating:

POST /v1/trade/create-position
{ "subaccountAddress": "0x…", "chainId": 42161, "marketId": 1,
  "positionType": "LONG", "orderType": "MARKET", "quantity": 1, "leverage": 10 }

Isolated (tradfi)

Each position gets its own VA with dedicated margin:

POST /v1/trade/create-position
{ "subaccountAddress": "0x…", "chainId": 42161, "marketId": 1,
  "positionType": "LONG", "orderType": "MARKET", "quantity": 1, "leverage": 10,
  "isolate": true, "isolationType": "POSITION" }

isolationType groups risk by POSITION, MARKET, MARKET_LONG, or MARKET_SHORT. The VA is funded from its parent subaccount's free balance; move margin with POST /v1/trade/add-margin and /remove-margin.

Allocated vs free balance

A subaccount's collateral sits in one of two buckets:

Bucket	Field	What it's for
Allocated	allocatedBalance	The cross margin pool. Counts toward equity and backs cross positions.
Free (deallocated)	freeBalance	Uncommitted collateral. This is what isolated VAs are funded from.

Deposits default to the bucket that matches the subaccount's mode:

• Crypto deposits land in the allocated balance — ready for cross trading.

• TradFi deposits land in the free (deallocated) balance — ready to fund isolated positions.

Move funds between the two with the Instant Layer collateral endpoints:

// free → allocated: make funds usable as cross margin
POST /v1/instant-layer/allocate
{ "subaccountAddress": "0x…", "chainId": 42161, "amountWei": "1000000000000000000" }

// allocated → free: make funds available for isolated positions
POST /v1/instant-layer/deallocate
{ "subaccountAddress": "0x…", "chainId": 42161, "amountWei": "1000000000000000000" }

Amounts are collateral wei (1e18) as decimal strings. allocate requires the OPEN_POSITION permission, deallocate requires CLOSE_POSITION. Deallocating is solvency-checked (the API obtains the required signature for you), so it fails if it would leave open cross positions under-margined. Both execute through the Instant Layer, so the subaccount must be enabled for API access first — see Enabling API access.

Trading a subaccount over the API

Owning a subaccount isn't enough — it must be enabled for API access and your API key must be granted permissions before it can trade. This one-time setup (via the Carbon app or the API) is covered in its own page: Enabling API access.