API Reference

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 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.


Code
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.

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.


Code
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.


Code
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 for the exact schema.

What's next

Perpetuals Reference — perpetual-contract margin and positions (separate margin system)
Trading: Order Lifecycle — place orders after previewing
Data Types — decimal strings and bigint handling
Error Handling — error types and metadata

Last modified on August 14, 2026

Perpetuals WebSocket

Code

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)

Code

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)
}

Code

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