Skip to main content
Use account reads to turn Perps activity into a reliable local view of account health, trading history, and performance.
Account management workflows require an authenticated session.

​
Review Account Health

Start with the account’s current collateral and exposure when showing portfolio health or checking whether a trade fits the account’s risk state.

​
Balances

Use balances to show collateral by asset and account value. 
const balances = await session.fetchBalances();
Use this shape to render collateral balances and account value by asset.
type PerpsBalance = {
  asset: string;
  balance: string;
  value: string;
};

type Output = PerpsBalance[];

​
Portfolio

Use the portfolio to show open positions, margin usage, withdrawable collateral, and liquidation state. 
const portfolio = await session.fetchPortfolio();
Use this shape to render positions, margin usage, and liquidation state.
type PerpsPortfolio = {
  positions: Array<{
    instrumentId: number;
    symbol: string;
    size: string;
    entryPrice: string;
    leverage: number;
    cross: boolean;
    initialMargin: string;
    maintenanceMargin: string;
    positionValue: string;
    liquidationPrice: string;
    unrealizedPnl: string;
    returnOnEquity: string;
    cumulativeFunding: string;
  }>;
  margin: {
    totalAccountValue: string;
    totalInitialMargin: string;
    totalMaintenanceMargin: string;
    totalPositionValue: string;
  };
  withdrawable: string;
  inLiquidation: boolean;
  timestamp: number;
};

type Output = PerpsPortfolio;

​
Account Stats

Use account stats to review trailing 7-day trading activity such as volume and maker share. Stats are cached by UTC day and may be stale by up to 24 hours. See Fee Metrics for what each metric means. 
const stats = await session.fetchStats();
Use this shape to render trailing 7-day volume and maker-share activity.
type PerpsAccountStats = {
  volume7d: string;
  takerVolume7d: string;
  makerVolume7d: string;
  accountMakerShare7d: string;
  entityMakerShare7d?: string;
  entityId?: number;
  entityName?: string;
};

​
Reconcile Orders and Fills

Use order state and fills to connect submitted orders with resting liquidity, executions, fees, and exposure changes.

​
Open Orders

Use open orders to show what is still resting on the book. 
const openOrders = await session.fetchOpenOrders({
  instrumentId: instrument.id,
});
Use this shape to render resting orders that can still fill or be canceled.
[
  {
    "id": 1234567890,
    "instrumentId": 1,
    "buy": true,
    "price": "65000",
    "quantity": "0.01",
    "timeInForce": "gtc",
    "postOnly": false,
    "status": "open",
    "restingQuantity": "0.01",
    "filledQuantity": "0",
    "createdTimestamp": 1767000010000,
    "updatedTimestamp": 1767000010000
  }
]

​
Orders

Use orders to inspect the latest known state for submitted orders. 
const orders = await session.fetchOrders({
  instrumentId: instrument.id,
});
Use this shape to reconcile submitted orders with their latest known state.
[
  {
    "id": 1234567890,
    "instrumentId": 1,
    "buy": true,
    "price": "65000",
    "quantity": "0.01",
    "timeInForce": "ioc",
    "postOnly": false,
    "status": "filled",
    "restingQuantity": "0",
    "filledQuantity": "0.01",
    "createdTimestamp": 1767000010000,
    "updatedTimestamp": 1767000010500
  }
]

​
Fills

Use fills to reconcile executions, fees, realized PnL, and exposure changes. 
const fills = session.listFills({
  start: Date.now() - 24 * 60 * 60 * 1000,
  end: Date.now(),
});

for await (const page of fills) {
  // page.items: PerpsAccountFill[]
}
Each page returns execution records you can use to reconcile fees, PnL, and exposure.
[
  {
    "tradeId": 987654321,
    "orderId": 1234567890,
    "instrumentId": 1,
    "side": "long",
    "price": "65000",
    "quantity": "0.01",
    "taker": true,
    "fee": "0.13",
    "feeAsset": "pUSD",
    "previousSize": "0",
    "previousEntryPrice": "0",
    "pnl": "0",
    "liquidation": false,
    "timestamp": 1767000010500,
    "hash": "0x1111111111111111111111111111111111111111111111111111111111111111"
  }
]

​
Reconcile Funding and Transfers

Funding, deposits, and withdrawals explain collateral changes that did not come from order fills. Use Fund Your Account for deposit and withdrawal submission workflows.

​
Funding Payments

Use funding payments to explain periodic funding debits or credits for a market. 
const fundingPayments = session.listFundingPayments({
  instrumentId: instrument.id,
});

for await (const page of fundingPayments) {
  // page.items: PerpsAccountFundingPayment[]
}
Each page returns funding records you can use to explain non-trade PnL changes.
[
  {
    "instrumentId": 1,
    "size": "0.01",
    "fundingRate": "0.0001",
    "fundingAsset": "pUSD",
    "funding": "0.05",
    "timestamp": 1767000010000
  }
]

​
Deposits

Use deposits to reconcile collateral added to the Perps account. 
const deposits = session.listDeposits();

for await (const page of deposits) {
  // page.items: PerpsDeposit[]
}
Each page returns deposits you can match against collateral arriving in the account.
[
  {
    "hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "asset": "pUSD",
    "amount": "100000000",
    "status": "confirmed",
    "from": "0x1234567890abcdef1234567890abcdef12345678",
    "to": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "confirmations": 12,
    "requiredConfirmations": 12,
    "createdTimestamp": 1767000010000,
    "confirmedTimestamp": 1767000030000
  }
]

​
Withdrawals

Use withdrawals to reconcile collateral leaving the Perps account. 
const withdrawals = session.listWithdrawals();

for await (const page of withdrawals) {
  // page.items: PerpsWithdrawal[]
}
Each page returns withdrawals you can match against collateral leaving the account.
[
  {
    "withdrawalId": 1234567891,
    "asset": "pUSD",
    "amount": "50000000",
    "fee": "1.5",
    "status": "confirmed",
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "hash": "0x3333333333333333333333333333333333333333333333333333333333333333",
    "confirmations": 12,
    "requiredConfirmations": 12,
    "createdTimestamp": 1767000010000,
    "confirmedTimestamp": 1767000030000
  }
]

​
Track Equity and PnL

Use equity and PnL history to explain how the account’s value changed over time.

​
Equity

Use equity history to chart account value over time. 
const equity = session.listEquityHistory({
  interval: "1h",
  start: Date.now() - 7 * 24 * 60 * 60 * 1000,
  end: Date.now(),
});

for await (const page of equity) {
  // page.items: PerpsEquityPoint[]
}
Each page returns points you can plot as account equity over time.
[
  {
    "timestamp": 1767000000000,
    "equity": "1000"
  }
]

​
PnL

Use PnL history to chart account profit and loss over the same interval. 
const pnl = session.listPnlHistory({
  interval: "1h",
  start: Date.now() - 7 * 24 * 60 * 60 * 1000,
  end: Date.now(),
});

for await (const page of pnl) {
  // page.items: PerpsPnlPoint[]
}
Each page returns points you can plot as account PnL over time.
[
  {
    "timestamp": 1767000000000,
    "pnl": "12.5"
  }
]