# TypeScript SDK — Margin Reference

Methods for querying margin account status, borrow rates, and previewing margin orders. All methods are on `client.margin`.

Every method in this namespace is a **POST mutation** — the SDK will **not** automatically retry on failure.

See the [API Specifications](/api-specifications) for full request/response schemas.

### getMarginAccount

`POST /v1/margin/account` · Authenticated

Retrieve your margin account summary — collateral, leverage, buying/selling power, and liquidation risk. The response is a `MarginAccountSummary` where monetary fields are `MoneyAmount` objects with `currency` and `value` properties. Requires the **Trader**, **Fund Manager**, or **Auditor** role. OAuth scope: `balances:read`. For Master API keys, include the `account` field in the request body to target a specific sub-account.

```ts
const account = await client.margin.getMarginAccount({});

console.log(account.marginAssetValue.value);     // total margin asset value (decimal string)
console.log(account.marginAssetValue.currency);   // e.g. "USD"
console.log(account.availableCollateral.value);   // available collateral (decimal string)
console.log(account.leverage);                    // leverage ratio (decimal string)
console.log(account.buyingPower.value);           // buying power (decimal string)
console.log(account.sellingPower.value);          // selling power (decimal string)
```

> **Tip:** Monetary fields (`marginAssetValue`, `availableCollateral`, `notionalValue`, `totalBorrowed`, `buyingPower`, `sellingPower`, `reservedBuyOrders`, `reservedSellOrders`) are `MoneyAmount` objects with `.currency` and `.value` (decimal string). The `leverage` field is a plain decimal string. See [Data Types](/tools/typescript-sdk/deep-dives/data-types).

### getMarginRates

`POST /v1/margin/rates` · Authenticated

Retrieve current margin borrow rates for all eligible currencies. Requires the **Trader**, **Fund Manager**, or **Auditor** role. OAuth scope: `balances:read`.

```ts
const result = await client.margin.getMarginRates({});

for (const rate of result.rates) {
  console.log(rate.currency);          // e.g. "BTC", "USD"
  console.log(rate.borrowRate);        // hourly borrow rate (decimal string)
  console.log(rate.borrowRateDaily);   // daily borrow rate (decimal string)
  console.log(rate.borrowRateAnnual);  // annual borrow rate (decimal string)
  console.log(rate.lastUpdated);       // timestamp (bigint)
}
```

> **Caveat:** The `lastUpdated` field in each rate entry is a `bigint` timestamp. The SDK deserializes it automatically.

> **Tip:** Borrow rates are **decimal strings**. Three granularities are provided: hourly (`borrowRate`), daily (`borrowRateDaily`), and annual (`borrowRateAnnual`).

### previewMarginOrder

`POST /v1/margin/order/preview` · Authenticated

Preview the margin impact of a hypothetical order before placing it. Returns pre-order and post-order risk statistics as `MarginRiskStats` objects, allowing you to see how the order would affect your margin account.

```ts
const preview = await client.margin.previewMarginOrder({
  symbol: "btcusd",
  amount: "0.5",
  price: "50000.00",
  side: "buy",
  type: "limit",
});

// Before the order
console.log(preview.preorder.marginAssetValue.value);     // current margin asset value
console.log(preview.preorder.availableCollateral.value);   // current available collateral
console.log(preview.preorder.leverage);                    // current leverage

// After the order (projected)
console.log(preview.postorder.marginAssetValue.value);     // projected margin asset value
console.log(preview.postorder.availableCollateral.value);   // projected available collateral
console.log(preview.postorder.leverage);                    // projected leverage
```

> **Tip:** Use this before `client.trading.createNewOrder()` to understand the margin impact of a trade. The preview does not place any order or reserve any margin.

> **Tip:** Both `preorder` and `postorder` are `MarginRiskStats` objects. While they share the same monetary field pattern (`MoneyAmount` objects with `.currency` and `.value`), `MarginRiskStats` is a distinct type from `MarginAccountSummary` — the set of fields may differ. Check the [API Specifications](/api-specifications) for the exact schema.

## What's next

- [Perpetuals Reference](/tools/typescript-sdk/reference/perpetuals) — perpetual-contract margin and positions (separate margin system)
- [Trading: Order Lifecycle](/tools/typescript-sdk/reference/trading/order-lifecycle) — place orders after previewing
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — decimal strings and bigint handling
- [Error Handling](/tools/typescript-sdk/errors) — error types and metadata