> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/public-info-api/account-data.md).

# Account data

## Account data

All account-data query types accept a public wallet address and do not require authentication. Where supported, broker\_id and account\_id narrow the lookup; use pangoperps for PangoPerps account scope. Account values and monetary amounts are decimal strings.

### Account state

Returns account collateral, margin, PnL, and currently open positions. Weight: 5. Supplying account\_id returns one account as a flat object; omitting it returns an accounts\[] list.

```json
{
  "type": "accountState",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "pangoperps",
  "account_id": "0xabc..."
}
```

| Field       | Type   | Required | Description                                                              |
| ----------- | ------ | -------- | ------------------------------------------------------------------------ |
| address     | string | Yes      | Wallet address.                                                          |
| broker\_id  | string | No       | Optional broker filter.                                                  |
| account\_id | string | No       | Optional account filter; when supplied, data is the flat account object. |

Account fields include address, broker\_id, account\_id, account\_type, account\_value, total\_collateral\_value, free\_collateral, margin\_ratio, initial\_margin\_ratio, maintenance\_margin\_ratio, total\_unrealized\_pnl, total\_unsettled\_pnl, total\_pnl\_24\_h, and positions\[]. account\_type is main, sub, or sp (vault strategy provider). account\_value is collateral plus unrealized PnL; total\_collateral\_value includes token holdings, isolated margin, and frozen collateral, with non-USDC balances valued using the spot index price. free\_collateral is approximately collateral multiplied by (1 - margin\_ratio). initial\_margin\_ratio is calculated over cross-margin positions; maintenance margin is the minimum ratio needed to avoid liquidation.

Each open-position row contains symbol, side, position\_qty, notional, average\_open\_price, mark\_price, unrealized\_pnl, unsettled\_pnl, pnl\_24\_h, imr, mmr, est\_liq\_price, leverage, margin\_mode, opened\_at, and updated\_at. Quantity is signed; side is LONG for a positive quantity and SHORT for a negative quantity. notional is absolute quantity times mark price. margin\_mode is CROSS or ISOLATED. PnL, margin, and price-derived fields can be null if position calculation is unavailable. Only open positions (nonzero holdings) are returned. A missing account returns ADDRESS\_NOT\_FOUND (404); position-calculation failure does not suppress other account data.

### Accounts

Lists the main and sub-accounts controlled by a wallet. Use this as the discovery query before requesting a particular account's state. Weight: 5; no pagination.

```json
{
  "type": "accounts",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "pangoperps"
}
```

| Field      | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| address    | string | Yes      | Wallet address; it must resolve to at least one account. |
| broker\_id | string | No       | Optional broker filter.                                  |

data contains the input address and accounts\[]. Each entry includes broker\_id, account\_id, account\_type (main, sub, or sp), and account\_value. Account value is calculated as (holding + iso\_margin\_total + frozen) + Σ unrealized\_pnl across positions. It can be null if position calculation is unavailable for that account. If no accounts resolve, the API returns ADDRESS\_NOT\_FOUND (404). Per-account calculation failures set only that account's value to null.

### Agent context

Returns a startup bundle containing an account snapshot, open positions, summaries for markets held by that account, and the open-order count. The constituent lookups run in parallel. Weight: 2.

```json
{
  "type": "agentContext",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "pangoperps",
  "account_id": "0xabc..."
}
```

| Field       | Type   | Required | Description                                                                                                                            |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| address     | string | Yes      | Wallet address.                                                                                                                        |
| broker\_id  | string | No       | Optional broker filter.                                                                                                                |
| account\_id | string | No       | Optional account filter. If omitted, the primary account is selected by highest account value, with a main account used to break ties. |

data includes account, positions\[], and markets\[]. The account object is a subset of accountState and adds open\_order\_count; if that subquery fails, the count defaults to 0. Positions follow accountState.positions\[]. Each market row corresponds to a held symbol and follows the marketSummary row format with an added 24h\_change\_pct, calculated as (close - open) / open × 100. Markets not held by the selected account are not included. For the complete open-order list, use openOrders. This bundle uses weight 2, compared with the separate-call total of 11 for accountState, openOrders, and marketSummary.

### Fee rate

Returns a user's fee tier, maker/taker rates, and executed notional over the last 30 days. Weight: 1. The response format depends on the supplied filters.

```json
{
  "type": "feeRate",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "pangoperps",
  "account_id": "0xabc..."
}
```

| Field       | Type   | Required | Description                                                            |
| ----------- | ------ | -------- | ---------------------------------------------------------------------- |
| address     | string | Yes      | Wallet address.                                                        |
| broker\_id  | string | No       | With no account\_id, returns a sub\_accounts\[] result for the broker. |
| account\_id | string | No       | Returns one account as a flat object.                                  |

Provide both address and account\_id for a flat account object; provide address and broker\_id without account\_id for sub\_accounts\[]; provide only address for accounts\[]. Each account entry contains broker\_id, account\_id, account\_type, tier, futures\_tier, maker\_fee\_rate, taker\_fee\_rate, and 30d\_volume.

tier and futures\_tier can be PUBLIC, SILVER, GOLD, PLATINUM, or DIAMOND; they may be null. Maker and taker rates are decimal strings (bps / 10000) and may be null. 30d\_volume is executed perpetual notional over the past 30 days, returned as a decimal string ("0" when there is no volume). Results are cached for 60 seconds by address and filters. No matching account returns ADDRESS\_NOT\_FOUND (404).

### Funding payments

Returns funding-fee history for a wallet, including payment direction and settlement state. Weight: 5.

```json
{
  "type": "fundingPayments",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "PERP_BTC_USDC",
  "start_time": 1715000000000,
  "limit": 100
}
```

| Field                  | Type   | Required | Default / limits | Description                         |
| ---------------------- | ------ | -------- | ---------------- | ----------------------------------- |
| address                | string | Yes      | —                | Wallet address.                     |
| broker\_id             | string | No       | —                | Optional broker filter.             |
| account\_id            | string | No       | —                | Optional account filter.            |
| symbol                 | string | No       | —                | Market filter.                      |
| start\_time, end\_time | int64  | No       | —                | Time-window bounds in milliseconds. |
| limit                  | int    | No       | 100; 1–500       | Maximum rows.                       |
| cursor                 | string | No       | —                | Opaque pagination cursor.           |

With no time filters, the query returns the full available history. Each row includes symbol, funding\_rate, funding\_fee, position\_qty, mark\_price, funding\_rate\_timestamp, payment\_type, funding\_status, and margin\_mode. The fee is signed: positive means the user paid, negative means the user received. payment\_type is Pay, Receive, or null when the fee is zero. funding\_status is Settled or Accrued; it defaults to Settled if the settlement table cannot be read. margin\_mode is CROSS or ISOLATED. The position and mark price are snapshots from the funding interval. Results use data.next\_cursor for pagination.

### Historical orders

Returns closed orders with status FILLED, CANCELLED, or REJECTED. It queries live and archived data, including windows that cross the 92-day archive boundary. Both standard and algorithmic orders are included. Weight: 5.

```json
{
  "type": "historicalOrders",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "PERP_ETH_USDC",
  "status": "FILLED",
  "start_time": 1715000000000,
  "end_time": 1715600000000,
  "limit": 100
}
```

| Field                   | Type   | Required | Default / limits          | Description                                                               |
| ----------------------- | ------ | -------- | ------------------------- | ------------------------------------------------------------------------- |
| address                 | string | Yes      | —                         | Wallet address.                                                           |
| broker\_id, account\_id | string | No       | —                         | Optional account filters.                                                 |
| symbol                  | string | No       | —                         | Market filter.                                                            |
| status                  | string | No       | All three statuses        | FILLED, CANCELLED (also accepts CANCELED), or REJECTED; case-insensitive. |
| start\_time             | int64  | No       | UTC-day-aligned now - 24h | Start time in milliseconds.                                               |
| end\_time               | int64  | No       | now                       | End time in milliseconds.                                                 |
| limit                   | int    | No       | 100; 1–500                | Maximum rows.                                                             |
| cursor                  | string | No       | —                         | Opaque pagination cursor.                                                 |

Order rows include order\_id, symbol, side, type, price, quantity, total\_executed\_quantity, average\_executed\_price, trigger\_price, trigger\_status, status, total\_fee, fee\_asset, realized\_pnl, reduce\_only, created\_time, and updated\_time. order\_id is a string-encoded 64-bit value. type may be a standard type (LIMIT, MARKET, IOC, POST\_ONLY, FOK, LIQUIDATE, BID, ASK, SETTLEMENT) or an algorithmic type (STOP\_MARKET, STOP\_LIMIT, TAKE\_PROFIT\_MARKET, TAKE\_PROFIT\_LIMIT, OCO, TRAILING\_STOP, BRACKET, POSITIONAL\_TP\_SL, TP\_SL, STOP\_TRIGGER, STOP\_BRACKET). average\_executed\_price is calculated from executed amount divided by executed quantity, and is null when there are no fills. Algorithmic rows can include trigger fields; realized\_pnl can be null for algorithmic rows.

If status is omitted, all three closed statuses are queried (FILLED → \[3], CANCELLED → \[5], REJECTED → \[6]). The default start time is aligned to a UTC day; specify start\_time for a longer lookback. Live and archived records are combined automatically. Rows are sorted by created\_time descending, then order\_id descending. Use data.next\_cursor to continue.

### Open orders

Returns open and partially filled standard and algorithmic orders for a wallet, sorted newest first. Weight: 5.

```json
{
  "type": "openOrders",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "PERP_ETH_USDC",
  "limit": 100
}
```

| Field                   | Type   | Required | Default / limits | Description               |
| ----------------------- | ------ | -------- | ---------------- | ------------------------- |
| address                 | string | Yes      | —                | Wallet address.           |
| broker\_id, account\_id | string | No       | —                | Optional account filters. |
| symbol                  | string | No       | —                | Market filter.            |
| limit                   | int    | No       | 100; 1–500       | Maximum rows.             |
| cursor                  | string | No       | —                | Opaque pagination cursor. |

Each row includes order\_id, symbol, side, type, price, quantity, total\_executed\_quantity, trigger\_price, trigger\_status, status, reduce\_only, created\_time, and updated\_time. order\_id is a 64-bit integer encoded as a string. side is BUY, SELL, or BOTH. price can be null for market orders or trigger orders without a limit price. Algorithmic orders may include trigger\_price, trigger\_status (PENDING, TRIGGERED, or FAILED), and reduce\_only; ordinary orders have these fields as null. The status returned by this query is always OPEN.

Rows are ordered by created\_time descending and then order\_id descending. The cursor continues from that ordering by comparing the timestamp and ID lexicographically; pass data.next\_cursor unchanged.

### Order status

Looks up one order by ID across both live and archived order data and includes algorithmic-order details when available. Weight: 5; one result, no pagination.

```json
{
  "type": "orderStatus",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "order_id": 123456789,
  "broker_id": "pangoperps",
  "account_id": "0xabc..."
}
```

| Field                   | Type   | Required | Description                                                                         |
| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| address                 | string | Yes      | Wallet address; scopes the lookup to one user. Omitting it makes the lookup slower. |
| order\_id               | int64  | Yes      | Order identifier. Missing value returns MISSING\_PARAM.                             |
| broker\_id, account\_id | string | No       | Optional account filters.                                                           |

The returned order includes the standard order fields such as order\_id, symbol, side, type, price, quantity, total\_executed\_quantity, average\_executed\_price, trigger\_price, status, total\_fee, fee\_asset, realized\_pnl, reduce\_only, created\_time, and updated\_time. Status can be PENDING\_NEW, NEW, PARTIAL\_FILLED, FILLED, PENDING\_CANCEL, CANCELLED, REJECTED, or REPLACED. average\_executed\_price is null for live orders and a decimal for archived orders. total\_fee and fee\_asset are null for live orders. Algorithmic orders may have trigger\_price. If the order is not in either data store, the API returns ORDER\_NOT\_FOUND (404).

### Portfolio

Returns daily account-value and cumulative-PnL snapshots aligned to UTC days. Weight: 5. Use accountState for current collateral and unrealized PnL.

```json
{
  "type": "portfolio",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "interval": "1d",
  "start_time": 1712000000000,
  "end_time": 1715000000000,
  "limit": 90
}
```

| Field                   | Type   | Required | Default / limits | Description                                                 |
| ----------------------- | ------ | -------- | ---------------- | ----------------------------------------------------------- |
| address                 | string | Yes      | —                | Wallet address.                                             |
| broker\_id, account\_id | string | No       | —                | Optional account filters.                                   |
| interval                | string | No       | 1d               | Only 1d is supported; another value returns INVALID\_PARAM. |
| start\_time             | int64  | No       | end\_time - 90d  | Start time in milliseconds.                                 |
| end\_time               | int64  | No       | now              | End time in milliseconds.                                   |
| limit                   | int    | No       | 90; 1–365        | Maximum daily snapshots.                                    |
| cursor                  | string | No       | —                | Opaque pagination cursor.                                   |

Each data.rows\[] item has account\_value, cumulative\_pnl, and timestamp. Rows are ordered by timestamp descending. Account value is the daily collateral snapshot (holdings plus frozen balance plus unrealized PnL); cumulative PnL is the account-value change from the earliest day in the returned window. The timestamp is the UTC-day-aligned snapshot time in milliseconds. interval values other than 1d and limits outside 1–365 return INVALID\_PARAM. The response is paginated with data.next\_cursor.

### Position context

Returns one market's position (if any), open orders for that market, a market snapshot, and account risk figures. The component lookups run in parallel. Weight: 2.

```json
{
  "type": "positionContext",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "PERP_BTC_USDC",
  "broker_id": "pangoperps",
  "account_id": "0xabc..."
}
```

| Field       | Type   | Required | Description                                                                                                                            |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| address     | string | Yes      | Wallet address.                                                                                                                        |
| symbol      | string | Yes      | Market symbol.                                                                                                                         |
| broker\_id  | string | No       | Optional broker filter.                                                                                                                |
| account\_id | string | No       | Optional account filter. If omitted, the primary account is the one with the highest account value, with a main account breaking ties. |

data contains position, open\_orders\[], market, and account\_summary. The position has the same shape as an accountState.positions\[] item and is null if the account has no position in that market. Open orders are already filtered to the requested symbol. The market object can be null if the symbol is absent from the latest market summary. The account summary contains free\_collateral and margin\_ratio, and can be null if the address is not found. This combined query is equivalent to requesting accountState, symbol-filtered openOrders, and marketSummary separately, but has a lower weight. Individual sections may have different freshness.

### Trades

Returns executed fills for a wallet. The query combines real-time fills from the latest 24 hours with older archived history and uses a cursor to continue across both sources. Weight: 5.

```json
{
  "type": "trades",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "symbol": "PERP_ETH_USDC",
  "start_time": 1714000000000,
  "end_time": 1715000000000,
  "limit": 200
}
```

| Field                   | Type   | Required | Default / limits                                  | Description                                     |
| ----------------------- | ------ | -------- | ------------------------------------------------- | ----------------------------------------------- |
| address                 | string | Yes      | —                                                 | Wallet address.                                 |
| broker\_id, account\_id | string | No       | —                                                 | Optional account filters.                       |
| symbol                  | string | No       | —                                                 | Market filter.                                  |
| start\_time             | int64  | No       | —                                                 | Start of the requested window, in milliseconds. |
| end\_time               | int64  | No       | If start\_time is set, defaults to now            | End of the requested window, in milliseconds.   |
| limit                   | int    | No       | 100; 1–1000 without a time range, 1–2000 with one | Maximum rows.                                   |
| cursor                  | string | No       | —                                                 | Opaque cursor that includes the data source.    |

Rows contain id, order\_id, symbol, side, executed\_price, executed\_quantity, fee, fee\_asset, is\_maker, realized\_pnl, and executed\_timestamp. IDs are strings; order\_id may be null for orphaned or liquidation fills. is\_maker is a boolean. realized\_pnl may be null for fills older than 24 hours because the archive does not retain that field.

The live interval covers \[max(start\_time, now - 24h), end\_time]; archived data covers \[start\_time, min(end\_time, now - 24h - 1ms)]. Pagination remains continuous across that boundary. Pass the returned cursor back unchanged. Recent data (within 24 hours) is fresher than archived results; older history is refreshed about hourly.

### Deposits and withdrawals

Returns deposit and withdrawal transaction history for an address, sorted by transaction ID descending. Weight: 5.

```json
{
  "type": "userDepositsWithdrawals",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "side": "deposit",
  "token": "USDC",
  "limit": 100
}
```

| Field                   | Type   | Required | Default / limits | Description                                                                |
| ----------------------- | ------ | -------- | ---------------- | -------------------------------------------------------------------------- |
| address                 | string | Yes      | —                | Wallet address.                                                            |
| broker\_id, account\_id | string | No       | —                | Optional account filters.                                                  |
| side                    | string | No       | —                | deposit or withdraw; case-insensitive. Other values return INVALID\_PARAM. |
| token                   | string | No       | —                | Token filter, for example USDC.                                            |
| start\_time, end\_time  | int64  | No       | —                | Time-window bounds in milliseconds.                                        |
| limit                   | int    | No       | 100; 1–500       | Maximum rows.                                                              |
| cursor                  | string | No       | —                | Opaque pagination cursor.                                                  |

Each row contains id, token, side, amount, fee, chain\_id, tx\_id, status, and created\_time. The transaction ID is returned as a string; chain\_id is the EVM chain ID, also represented as a string; tx\_id is the on-chain transaction hash. Status values include SUCCESS, PENDING, and FAILED. created\_time is milliseconds. Results are paginated with data.next\_cursor.

### Whale context

Returns an address research bundle with account details, open positions, and recent fills. The component lookups run in parallel and degrade independently if a component is unavailable. Weight: 3.

```json
{
  "type": "whaleContext",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "broker_id": "pangoperps",
  "recent_trades_limit": 20
}
```

| Field                   | Type   | Required | Default / limits    | Description                      |
| ----------------------- | ------ | -------- | ------------------- | -------------------------------- |
| address                 | string | Yes      | —                   | Wallet address.                  |
| broker\_id, account\_id | string | No       | —                   | Optional account filters.        |
| recent\_trades\_limit   | int    | No       | 20; clamped to 1–50 | Maximum recent fills to include. |

data contains account, positions\[], and recent\_trades\[]. The account is a subset of accountState and can be null if no account resolves. Positions follow the accountState.positions\[] format; recent fills follow the trades row format. If an individual component fails, its data may be null or an empty array while the overall request still succeeds.

***
