Skip to main content
A portfolio is your trading account on the exchange. It holds your cash and positions and carries its own margin type and leverage settings. Every order, deposit, withdrawal, and transfer targets a specific portfolio. The exchange nests trading in three levels, each one a unit of isolation: 
account
  └─ subaccount   (index 0, 1, 2, ...)
       └─ portfolio   (index 0, 1, 2, ...)

​
The portfolio

A portfolio is an independent margin and collateral bucket. It holds:
  • A cash balance — your USDC collateral. See Collateral and cash.
  • Positions — your open perpetuals exposure. See Positions, leverage, and funding.
  • A margin type — Isolated or Cross, fixed when the portfolio is created.
  • Leverage settings — configured per portfolio per market. One portfolio can run different leverage on BTC-PERP and ETH-PERP.
Cash and positions in one portfolio never back another. Each portfolio has its own cash_balance, and liquidation is tracked per portfolio. That isolation is the point: create separate portfolios and subaccounts to split strategies, contain risk, and mix margin types — say, one Isolated portfolio for a directional trade and one Cross portfolio for a hedged book, all under the same account.

​
PortfolioId

Every portfolio is identified by a triple: 
{
  "account_id": 12345,
  "subaccount_index": 0,
  "portfolio_index": 0
}
  • account_id — your account, a 64-bit unsigned integer.
  • subaccount_index — a 32-bit unsigned integer.
  • portfolio_index — a 32-bit unsigned integer.
This PortfolioId appears in request bodies and responses throughout the API. Its string display form is account_id:subaccount_index:portfolio_index. Indices are dense: they start at 0 and run 0..n with no gaps. Subaccount index 0 is the default subaccount, and portfolio index 0 is the default portfolio (named Main). To enumerate everything you own, walk 0..subaccount_count for subaccounts and 0..portfolio_count within each.

​
Creating subaccounts and portfolios

1

Create a subaccount

POST /api/v1/accounts/{account_id}/subaccount/createCreating a subaccount also creates its default (Main) portfolio. The response returns both the new subaccount_index and its main_portfolio_index.
2

Create an additional portfolio

POST /api/v1/accounts/{account_id}/portfolioPass a margin_type — 0 for Isolated, 1 for Cross. This is the only setting fixed at creation. The response returns the allocated portfolio_index and the portfolio’s default name (Portfolio N).
To list what exists, GET /api/v1/subaccounts returns one summary per subaccount, including its portfolio_count and total_cash (summed over non-closed portfolios). GET /api/v1/portfolio/cash_balances returns one balance per portfolio.

​
Status lifecycle

A portfolio has one of three statuses:
StatusMeaning
ACTIVENormal. The portfolio can trade and hold cash. New portfolios start here.
IN_LIQUIDATIONThe exchange is unwinding the portfolio. You cannot close or reopen it in this state.
CLOSEDRetired. No cash, positions, or resting orders.
Accounts and subaccounts use a separate two-state status, ACTIVE or CLOSED.

​
Closing a portfolio

POST /api/v1/portfolio/close with { subaccount_index, portfolio_index }. Clear cash, positions, and orders first.
A close request fails with 409 Conflict if the portfolio is already CLOSED, is IN_LIQUIDATION, has a non-zero cash balance (withdraw or transfer it out first), has open positions (close them first), or has resting orders (cancel them first). An unknown portfolio returns 404.

​
Reopening a portfolio

POST /api/v1/portfolio/reopen with { subaccount_index, portfolio_index }. Only a CLOSED portfolio can be reopened. It fails with 409 Conflict if the portfolio is already ACTIVE or is IN_LIQUIDATION. An unknown portfolio returns 404. For the full status-code catalog, see Error codes.