> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aultblockchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Margin Trading API

> [!NOTE]
>
> **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](https://docs.aultblockchain.com/ault-dex/margin-trading.md) 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](https://docs.aultblockchain.com/dex-api/getting-started/pagination.md).

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.

```bash theme={null}
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](https://docs.aultblockchain.com/dex-api/rest/orders.md) and [fills](https://docs.aultblockchain.com/dex-api/rest/user-fills.md). 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.

> [accordion] Params
>
> | Field | JSON type |
> | - | - |
> | `enabled` | boolean |
> | `marginLendingPoolId` | string or null |
> | `marginCallBar` | string |
> | `forceLiquidationBar` | string |
> | `indexedHeight` | number |

> [accordion] 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 |

> [accordion] Account
>
> | Field | JSON type |
> | - | - |
> | `address` | string |
> | `owner` | string |
> | `marginMode` | string |
> | `marketId` | string or null |
> | `symbol` | string or null |
> | `collateralsInOrder` | array of Coin |

> [accordion] Accounts
>
> | Field | JSON type |
> | - | - |
> | `accounts` | array of Account |
> | `asOf` | number |
> | `indexedHeight` | number |

> [accordion] 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 |

> [accordion] Positions
>
> | Field | JSON type |
> | - | - |
> | `positions` | array of PositionSummary |
> | `asOf` | number |
> | `indexedHeight` | number |

> [accordion] PositionAsset
>
> | Field | JSON type |
> | - | - |
> | `denom` | string |
> | `total` | string |
> | `used` | string |
> | `free` | string |
> | `maxTransferable` | string or null |
> | `debt` | string |

> [accordion] 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 |

> [accordion] 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 |

> [accordion] Activity
>
> | Field | JSON type |
> | - | - |
> | `activity` | array of ActivityEntry |

> [accordion] Coin
>
> | Field | JSON type |
> | - | - |
> | `denom` | string |
> | `amount` | string |

> [accordion] 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 |

> [accordion] Liquidations
>
> | Field | JSON type |
> | - | - |
> | `liquidations` | array of Liquidation |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.