Check how current the Perpl data is

GET/v1/chains/{chain}/perpl/status

curl -s "https://api.sonaintel.com/v1/chains/eip155:143/perpl/status"

Response200

{
  "data": {
    "backfill": "complete",
    "chain": "eip155:143",
    "coverage": [
      {
        "code": "perpl_snapshot_only",
        "note": "Positions are read at one block. Collateral added or positions closed after that block are not in these numbers."
      },
      {
        "code": "perpl_bad_debt_is_floor",
        "note": "Gap bad debt assumes every liquidation fills at the shocked price, so it is a floor. A real book fills worse, and the share of the fund inflow from positions that close above bankruptcy is ignored."
      },
      {
        "code": "perpl_leaderboard_unavailable",
        "note": "The public leaderboard could not be read, so the volume shares or the rank that depend on it are left out."
      },
      {
        "code": "perpl_history_partial",
        "note": "The liquidation history may be incomplete because the backfill of older events is disabled or still running. See backfill in the status."
      },
      {
        "code": "perpl_funding_from_snapshots",
        "note": "The series is built from the snapshots this engine stored, so it starts when Sona started and a gap means Sona was not running."
      }
    ],
    "exchange": "0x34b6552d57a35a1d042ccae1951bd1c370112a6f",
    "implementation": "0xa9ab97a404a0bca04d6a5b4a39995fea9e791b2a",
    "implementation_changed": false,
    "kind": "perpl_status",
    "liquidations_indexed": 3650,
    "markets": 17,
    "paid_rpc_calls": 0,
    "positions": 665,
    "snapshot": {
      "age_s": 4,
      "block": 112777356,
      "time": "2026-10-12T14:21:57Z"
    }
  },
  "links": {
    "self": "/v1/chains/eip155:143/perpl/status"
  },
  "meta": {
    "as_of": {},
    "finality": "none",
    "missing": [],
    "partial": false
  }
}

Call this to see whether Sona has a snapshot and how old it is. The record holds:

exchange: the address of the Perpl exchange proxy that is read.
implementation and implementation_changed: the address behind the proxy (the ERC-1967 implementation slot), which Sona reads on every refresh, and whether it differs from the address Sona was configured to expect. A true means that the exchange was upgraded and its formulas should be checked again before the numbers are trusted. implementation is null until the first read.
snapshot: the block and time of the latest snapshot and its age in whole seconds, or null before the first one.
markets and positions: how many priced markets and open positions the snapshot holds (0 before the first snapshot).
liquidations_indexed: how many PositionLiquidated events the database holds.
backfill: complete when the history reaches back to the deployment block, running while it is being read, pending before it starts, retrying while it waits to try a failed read again, and disabled when Sona has no key for the history source and keeps only what it has seen since it started.
paid_rpc_calls: how many chain reads the RPC router billed to a paid provider since the start. It is 0 in normal operation.
coverage: the five limits of the data, each with its code and a sentence, always in the same order. The other routes list the codes that apply to their answer in their own coverage.

The route answers 200 also before the first snapshot exists, then with snapshot null and meta.finality none. It needs the database for liquidations_indexed.

Path parameters

Name	Type	Description
chainRequired	string	The chain, as a CAIP-2 chain ID. Only Monad, `eip155:143`, has Perpl data. A malformed ID answers 400 `invalid_id`, and any other well-formed ID, Ethereum's `eip155:1` included, answers 404 `unsupported_chain`.

Response

The answer, wrapped in the {data, meta, links} envelope. data.kind is perpl_status. meta.finality is none.

Field	Type	Description
backfill	string	The state of the liquidation history. `complete` reaches back to the deployment block, `running` is being read, `pending` has not started, `retrying` waits to try again after a failed read and `disabled` has no source, so it keeps only events seen since the start.
chain	string	The CAIP-2 id of the chain.
coverage	array of objects	The five limits of the data, always in the same order.
exchange	string	The Perpl exchange proxy that is read.
implementation	string \| null	The address behind the proxy at the last read, `null` before the first read.
implementation_changed	boolean	Whether the implementation differs from the one Sona expects. A `true` means that the exchange was upgraded.
kind	string	`perpl_status`
liquidations_indexed	integer	The number of liquidation events in the database.
markets	integer	The number of priced markets in the snapshot.
paid_rpc_calls	integer	Chain reads that the RPC router billed to a paid provider since the start.
positions	integer	The number of open positions in the snapshot.
snapshot	object \| null	The latest snapshot, `null` before the first one.

Cost

1 credit. The time limit is 5 seconds.

Errors

Status	Code
400	`invalid_idinvalid_query`
404	`unsupported_chain`
429	`rate_limitedcredits_exhausted`
500	`internal`
503	`upstream_unavailable`
504	`deadline_exceeded`

400 for a query parameter (this route takes none) or a chain that is no CAIP-2 id, 404 unsupported_chain, 503 upstream_unavailable when the database does not answer, and 504 deadline_exceeded when the budget runs out.

{ "data": { "backfill": "complete", "chain": "eip155:143", "coverage": [ { "code": "perpl_snapshot_only", "note": "Positions are read at one block. Collateral added or positions closed after that block are not in these numbers." }, { "code": "perpl_bad_debt_is_floor", "note": "Gap bad debt assumes every liquidation fills at the shocked price, so it is a floor. A real book fills worse, and the share of the fund inflow from positions that close above bankruptcy is ignored." }, { "code": "perpl_leaderboard_unavailable", "note": "The public leaderboard could not be read, so the volume shares or the rank that depend on it are left out." }, { "code": "perpl_history_partial", "note": "The liquidation history may be incomplete because the backfill of older events is disabled or still running. See backfill in the status." }, { "code": "perpl_funding_from_snapshots", "note": "The series is built from the snapshots this engine stored, so it starts when Sona started and a gap means Sona was not running." } ], "exchange": "0x34b6552d57a35a1d042ccae1951bd1c370112a6f", "implementation": "0xa9ab97a404a0bca04d6a5b4a39995fea9e791b2a", "implementation_changed": false, "kind": "perpl_status", "liquidations_indexed": 3650, "markets": 17, "paid_rpc_calls": 0, "positions": 665, "snapshot": { "age_s": 4, "block": 112777356, "time": "2026-10-12T14:21:57Z" } }, "links": { "self": "/v1/chains/eip155:143/perpl/status" }, "meta": { "as_of": {}, "finality": "none", "missing": [], "partial": false } }

Name

Type

Description

chainRequired

string

The chain, as a CAIP-2 chain ID. Only Monad, eip155:143, has Perpl data. A malformed ID answers 400 invalid_id, and any other well-formed ID, Ethereum's eip155:1 included, answers 404 unsupported_chain.

Response

The answer, wrapped in the {data, meta, links} envelope. data.kind is perpl_status. meta.finality is none.

Field	Type	Description
backfill	string	The state of the liquidation history. `complete` reaches back to the deployment block, `running` is being read, `pending` has not started, `retrying` waits to try again after a failed read and `disabled` has no source, so it keeps only events seen since the start.
chain	string	The CAIP-2 id of the chain.
coverage	array of objects	The five limits of the data, always in the same order.
exchange	string	The Perpl exchange proxy that is read.
implementation	string \| null	The address behind the proxy at the last read, `null` before the first read.
implementation_changed	boolean	Whether the implementation differs from the one Sona expects. A `true` means that the exchange was upgraded.
kind	string	`perpl_status`
liquidations_indexed	integer	The number of liquidation events in the database.
markets	integer	The number of priced markets in the snapshot.
paid_rpc_calls	integer	Chain reads that the RPC router billed to a paid provider since the start.
positions	integer	The number of open positions in the snapshot.
snapshot	object \| null	The latest snapshot, `null` before the first one.

Errors

Status	Code
400	`invalid_idinvalid_query`
404	`unsupported_chain`
429	`rate_limitedcredits_exhausted`
500	`internal`
503	`upstream_unavailable`
504	`deadline_exceeded`

Path parameters#

Response#

Cost#

Errors#

Path parameters#

Response#

Cost#

Errors#

Path parameters

Response

Cost

Errors

Path parameters

Response

Cost

Errors