Margin Trading API

Testnet-Only. Use https://test-dex-api.cloud.aultblockchain.xyz for these endpoints and the matching Testnet chain for signed actions. This product is not available on Mainnet.

These endpoints describe leveraged Spot accounts backed by Lending. They are separate from Perp margin. Read Margin Trading for the product rules.

Routes

All routes use GET under /api/v1/margin.

Suffix	Optional query	Body
`/params`	None	`Params`
`/markets`	`market_id` or `symbol`	`Market[]`
`/accounts/{owner}`	`market_id` or `symbol`, `margin_mode`	`{accounts, asOf, indexedHeight}`
`/accounts/{owner}/positions`	Same account filters	`{positions, asOf, indexedHeight}`
`/positions/{address}`	None	`Position`
`/activity`	Required `owner` or `account`; optional `type`, `denom`, `since`, `limit`, `cursor`	`{activity}`
`/liquidations`	Required `owner` or `account`; optional `since`, `limit`, `cursor`	`{liquidations}`

market_id is hex and takes precedence over symbol. symbol is a Spot BASE/QUOTE pair. margin_mode is cross or isolated. owner identifies the wallet; address and account identify a derived Margin account. Use discovery results unchanged. Repeat type to select activity categories: deposit, withdraw, reservation, borrow.auto, borrow.manual, repay.settlement, repay.cancel, repay.manual, repay.skipped, settlement, forceCancel. Both feeds accept paired legacy before_height/before_index; prefer the opaque cursor. Invalid filters or no owner/account on a feed return 400. A missing position returns 404. Health dependencies can return 503, or a response can retain its balances while returning null valuation fields and healthError.

Balances and derived risk

Per-denom total, used, free, debt and maxTransferable are raw base-unit strings. free = total - used is unreserved collateral, not a safe withdrawal estimate. maxTransferable applies the API’s indexed borrow-capacity calculation and is capped by free. With debt it is null if health cannot be priced; a debt-free account can still report free collateral. It is not a transaction-execution guarantee. Debt includes accrued interest. Valuation totals retain the raw Lending amount/price scale; ratios and leverage are dimensionless. liquidationPrice is nullable and must not be treated as an executable closeout price. marginCallBar and forceLiquidationBar are API display configuration, not new on-chain liquidation thresholds. enabled and marginLendingPoolId describe indexed configuration. Market maxLeverageBuy and maxLeverageSell are side-specific calculations from the received asset’s Lending LTV and taker fee; maxLeverage is the smaller bound and can be null. These values are not Perp leverage tiers. Activity amount is signed for reservation changes, negative on release; after is the resulting reservation and is otherwise null. Liquidation records include seized/repaid coins, canceled order IDs and bad debt.

curl -fsS "$API_URL/api/v1/margin/accounts/$OWNER"
curl -fsS --get "$API_URL/api/v1/margin/activity" \
  --data-urlencode "owner=$OWNER" --data-urlencode 'type=reservation' \
  --data-urlencode 'limit=100'

Use the returned account address with Spot orders and fills. Margin-owned Spot orders can carry marginMode, marginOwner, autoRepay and autoRepayAtCancel decorations. No Margin-specific WebSocket channel is registered.

Response field reference

Types below describe JSON, not numeric units. See the unit notes above. Nullable values must not be replaced with zero.

Params

Field	JSON type
`enabled`	boolean
`marginLendingPoolId`	string or null
`marginCallBar`	string
`forceLiquidationBar`	string
`indexedHeight`	number

Market

Field	JSON type
`marketId`	string
`symbol`	string or null
`baseDenom`	string
`quoteDenom`	string
`marginEnabled`	boolean
`maxLeverage`	string or null
`maxLeverageBuy`	string or null
`maxLeverageSell`	string or null
`collateralDenoms`	array of string
`borrowableDenoms`	array of string

Account

Field	JSON type
`address`	string
`owner`	string
`marginMode`	string
`marketId`	string or null
`symbol`	string or null
`collateralsInOrder`	array of Coin

Accounts

Field	JSON type
`accounts`	array of Account
`asOf`	number
`indexedHeight`	number

PositionSummary

Field	JSON type
`address`	string
`owner`	string
`marginMode`	string
`marketId`	string or null
`symbol`	string or null
`collateralValue`	string or null
`debtValue`	string or null
`healthFactor`	string or null
`healthStatus`	string or null
`healthError`	string or null

Positions

Field	JSON type
`positions`	array of PositionSummary
`asOf`	number
`indexedHeight`	number

PositionAsset

Field	JSON type
`denom`	string
`total`	string
`used`	string
`free`	string
`maxTransferable`	string or null
`debt`	string

Position

Field	JSON type
`address`	string
`owner`	string
`marginMode`	string
`marketId`	string or null
`symbol`	string or null
`assets`	array of PositionAsset
`collateralValue`	string or null
`debtValue`	string or null
`borrowCapacity`	string or null
`liquidationCollateralValue`	string or null
`healthFactor`	string or null
`healthStatus`	string or null
`healthError`	string or null
`effectiveLeverage`	string or null
`liquidationPrice`	string or null
`oracleUpdatedAt`	number or null
`asOf`	number
`indexedHeight`	number

ActivityEntry

Field	JSON type
`type`	string
`account`	string
`owner`	string
`denom`	string or null
`amount`	string or null
`after`	string or null
`orderId`	string or null
`poolId`	string or null (optional)
`reason`	string or null (optional)
`blockHeight`	number
`blockTime`	number
`eventIndex`	number

Activity

Field	JSON type
`activity`	array of ActivityEntry

Coin

Field	JSON type
`denom`	string
`amount`	string

Liquidation

Field	JSON type
`liquidator`	string
`account`	string
`owner`	string
`poolId`	string
`repaid`	Coin
`seized`	Coin
`forceCanceledOrderIds`	array of string
`badDebt`	array of Coin
`blockHeight`	number
`blockTime`	number
`eventIndex`	number

Liquidations

Field	JSON type
`liquidations`	array of Liquidation

collateralsInOrder contains Coin objects with string denom and raw-unit string amount.

Getting Started

Spot REST API

Perpetual REST API (Testnet-Only)

Lending & Margin API (Testnet-Only)

Vaults & Oracle API (Testnet-Only)

WebSocket API

Trading Actions

Advanced

Routes

Balances and derived risk

Response field reference

​Routes

​Balances and derived risk

​Response field reference

Routes

Balances and derived risk

Response field reference