Credit & Margin
The margin model for a Native Core credit account — how positions are held, how available_usd_atoms is calculated, and what a resting order consumes.
A credit account trades against a USD credit line rather than a per-asset balance. Its margin headroom is available_usd_atoms, and an order is admitted only if that value is still >= 0 once the order is applied. This page specifies the model and the calculation.
It covers credit accounts only; a spot account is gated on its per-asset available balance, described in Account Types.
The position model
A credit account holds one signed position per asset, not a directional position per market.
net = pending_exposure_qty + actual_qtyBoth terms are in that asset's raw balance atoms, not display units; conversion uses balance_decimals, described in Decimals & Units.
The sign states which way the account stands in that asset. Positive means the account holds it, counting as collateral; negative means it owes it, counting as a liability. This page calls the two cases long and short. A fill moves two positions in opposite directions — the asset received rises, the asset paid falls — so an account buying ETH with USDC is long ETH and short USDC at once.
The sign is never replaced by the magnitude. It carries three consequences:
only a positive
netis haircut by LTV;the position adds or subtracts through ordinary signed addition;
division floors, so a negative value rounds away from zero. Valuing a short from
|net|and subtracting truncates toward zero instead, understating the liability.
Committed size and settled size
actual_qty is settled size; pending_exposure_qty is size a resting order has committed and not yet filled. Both count against the credit line on the same terms, and a fill converts one into the other, so the sum counts each unit once.
A resting order commits one asset, always as a debit:
ask
the market's base asset
the resting quantity, in base balance atoms
bid
the market's quote asset
the resting quantity's notional (price × quantity)
A bid commits the asset it would pay with, not the asset being acquired. The opposite leg appears in actual_qty only once a fill settles.
The calculation
summed over every position the account holds. With a fresh mark — one whose updated_height equals the query_height of the markPrices response it came in — value(net) is
credit_ltv is an integer percentage, so the * 100 divisor is part of the expression. LTV applies to longs only: a short is carried at full value, so a long and a short of equal notional do not offset. Both expressions floor, which rounds against the account on either side.
A stale or missing mark changes this. A long contributes 0; a stale short is marked up by a protocol haircut before valuation; a short with no mark cannot be valued, and the order is rejected. A stale mark can therefore only reduce headroom, never increase it.
Worked examples
Both examples use balance_decimals: 8 throughout, so 10^balance_decimals is 100000000, and a USDC mark of exactly 100000000 ($1.00). Fees are omitted.
A resting bid, from placement to fill
A $100,000 line, no positions, then a limit bid for 10 ETH at $3,500 — a notional of $35,000. ETH has credit_ltv: 85 and a mark of 350000000000.
net USDC
net ETH
available_usd_atoms
before
0
0
10000000000000
$100,000.00
order resting
-3500000000000
0
6500000000000
$65,000.00
fully filled
-3500000000000
1000000000
9475000000000
$94,750.00
Placement commits the quote asset only. pending_exposure_qty for USDC becomes the notional, and a negative net is carried at full value with no LTV:
ETH is untouched: its net stays 0, contributes nothing, and needs no mark.
The fill releases the pending exposure and books both settlement legs. USDC's pending returns +3500000000000 and its actual_qty takes -3500000000000, leaving net unchanged — a fill converts committed size into settled size. The ETH leg is new, and being long it is haircut:
The filled buy therefore costs $5,250.00 of headroom, or (100 - 85)% of notional. A credit account consumes headroom when it buys, not only when it sells short: the cost of holding a long is the part of its value that LTV does not return.
An account with three positions
A $100,000 line, two longs and a short, all marks fresh.
asset
net (atoms)
mark (usd_atoms)
credit_ltv
USDC
5000000000000
100000000
95
ETH
1000000000
350000000000
85
BTC
-50000000
7600000000000
85
That is $100,000.00 of credit, plus $47,500.00 and $29,750.00 of collateral after LTV, less $38,000.00 for the short: $139,250.00 of headroom.
The BTC row shows the long/short asymmetry. At credit_ltv: 85 the same 0.5 BTC held long would contribute $32,300; held short it costs the full $38,000.
If the BTC mark goes stale, the short is revalued upward by the haircut and headroom falls with no change in position. An account operating close to its limit can therefore fail the gate, and be frozen, as a result of oracle staleness alone.
Inputs
Four POST /info queries supply every term, each read against the owner address.
available_usd_atoms
the protocol's own result, as a JSON string, for comparison
actual_qty
settled size, signed raw atoms
updated_height
the block in which that mark was committed
query_height
response-level; the height freshness is tested against
balance_decimals
atom scale of that asset's balances
Last updated