Copy page

API Reference

TypeScript SDK — Perpetuals Reference

Methods for perpetual-contract positions, margin, risk statistics, and funding payment history. All methods are on client.perpetuals.

See the API Specifications for full request/response schemas.

Positions & Margin

getAccountMargin

POST /v1/margin · Authenticated

Retrieve the perpetuals margin summary for a symbol — margin assets value, initial margin, available margin, and liquidation information.

Code
const margin = await client.perpetuals.getAccountMargin({
  symbol: "BTC-GUSD-PERP",
});

console.log(margin.margin_assets_value);  // account margin asset value (decimal string)
console.log(margin.initial_margin);       // margin in use (decimal string)
console.log(margin.available_margin);     // available margin (decimal string)
console.log(margin.leverage);             // leverage ratio (decimal string)
console.log(margin.buying_power);         // buying power (decimal string)

Note: This is a POST mutation and is not automatically retried.

Tip: All margin values are decimal strings. See Data Types.

getOpenPositions

POST /v1/positions · Authenticated

Retrieve all open perpetual-contract positions on the account. The response wraps the positions array in an openPositions field.

Code
const result = await client.perpetuals.getOpenPositions({});

for (const pos of result.openPositions ?? []) {
  console.log(pos.symbol);          // e.g. "btcgusdperp"
  console.log(pos.quantity);        // position size (decimal string, negative for shorts)
  console.log(pos.average_cost);    // average entry price (decimal string)
  console.log(pos.unrealised_pnl);  // unrealized P&L (decimal string)
  console.log(pos.mark_price);      // current mark price (decimal string)
}

Note: This is a POST mutation and is not automatically retried.

getRiskStats

GET /v1/riskstats/{symbol} · Public

Retrieve risk statistics for a specific perpetual symbol — mark price, index price, and open interest.

Code
const stats = await client.perpetuals.getRiskStats({ symbol: "BTCGUSDPERP" });

console.log(stats.product_type);            // "PerpetualSwapContract"
console.log(stats.mark_price);              // current mark price (decimal string)
console.log(stats.index_price);             // index price (decimal string)
console.log(stats.open_interest);           // open interest (decimal string)
console.log(stats.open_interest_notional);  // open interest notional (decimal string)

Auto-retried. This is a GET endpoint — the SDK automatically retries on 429, 502, 503, and 504.

Public endpoint. No authentication required. The symbol path parameter is passed as a top-level field.

Funding

listFundingPayments

POST /v1/perpetuals/fundingPayment · Authenticated

Retrieve funding payments for your perpetual positions. Supports optional since and to query parameters to filter by time range. Each payment wraps a hourlyFundingTransfer object with the transfer details.

Code
const payments = await client.perpetuals.listFundingPayments({
  query: {
    since: 1700000000000n,
    to: 1700100000000n,
  },
  body: {},
});

for (const payment of payments) {
  console.log(payment.eventType);  // "Hourly Funding Transfer"
  const transfer = payment.hourlyFundingTransfer;
  console.log(transfer.assetCode);             // e.g. "GUSD"
  console.log(transfer.action);                // "Credit" or "Debit"
  console.log(transfer.quantity.currency);      // e.g. "GUSD"
  console.log(transfer.quantity.value);         // funding amount (decimal string)
  console.log(transfer.instrumentSymbol);       // e.g. "BTCGUSDPERP"
}

Note: This is a POST mutation and is not automatically retried.

Input pattern. This method takes an input object with query (optional) and body keys, because the endpoint has both query parameters and a request body. The since and to query parameters are int64 timestamps — the SDK accepts both bigint and number.

getFundingPaymentReportFile

GET /v1/perpetuals/fundingpaymentreport/records.xlsx · Authenticated

Download a funding payment report as an Excel spreadsheet file. Returns raw bytes, not JSON.

Code
const report = await client.perpetuals.getFundingPaymentReportFile({
  query: {
    fromDate: "2024-01-01",
    toDate: "2024-01-31",
    numRows: 100,
  },
});

// report.bytes is a Uint8Array containing the .xlsx file
// report.contentType is "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
// report.contentDisposition contains the suggested filename

import { writeFile } from "node:fs/promises";
await writeFile("funding-report.xlsx", report.bytes);

Returns a file, not JSON. The response is a RestFileResponse with bytes: Uint8Array, contentType?: string, and contentDisposition?: string.

Auto-retried. This is a GET endpoint — the SDK automatically retries on transient errors.

All query parameters are optional. Omit them to get a default report.

getFundingPaymentReportJson

POST /v1/perpetuals/fundingpaymentreport/records.json · Authenticated

Retrieve funding payment report data as JSON. Same data as getFundingPaymentReportFile but in a structured JSON format.

Code
const report = await client.perpetuals.getFundingPaymentReportJson({
  query: {
    fromDate: "2024-01-01",
    toDate: "2024-01-31",
  },
  body: {},
});

for (const record of report) {
  console.log(record.eventType);            // "Hourly Funding Transfer"
  console.log(record.assetCode);            // e.g. "GUSD"
  console.log(record.action);               // "Credit" or "Debit"
  console.log(record.quantity.currency);     // e.g. "GUSD"
  console.log(record.quantity.value);        // funding amount (decimal string)
  console.log(record.instrumentSymbol);      // e.g. "BTCGUSDPERP"
}

Note: This is a POST mutation and is not automatically retried.

Input pattern. This method takes query (optional) and body keys.

What's next

• Margin Reference — margin account details and borrow rates (separate from perpetuals margin)
• Market Data: Networks & Derivatives — public funding-amount data
• Data Types — decimal strings and bigint handling
• Error Handling — error types and metadata