A position is the net result of your fills in one perpetual market. The exchange
builds it from your trades, charges funding against it, and checks it against
margin requirements on every increasing trade.
Positions, leverage, and funding all attach to a portfolio, identified by its
PortfolioId triple. See
Accounts, subaccounts, and portfolios
for the hierarchy.
Positions
A position is a signed size plus an average entry price, updated trade by trade.
There is one position per perpetual market per portfolio. Adding to a position
moves its average entry price; reducing or reversing it realizes profit or loss.
Size is signed: positive is long, negative is short — the same convention
order quantity uses (see
Orders and time-in-force).
Read positions with GET /api/v1/positions. Optional portfolio_index and
market query parameters narrow the result. Each PositionResponse carries:
| Field | Meaning |
|---|
side | LONG or SHORT. |
quantity | Position size in base-asset units. |
avg_entry_price | Average entry price in USDC. |
net_funding | Funding accrued against this position, in USDC. |
<ASSET>-PERP, quoted in USDC. The
tradeable markets are BTC-PERP, ETH-PERP, SOL-PERP, XRP-PERP,
UNI-PERP, and AAVE-PERP. For symbols, asset scales, and human-to-wire
conversion, see
Markets, assets, and precision.
Spot markets are not yet available: no spot positions, and spot deposit and
withdraw are stubbed.
Margin type
Each portfolio has a margin type fixed at creation: Isolated or
Cross. Isolated portfolios margin each position against its own allocated
collateral; cross portfolios share collateral across positions in that
portfolio. The margin type cannot be changed after creation — open a separate
portfolio to use a different one.
Collateral never crosses portfolio boundaries. A position in one portfolio is
never backed by cash or positions in another. Use separate portfolios to isolate
strategies and risk. See Collateral and cash
for how USDC backs a position.
Leverage
Leverage is set per (portfolio, market) pair — there is no single
account-wide leverage value.
| Operation | Endpoint |
|---|
| List leverage settings for a portfolio | GET /api/v1/leverage |
| Set leverage for one market | PUT /api/v1/leverage |
SetLeverageRequest carries subaccount_index, portfolio_index, market
(for example BTC-PERP), and leverage (an integer multiplier).
The accepted range is 1 to 100 inclusive. A value outside that range returns
400 Bad Request.
Leverage is a client-side preference; the exchange’s margin requirements are
authoritative. A trade that increases a position is accepted only if your
post-trade equity covers the post-trade initial margin requirement, regardless
of the leverage you stored. Trades that reduce a position are always allowed.
A high leverage setting does not guarantee a trade will be accepted. Margin,
not leverage, decides.
Funding
Perpetuals have no expiry, so funding payments keep the perpetual price tethered
to the underlying. Funding is charged periodically against your open position and
settled in USDC cash.
Sign convention
When the funding rate is positive, longs pay shorts. When it is negative,
shorts pay longs.
- Long position, positive rate: you pay. Your cash decreases.
- Short position, positive rate: you receive. Your cash increases.
The payment field follows this directly: positive means received, negative
means paid.
Reading funding
Funding history
Accrued per position
GET /api/v1/funding-payments returns funding payments newest first,
paginated. The limit query parameter ranges from 1 to 1000 and defaults to
100. Each FundingPaymentResponse carries market, position_size (signed,
base-asset units), funding_rate (decimal string), payment (signed USDC),
and time.
PositionResponse.net_funding reports the funding accrued against the
current open position, in USDC. Read it from GET /api/v1/positions.
10⁻⁴ USDC), so a market’s funding is
not exactly zero-sum. The rounding residual is at most one ten-thousandth of a
dollar per position per settlement.
Liquidation and auto-deleverage
Liquidation surfaces through portfolio status, not a separate notification.
A portfolio is in one of three states:
| Status | Meaning |
|---|
ACTIVE | Normal trading. |
IN_LIQUIDATION | The exchange is unwinding the portfolio’s positions. |
CLOSED | The portfolio is closed. |
PortfolioBalanceResponse.status via
GET /api/v1/portfolio/balance.
When a position closes, its close reason records how it ended: OPEN, CLOSED,
LIQUIDATED, or AUTO_DELEVERAGED. LIQUIDATED means the exchange unwound the
position to restore margin; AUTO_DELEVERAGED means it was reduced to offset a
counterparty’s liquidation.
You cannot close a portfolio while it is IN_LIQUIDATION. Top up collateral or
reduce positions before equity falls below the maintenance margin requirement.
