> ## Documentation Index > Fetch the complete documentation index at: https://public-perps-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Account data shapes > Account, positions, orders, fills, and activity shapes returned by the SDK direct-to-provider reads Account-level reads — account summary, positions, orders, fills, activity, and single-order lookup — are served by the SDK directly from each provider via `@lifi/perps-sdk` (`getAccount`, `getPositions`, `getOrders`, `getFills`, `getActivity`, `getOrder`). They are not LI.FI HTTP endpoints. This page documents the data shapes those calls return. *** ## getAccount Returns the account summary including balances, margin, and fee tier. ```typescript theme={null} const account = await getAccount(client, { provider: 'hyperliquid', address: '0x1234...', }); ``` ### Parameters | Name | Type | Required | Description | | ---------- | -------- | -------- | --------------------- | | `provider` | `string` | Yes | Provider identifier | | `address` | `string` | Yes | User's wallet address | ### Shape ```json theme={null} { "provider": "hyperliquid", "address": "0x1234567890abcdef1234567890abcdef12345678", "balances": [ { "categoryId": "perps", "asset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }, "units": "10000.00", "valueUsd": "10000.00" } ], "collateralBalances": [ { "categoryId": "spot", "asset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" }, "units": "2500.00", "valueUsd": "2500.00" } ], "positions": [], "marginUsed": "2500.00", "unrealizedPnl": "150.00", "feeTier": { "maker": "0.0002", "taker": "0.0005" }, "config": { "provider": "hyperliquid", "abstractionMode": "unifiedAccount", "agents": [], "builderFeeApproval": { "builderAddress": "0x5678901234abcdef5678901234abcdef56789012", "maxFeeRate": "0.001", "approved": true } } } ``` ### AccountResponse fields | Field | Type | Description | | -------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `provider` | `string` | Provider identifier | | `address` | `string` | User's wallet address | | `balances` | `Balance[]` | Flat, non-collateral holdings. Each `Balance` is `{ categoryId, asset, units, valueUsd }`. | | `collateralBalances` | `Balance[]` | SDK-determined collateral subset (spot balances in a category's quote asset). | | `positions` | `Position[]` | Open positions the snapshot already computed; equals the unfiltered [getPositions](#getpositions) output. | | `marginUsed` | `string` | Total margin used across all positions | | `unrealizedPnl` | `string` | Total unrealized PnL across all positions | | `feeTier` | `FeeTier` | Maker and taker fee rates | | `config` | `AccountConfig` | Provider-specific account state — see [AccountConfig](#accountconfig) | ### AccountConfig Discriminated union of per-provider account configuration state. Narrow with `config.provider === ''` to access provider-specific fields. **Hyperliquid** (`provider: "hyperliquid"`): | Field | Type | Description | | -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | `"hyperliquid"` | Discriminator | | `abstractionMode` | `string \| null` | Active abstraction variant (e.g. `"unifiedAccount"`, `"dexAbstraction"`, `"disabled"`). `null` when abstraction has never been set — the widget falls back to the descriptor's `default` `ParamOption`. | | `agents` | `HyperliquidAgent[]` | Currently-authorised agent wallets. The `approveAgent` setup descriptor consults this to detect expiry. | | `builderFeeApproval` | `HyperliquidBuilderFeeApproval?` | Builder fee approval state. Absent when no builder is configured. | **Lighter** (`provider: "lighter"`): | Field | Type | Description | | ----------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | `"lighter"` | Discriminator | | `accountIndex` | `number` | L2 integer account identifier — used by the SDK for WASM signing and by the widget when rendering transfer counterparties | | `apiKeyIndex` | `number` | Slot the SDK has registered (or will register) the session API key in | | `apiKeyRegistered` | `boolean` | Whether a key is currently live in `apiKeyIndex`. The `registerApiKey` setup descriptor consults this to gate trading. | | `accountType` | `number` | Raw integer fee/latency tier from Lighter's `/api/v1/account.account_type`. Decoded to a human label by the widget once Lighter publishes the numeric→string mapping. | | `accountTradingMode` | `number` | Lighter `account_trading_mode`: `0` = Classic/Simple (segregated margin), `1` = Unified (cross-asset margin). Drives the `accountMode` options descriptor. | | `assetCollateral` | `LighterAssetCollateral[]` | Per-asset cross-margin collateral flags for held spot assets, each `{ assetId, enabled }`. Meaningful only when `accountTradingMode === 1`; assets whose `margin_mode` Lighter omits are not listed. | | `readOnlyTokenApproved` | `boolean` | Whether a read-only auth token is currently live. The `approveReadOnlyToken` client-side flow consults this to gate read access. | | `readOnlyTokenExpiry` | `number?` | Unix timestamp (seconds) at which the read-only token expires. Absent when no token is approved. | | `readOnlyTokenScope` | `'single' \| 'all'` | Scope of the approved read-only token. Absent when no token is approved. | | `referralPresent` | `boolean` | `true` when LI.FI's referral code is the one currently applied to the account. `false` when another integrator's code (or none) is applied, or when the SDK holds no code to compare against — keeping `setReferrer` gateable since Lighter referral is mutable. | **Ondo** (`provider: "ondo"`): | Field | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | `"ondo"` | Discriminator | | `loggedIn` | `boolean` | Whether a live login (auth) token is held | | `authTokenExpiry` | `number?` | Unix timestamp (seconds) at which the login token expires. Present if and only if `loggedIn === true`. The token itself never appears here. | | `termsAccepted` | `boolean` | Venue terms accepted, inferred from the login token's `newAccount` flag. Always `false` when logged out. | | `apiKeyRegistered` | `boolean` | A venue API key is present in local storage. Local presence only — venue-side validity is not verified. | | `referralSet` | `boolean` | A referral code (any referrer's) is already applied to the account. Always `false` when logged out. | The response `positions` array mirrors the unfiltered [getPositions](#getpositions) output. Orders are fetched separately: [getOrders](#getorders). **SDK:** [`getAccount()`](/sdk/account/get-account) *** ## getPositions Returns the user's open positions. Results are paginated. ```typescript theme={null} const result = await getPositions(client, { provider: 'hyperliquid', address: '0x1234...', }); ``` ### Parameters | Name | Type | Required | Description | | ---------- | --------- | -------- | -------------------------------------------------------- | | `provider` | `string` | Yes | Provider identifier | | `address` | `string` | Yes | User's wallet address | | `marketId` | `string` | No | Filter by the canonical `Market.id` (not display symbol) | | `limit` | `integer` | No | Items per page (default 50, max 100) | | `cursor` | `string` | No | Pagination cursor from previous response | ### Shape ```json theme={null} { "provider": "hyperliquid", "positions": [ { "market": { "providerId": "hyperliquid", "id": "BTC", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "side": "LONG", "size": "0.5", "entryPrice": "94000.00", "markPrice": "95000.50", "liquidationPrice": "85000.00", "unrealizedPnl": "500.25", "leverage": 10, "marginUsed": "4700.00", "marginMode": "ISOLATED" } ], "pagination": { "limit": 50, "hasMore": false } } ``` ### Position fields | Field | Type | Description | | ------------------ | ----------------------- | ---------------------------- | | `market` | `MarketDisplay` | Market reference (see below) | | `side` | `'LONG' \| 'SHORT'` | Position direction | | `size` | `string` | Position size | | `entryPrice` | `string` | Average entry price | | `markPrice` | `string` | Current mark price | | `liquidationPrice` | `string` | Estimated liquidation price | | `unrealizedPnl` | `string` | Unrealized profit/loss | | `leverage` | `number` | Current leverage | | `marginUsed` | `string` | Margin allocated | | `marginMode` | `'ISOLATED' \| 'CROSS'` | Margin mode | ### MarketDisplay The `MarketDisplay` object is used across positions, orders, fills, and activity to identify the market and its underlying assets: | Field | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providerId` | `string` | Provider that owns the market (e.g., `"hyperliquid"`) | | `id` | `string` | Provider's canonical, stringified market id that uniquely identifies the trading instrument (e.g., `"BTC"`, `"xyz:PURR"`, `"@142"`; numeric on Lighter) | | `categoryId` | `string` | Provider category id (e.g., `"hyperliquid"`, `"xyz"`, `"spot"`) | | `baseAsset` | `Asset` | Base leg of the market | | `quoteAsset` | `Asset` | Quote leg of the market | **SDK:** [`getPositions()`](/sdk/account/get-positions) *** ## getOrders Returns the user's open orders and trigger orders. Results are paginated. ```typescript theme={null} const result = await getOrders(client, { provider: 'hyperliquid', address: '0x1234...', }); ``` ### Parameters | Name | Type | Required | Description | | ---------- | --------- | -------- | -------------------------------------------------------- | | `provider` | `string` | Yes | Provider identifier | | `address` | `string` | Yes | User's wallet address | | `marketId` | `string` | No | Filter by the canonical `Market.id` (not display symbol) | | `limit` | `integer` | No | Items per page (default 50, max 100) | | `cursor` | `string` | No | Pagination cursor from previous response | ### Shape ```json theme={null} { "provider": "hyperliquid", "openOrders": [ { "orderId": "12345678", "market": { "providerId": "hyperliquid", "id": "ETH", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "ETH", "displaySymbol": "ETH", "logoURI": "https://assets.li.fi/tokens/eth.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "side": "BUY", "type": "LIMIT", "size": "1.0", "price": "3150.00", "filledSize": "0", "reduceOnly": false, "createdAt": "2025-01-15T10:30:00Z" } ], "triggerOrders": [ { "orderId": "87654321", "market": { "providerId": "hyperliquid", "id": "BTC", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "type": "TAKE_PROFIT_MARKET", "size": "0.1", "triggerPrice": "100000.00", "createdAt": "2025-01-15T10:30:00Z" } ], "pagination": { "limit": 50, "hasMore": false } } ``` ### OpenOrder fields | Field | Type | Description | | ------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `orderId` | `string` | Order ID | | `market` | `MarketDisplay` | Market reference | | `side` | `'BUY' \| 'SELL'` | Order direction | | `type` | `OrderType` | Order type: `MARKET`, `LIMIT`, `STOP_MARKET`, `STOP_LIMIT`, `TAKE_PROFIT_MARKET`, `TAKE_PROFIT_LIMIT`, `TRIGGER_ONLY`, `TWAP` (read-side only) | | `size` | `string` | Order size | | `price` | `string` | Limit price | | `filledSize` | `string` | Amount filled | | `reduceOnly` | `boolean` | Whether reduce-only | | `label` | `string?` | Optional order label | | `createdAt` | `string` | ISO 8601 timestamp | ### TriggerOrder fields | Field | Type | Description | | -------------- | --------------- | ------------------------------------------------------------- | | `orderId` | `string` | Order ID | | `market` | `MarketDisplay` | Market reference | | `type` | `OrderType` | Trigger order type (e.g., `TAKE_PROFIT_MARKET`, `STOP_LIMIT`) | | `size` | `string` | Order size | | `triggerPrice` | `string` | Price at which the order activates | | `limitPrice` | `string?` | Execution limit price (market order if omitted) | | `label` | `string?` | Optional order label | | `createdAt` | `string` | ISO 8601 timestamp | **SDK:** [`getOrders()`](/sdk/account/get-orders) *** ## getFills Returns paginated order fills. Results are sorted by creation time, newest first. ```typescript theme={null} const fills = await getFills(client, { provider: 'hyperliquid', address: '0x1234...', limit: 50, }); ``` ### Parameters | Name | Type | Required | Description | | ----------- | --------- | -------- | ---------------------------------------- | | `provider` | `string` | Yes | Provider identifier | | `address` | `string` | Yes | User's wallet address | | `startTime` | `integer` | No | Filter: fills after this timestamp (ms) | | `endTime` | `integer` | No | Filter: fills before this timestamp (ms) | | `cursor` | `string` | No | Pagination cursor from previous response | | `limit` | `integer` | No | Items per page (default 50, max 100) | ### Shape The `filledSize`, `fee`, and `realizedPnl` fields are optional -- they may be absent on cancelled or rejected orders, and `realizedPnl` is `null` when the order did not close a position. ```json theme={null} { "provider": "hyperliquid", "items": [ { "id": "12345678", "orderId": "12340001", "market": { "providerId": "hyperliquid", "id": "BTC", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "side": "BUY", "type": "MARKET", "size": "0.5", "price": "94000.00", "status": "FILLED", "liquidity": "taker", "filledSize": "0.5", "fee": "4.70", "realizedPnl": "125.50", "startPosition": "0", "classification": "Opened Long", "createdAt": "2025-01-15T09:00:00Z" } ], "pagination": { "limit": 50, "hasMore": true, "cursor": "abc123" } } ``` ### Fill fields | Field | Type | Description | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Fill ID | | `orderId` | `string` | ID of the parent order | | `market` | `MarketDisplay` | Market reference | | `side` | `'BUY' \| 'SELL'` | Order direction | | `type` | `OrderType` | Order type | | `size` | `string` | Original order size | | `price` | `string` | Fill price | | `status` | `FillStatus` | `FILLED`, `PARTIALLY_FILLED`, `CANCELLED`, `REJECTED` | | `liquidity` | `LiquidityRole` | `'maker'` or `'taker'` — whether the fill provided or removed liquidity | | `filledSize` | `string?` | Amount filled (absent if no fills yet) | | `fee` | `string?` | Total fees paid (absent if no fills yet) | | `realizedPnl` | `string \| null?` | Realized PnL (present only when closing a position, `null` otherwise) | | `startPosition` | `string?` | Position size before this fill | | `classification` | `FillClassification` | How this fill affected the position (see below) | | `createdAt` | `string` | ISO 8601 timestamp | | `explorerLink` | `string?` | Block-explorer URL for the settling on-chain tx. Absent when the fill has no on-chain tx (every Hyperliquid fill is off-chain). | ### FillClassification Describes how the fill affected the user's position. Wire values are Title Case strings: | Value | Description | | ------------------- | ----------------------------------------------- | | `"Opened Long"` | Opened a new long position from zero | | `"Opened Short"` | Opened a new short position from zero | | `"Increased Long"` | Added to an existing long position | | `"Increased Short"` | Added to an existing short position | | `"Reduced Long"` | Partially closed a long position | | `"Reduced Short"` | Partially closed a short position | | `"Closed Long"` | Fully closed a long position | | `"Closed Short"` | Fully closed a short position | | `"Switched Long"` | Closed a short and opened a long (crossed zero) | | `"Switched Short"` | Closed a long and opened a short (crossed zero) | | `"Spot Buy"` | Spot market buy | | `"Spot Sell"` | Spot market sell | ### Pagination Use the `cursor` from the response to fetch the next page: ```typescript theme={null} const nextPage = await getFills(client, { provider: 'hyperliquid', address: '0x1234...', cursor: 'abc123', }); ``` When `hasMore` is `false`, there are no more pages. **SDK:** [`getFills()`](/sdk/account/get-fills) *** ## getActivity Returns paginated account activity: deposits, withdrawals, liquidations, and funding payments. ```typescript theme={null} const activity = await getActivity(client, { provider: 'hyperliquid', address: '0x1234...', }); ``` ### Parameters | Name | Type | Required | Description | | ----------- | ---------------- | -------- | ----------------------------------------------------------------------------------------- | | `provider` | `string` | Yes | Provider identifier | | `address` | `string` | Yes | User's wallet address | | `startTime` | `integer` | No | Filter: activity after this timestamp (ms) | | `endTime` | `integer` | No | Filter: activity before this timestamp (ms) | | `cursor` | `string` | No | Pagination cursor from previous response | | `limit` | `integer` | No | Items per page (default 50, max 200) | | `type` | `ActivityType[]` | No | Filter by activity type(s): `DEPOSIT`, `WITHDRAWAL`, `FUNDING`, `LIQUIDATION`, `TRANSFER` | ### Shape The response contains a discriminated union of activity items — the `type` field determines which fields are present. ```json theme={null} { "provider": "hyperliquid", "items": [ { "id": "dep-001", "provider": "hyperliquid", "type": "DEPOSIT", "timestamp": "2025-01-15T10:00:00Z", "amount": "5000.00" }, { "id": "wd-002", "provider": "hyperliquid", "type": "WITHDRAWAL", "timestamp": "2025-01-14T09:00:00Z", "amount": "1000.00", "fee": "1.00" }, { "id": "fund-003", "provider": "hyperliquid", "type": "FUNDING", "timestamp": "2025-01-14T08:00:00Z", "market": { "providerId": "hyperliquid", "id": "BTC", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "BTC", "displaySymbol": "BTC", "logoURI": "https://assets.li.fi/tokens/btc.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "amount": "-2.50", "positionSize": "0.5", "fundingRate": "0.0001" }, { "id": "liq-004", "provider": "hyperliquid", "type": "LIQUIDATION", "timestamp": "2025-01-13T12:00:00Z", "liquidatedNotionalPosition": "50000.00", "accountValue": "100.00", "leverageType": "Cross", "liquidatedPositions": [ { "market": { "providerId": "hyperliquid", "id": "ETH", "categoryId": "hyperliquid", "baseAsset": { "providerId": "hyperliquid", "id": "ETH", "displaySymbol": "ETH", "logoURI": "https://assets.li.fi/tokens/eth.png" }, "quoteAsset": { "providerId": "hyperliquid", "id": "USDC", "displaySymbol": "USDC", "logoURI": "https://assets.li.fi/tokens/usdc.png" } }, "size": "10.0" } ] } ], "pagination": { "limit": 50, "hasMore": true, "cursor": "abc123" } } ``` ### Activity Types All activity items share these base fields: | Field | Type | Description | | ----------- | -------- | ----------------------------- | | `id` | `string` | Activity ID | | `provider` | `string` | Provider identifier | | `type` | `string` | Activity type (discriminator) | | `timestamp` | `string` | ISO 8601 timestamp | **DEPOSIT** — Funds deposited into the DEX account: | Field | Type | Description | | -------------- | --------- | ---------------------------------------------- | | `amount` | `string` | Deposit amount | | `explorerLink` | `string?` | Block-explorer URL for the on-chain deposit tx | **WITHDRAWAL** — Funds withdrawn from the DEX account: | Field | Type | Description | | -------------- | --------- | ------------------------------------------------- | | `amount` | `string` | Withdrawal amount | | `fee` | `string` | Withdrawal fee | | `explorerLink` | `string?` | Block-explorer URL for the on-chain withdrawal tx | **FUNDING** — Funding payment received or paid on an open position: | Field | Type | Description | | -------------- | --------------- | -------------------------------- | | `market` | `MarketDisplay` | Market reference | | `amount` | `string` | Funding amount (negative = paid) | | `positionSize` | `string` | Position size at time of funding | | `fundingRate` | `string` | Funding rate applied | **LIQUIDATION** — Position(s) liquidated: | Field | Type | Description | | ---------------------------- | ---------------------- | ------------------------------------ | | `liquidatedNotionalPosition` | `string` | Total notional value liquidated | | `accountValue` | `string` | Account value at time of liquidation | | `leverageType` | `string` | Leverage type (e.g., `"Cross"`) | | `liquidatedPositions` | `LiquidatedPosition[]` | Positions that were liquidated | Each `LiquidatedPosition`: | Field | Type | Description | | -------- | --------------- | ------------------------ | | `market` | `MarketDisplay` | Market reference | | `size` | `string` | Position size liquidated | **TRANSFER** — Internal transfer between two accounts on the same provider (currently emitted by Lighter only; the type definition supports Hyperliquid as well). Direction is relative to the queried account. The counterparty is identified by either an account index (integer L2 account identifier — Lighter) or a wallet address (Hyperliquid, where accounts ARE addresses). The shape is a discriminated union: at least one of `counterpartyAccountIndex` / `counterpartyAddress` MUST be present, and either may appear alone or alongside the other. Consumers that render counterparties should prefer `counterpartyAccountIndex` when present (canonical handle on index-based providers) and fall back to a truncated `counterpartyAddress` otherwise. | Field | Type | Description | | -------------------------- | --------------- | ------------------------------------------------------------------------------------ | | `direction` | `'IN' \| 'OUT'` | Direction relative to the queried account | | `counterpartyAccountIndex` | `number?` | The other side's account index (required when `counterpartyAddress` is absent) | | `counterpartyAddress` | `string?` | The other side's wallet address (required when `counterpartyAccountIndex` is absent) | | `asset` | `string` | Asset symbol (e.g., `"USDC"`) | | `amount` | `string` | Transfer amount | | `meta` | `object?` | Provider-specific metadata | | `explorerLink` | `string?` | Block-explorer URL for the on-chain transfer tx | ### Pagination Use the `cursor` from the response to fetch the next page: ```typescript theme={null} const nextPage = await getActivity(client, { provider: 'hyperliquid', address: '0x1234...', cursor: 'abc123', }); ``` When `hasMore` is `false`, there are no more pages. **SDK:** [`getActivity()`](/sdk/account/get-activity)