# 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](/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.

```ts
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](/tools/typescript-sdk/deep-dives/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.

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

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

```ts
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**.

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

```ts
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](/tools/typescript-sdk/reference/margin) — margin account details and borrow rates (separate from perpetuals margin)
- [Market Data: Networks & Derivatives](/tools/typescript-sdk/reference/market-data/networks-and-derivatives) — public funding-amount data
- [Data Types](/tools/typescript-sdk/deep-dives/data-types) — decimal strings and bigint handling
- [Error Handling](/tools/typescript-sdk/errors) — error types and metadata