Get the risk card of one wallet
/v1/chains/{chain}/perpl/accounts/{address}Call this for the open positions of one wallet and how close each is to liquidation. The address is looked up on the exchange (getAccountByAddr) and its positions are taken from the latest snapshot. The record holds:
- the account:
account_id,address,balance_usd(the free balance),locked_usd(the part of the balance that the exchange has locked) andfrozen; total_notional_usdandtotal_deposit_usdover the positions, andmin_distance, the smallest distance to liquidation of any position (nullwithout positions);positions, the largest notional first. A position has thesize,entry_price,mark_price,deposit_usd,premium_pnl_usd(the premium PnL that the contract keeps for the position and that the liquidation price takes into account),notional_usdat the mark,maintenance_margin_usd,leverage(nullwith a zero deposit),liq_price,bankruptcy_price,distance(the fraction of the mark to the liquidation price, 0 or less means liquidatable now) andoi_share, the position's share of the open notional of its own side of the market;standing: the rank, PnL and volume of the wallet on Perpl's public leaderboard for the last day and for all time. A period isnullwhen the wallet is not on the board or the board could not be read (coveragehasperpl_leaderboard_unavailablein that case).
A wallet with an account and no positions answers 200 with empty positions. The address is taken in any case, without a checksum check.
Path parameters
| Name | Type | Description |
|---|---|---|
chainRequired | string | The chain, as a CAIP-2 chain ID. Only Monad, |
addressRequired | string | The wallet address: |
Response
The answer, wrapped in the {data, meta, links} envelope. data.kind is perpl_account. meta.as_of names the snapshot block.
| Field | Type | Description |
|---|---|---|
| account_id | integer | |
| address | string | A 20-byte address written as |
| balance_usd | string | An amount in US dollars as a decimal string with up to 6 decimals and no trailing zeros. It can be negative for a PnL. |
| chain | string | The CAIP-2 id of the chain. |
| coverage | array of strings | The codes of the limits that apply to this answer, in a fixed order. It is empty when none applies. The status route explains each code. |
| frozen | boolean | |
| kind | string | perpl_account |
| locked_usd | string | An amount in US dollars as a decimal string with up to 6 decimals and no trailing zeros. It can be negative for a PnL. |
| min_distance | number | null | The smallest distance to liquidation of any position, |
| positions | array of objects | |
| standing | object | |
| total_deposit_usd | string | An amount in US dollars as a decimal string with up to 6 decimals and no trailing zeros. It can be negative for a PnL. |
| total_notional_usd | string | An amount in US dollars as a decimal string with up to 6 decimals and no trailing zeros. It can be negative for a PnL. |
Cost
1 credit. The time limit is 5 seconds.
Errors
| Status | Code |
|---|---|
| 400 | invalid_id |
| 404 | not_foundunsupported_chain |
| 429 | rate_limitedcredits_exhausted |
| 500 | internal |
| 503 | upstream_unavailable |
| 504 | deadline_exceeded |
404 not_found when the address has no Perpl account, 400 invalid_id for a malformed address, 404 unsupported_chain, 503 upstream_unavailable also when the chain read for the account fails, and 504 as elsewhere.