Perpl risk
Perpl is a perpetual futures exchange on Monad. Sona reads every open position of every market from the exchange contract, computes each position's liquidation price with the published formula, and serves the risk that follows from it. Only Monad, eip155:143, is covered.
Snapshots
Positions come from a snapshot taken every 30 seconds, a few blocks behind the head. meta.as_of names the snapshot block and meta.finality is confirmed. Liquidations and funding come from stored history, and their meta.as_of still names the snapshot, not the events.
Every data ends with coverage, the codes of the limits that apply to that answer.
| Code | Meaning |
|---|---|
perpl_snapshot_only | Positions are read at one block |
perpl_bad_debt_is_floor | A bad debt figure is a lower bound |
perpl_leaderboard_unavailable | Perpl's public leaderboard could not be read, so the figures taken from it are null |
perpl_history_partial | The liquidation history is still being read |
perpl_funding_from_snapshots | Funding history starts when Sona began recording |
perpl_oi_from_snapshots | Open interest history starts when Sona began recording |
perpl_leaderboard_figures | Leaderboard figures are Perpl's own |
perpl_snapshot_stale | Refreshes are failing, so the numbers describe an earlier block |
A market is named by its symbol in any case or by its decimal perp id. USD amounts, prices and sizes are decimal strings, and shares and distances are numbers.
Markets
The headline table: one item per priced market.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/markets"| Field | Meaning |
|---|---|
mark, oracle | Mark and oracle prices |
oracle_gap_bps | Mark against oracle in basis points |
oracle_age_s | Seconds between the oracle's own timestamp and the snapshot. A stale oracle blocks liquidations. |
long_oi, short_oi | Open interest in size and in USD at the mark. Both sides are equal. |
positions, insurance_fund_usd | Open positions and the market's insurance fund |
funding_rate | Rate of one funding interval as a fraction of notional |
max_leverage, maint_margin_fraction | Margin settings |
scr_m10, scr_p10 | Shock Cover Ratio after a fall or rise of 10% |
/perpl/markets/{market} adds the margin and funding settings and how a liquidation's proceeds are split between the insurance fund, the liquidated trader and the protocol.
Liquidation map
Where the open positions of a market would be liquidated. Buckets run from mark * (1 - range_pct%) to mark * (1 + range_pct%). Each holds the notional at the mark and the number of accounts whose liquidation price lies in [price_from, price_to), split by side.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/markets/BTC/liquidation-map?bucket_bps=100&range_pct=10"| Parameter | Values |
|---|---|
bucket_bps | 5 to 500, default 25 |
range_pct | 1 to 50, default 20 |
Longs normally liquidate below the mark and shorts above it. beyond_range adds up the positions outside the range. cumulative gives, for each whole move from 1 to range_pct percent, the notional and number of positions a fall (long) or rise (short) of that size would liquidate. It counts every position, also those beyond the range or already liquidatable, and both curves never decrease.
Stress test and Shock Cover Ratio
A stress test moves the mark by shock, a fraction from -0.5 to 0.5 that is not 0. -0.1 is a fall of 10%, and the default is -0.1.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/markets/BTC/stress?shock=-0.2"| Field | Meaning |
|---|---|
p0, p1 | The mark and the shocked price |
liquidating | Notional at p1, positions and accounts the shock liquidates |
gap_bad_debt_usd | Loss beyond the traders' margin if every liquidation fills at p1 |
insurance_fund_usd | The market's fund |
scr | Shock Cover Ratio, the fund divided by the gap bad debt. 2.5 means the fund covers the loss 2.5 times. |
no_bad_debt | true when the shock causes no bad debt, and then scr is null |
uncovered_usd | Bad debt the fund cannot pay, 0 when scr is 1 or more |
top_positions | Up to 10 liquidating positions, largest first |
Bad debt is a floor. It assumes every liquidation fills exactly at p1. Order book depth, slippage, cascades and traders adding collateral during the move are not modelled, and each market's fund is not netted against another's.
/perpl/stress runs the same test for every market with one shock and costs 2 credits.
Concentration
Who holds the risk. It costs 2 credits.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/concentration"| Part | Meaning |
|---|---|
markets | Per market, top1, top5 and top10, the share of the market's two-sided notional that the largest 1, 5 and 10 accounts hold, plus top_accounts |
overall | The same over all markets, with an account's notional added across markets |
volume | The share of leaderboard volume held by the top 1, 5 and 10 accounts for the last day and all time |
keepers | The 10 addresses that sent the most liquidation transactions, with their share of all liquidations |
Shares are numbers from 0 to 1. An account is not necessarily one person, and one person can control several addresses.
Liquidations
Forced closes, newest first. market narrows the list, limit is 1 to 200 (default 50), and next_cursor goes back as cursor for the next page.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/liquidations?limit=3"An item has the block, time, tx, market, the account and its address, side, mark, liq_price, size, remaining_size (0 for a full liquidation), notional_usd, on_order_book and the keeper that sent the transaction.
liq_price is the price the position was closed at, not its trigger price. Do not compare it with the prices of the liquidation map.
/perpl/liquidations/daily counts liquidations per UTC day for the last days days (1 to 400, default 90), with count and notional_usd. A day without any is there with count 0, and today's item is partial.
Funding and market history
/perpl/funding draws the funding rate and the gap between mark and oracle of one market. market is required and hours is 1 to 168 (default 24).
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/funding?market=BTC&hours=24"/perpl/markets/{market}/history draws one series chosen by metric. hours is 24, 168 or 720, default 168.
metric | Series |
|---|---|
oi | Open interest in USD at the mark and the number of positions. Starts when Sona began recording. |
volume | Hourly traded notional and trades from Perpl's public market data. The last hour is still open. |
funding | The funding rates Perpl applied, one item per application. Positive means longs pay shorts, so 0.00004 is 0.004%. |
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/markets/BTC/history?metric=oi&hours=24"Leaderboard
The top accounts of Perpl's public leaderboard, ranked by by (pnl or volume) for the period (all or day). limit is 1 to 100, default 25.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/leaderboard?by=pnl&period=all&limit=5"Each row has rank, address, pnl_usd, volume_usd and volume_share, the row's volume over the volume of the whole board. The figures are Perpl's own and are not recomputed. Volume counts both sides of every trade, so it is about twice the traded volume, and Perpl does not publish what its PnL includes.
Accounts
The open positions of one wallet and how close each is to liquidation.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/accounts/0x7e842a5d75249257036d6bde1887874131e77ad1"| Field | Meaning |
|---|---|
balance_usd, locked_usd, frozen | The account's free balance, the locked part and its frozen flag |
total_notional_usd, total_deposit_usd | Sums over the positions |
min_distance | Smallest distance to liquidation of any position, null without positions |
positions | Largest notional first, each with size, entry_price, mark_price, leverage, liq_price, bankruptcy_price, distance and oi_share |
standing | Rank, PnL and volume on the public leaderboard for the day and all time, null when not listed |
distance is the fraction of the mark to the liquidation price. 0 or less means the position is liquidatable now. An address with no Perpl account answers 404 not_found.
Status
/perpl/status shows the exchange address, whether the exchange implementation changed, the age of the snapshot, the number of markets and positions, liquidations indexed, the state of the history backfill, and each coverage code in a sentence.
curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/status"Reference pages: Perpl endpoints.