# GET /v1/xrpl/metrics/liquidity-stress

How stressed a registry stablecoin's liquidity is against its peg default: a score from 0 to 100, its band and the four weighted components behind it.

## Purpose

Measures how stressed the liquidity of `asset` is against its peg default. `asset` is an XRPL stablecoin of the registry that `/v1/xrpl/stablecoin/{asset}` checks (RLUSD, USDC or EURØP), and its peg default is the other USD registry coin for a USD asset (USDC for RLUSD, RLUSD for USDC) and RLUSD for an EUR asset. Any other `asset` answers 400 naming it, with no ledger read. The route reads what `/v1/xrpl/metrics/peg` reads for that pair, plus the issuer's account. `components` lists four weighted components, each with its `value` from 0 to 1, its integer `weight` and its `contribution` = weight × value. The weights are `peg` 40, `spread` 20, `depth` 25 and `amm_gap` 15, summing to 100. Each value is clamped to [0, 1]: `peg` = |deviation_bps| / 200, from peg's unrounded headline `deviation_bps`; `spread` = spread_bps / 100, from the direct book's unrounded `spread_bps`; `depth` = 1 − depth_at_peg_50 / 100000, from peg's unrounded `depth_at_peg_50` in units of `asset` (more depth near the peg means less stress); and `amm_gap` = |amm_clob_gap_bps| / 100, where amm_clob_gap_bps = (amm_spot − clob_mid) / clob_mid × 10000 between the direct AMM pool's fee-free spot and the direct book's mid, 0 without a pool (a frozen or empty pool counts as no pool). A component whose input is missing (a one-sided direct book has no spread and no mid; an EUR asset without a stored ECB rate has no deviation and no depth at peg) has `value` 1 and counts its full weight. `score` is the sum of the unrounded contributions rounded half-up to an integer from 0 to 100, and `band` is decided on that integer score: `low` below 25, `elevated` from 25 to below 50, `high` from 50 to below 75 and `severe` from 75. An issuer global freeze gives `score` 100 and `band` `severe` with the reason `issuer_global_freeze`, and never `no_route`, even without a route; without a freeze and without a route between the asset and its peg default `score` and `band` are `null` with `no_route`; the components are listed in both cases. `baseline` compares the direct book (base `asset`, quote its peg default) with its stored 7-day series: 15-minute snapshots of the books of the registry stablecoins paired with XRP and with each other, read from one dedicated upstream, each orientation stored on its own (depth in its base); every pair this route reads is in that list, in its own order. Its seven figures, in this order, are `spread_bps`, `depth_bid_10`, `depth_ask_10`, `depth_bid_50`, `depth_ask_50`, `depth_bid_100` and `depth_ask_100`, each with its stored `points` in the window of the 672 15-minute slots ending at the latest recorded slot, `gaps` (672 − points, the slots with no stored point), `median` and `zscore` = (live − mean) / population standard deviation of the stored values, rounded half-up to 2 decimals (`null` when that deviation is 0), where live is the same statistic of the direct book read here: its spread / mid × 10000, not rounded to 2 decimals, and the funded base quantity of its bids and of its asks priced within 10, 50 and 100 bps of its mid, bounds included, as `/v1/xrpl/metrics/pressure` computes them (around the mid, not around the price on peg). A one-sided direct book has no live figure: every `zscore` is `null` and the medians are kept. A figure with fewer than 288 stored slots (3 days) is warming up: its `median` and `zscore` are `null` and `reasons` contains `warming_up`; `baseline` is `null` while every figure warms up. Every pair has `baseline: null` with `not_tracked` while the book series is not tracked; a stored series that cannot be read, or that lacks a figure, gives `baseline: null` with `baseline_unavailable`; the score, its band and the components are still served and never depend on the baseline. `reasons` lists `issuer_global_freeze` or `no_route` first, then at most one of `warming_up`, `not_tracked` and `baseline_unavailable`, so a global freeze while the book series is not tracked answers `["issuer_global_freeze", "not_tracked"]`, and is empty when none applies. For an EUR asset the price on peg is the stored ECB reference rate in USD per EUR, the latest on or before the answer's UTC date. The books are read at depth 100 (the same cached books as `/v1/xrpl/orderbook`), the pool through the same cache entry as `/v1/xrpl/amm/{a}/{b}` and the issuer through the same cached account entry as `/v1/xrpl/stablecoin/{asset}`; `meta` reports the lowest ledger, the oldest read and the worst cache state of these reads, the ECB rate and the stored series not included; the 7-day summary of the stored series is computed once per 15-minute slot, from the 672 slots ending at the latest recorded slot, and cached until that slot ends (a request made before the current slot is recorded gets the previous slot's summary). An issuer account that does not exist reads as no freeze; any other failed issuer or book read, or an AMM read that fails for another reason than a missing pool, fails the answer (503 `upstream-unavailable` when no node can serve it). The score, its band and the z-scores are defined computations over the ledger and the stored series, not advice. Values, contributions and medians are decimal strings, and z-scores decimal strings rounded half-up to 2 decimals. An answer is fresh for 4 seconds, the shortest policy of its reads.

## When to use

To score, from the XRP Ledger's own order books, AMM pool and issuer account, how stressed a registry stablecoin's liquidity is against its peg default, as one score with its band and the components behind it.

## When not to use

To read the peg deviation of each price route (use `/v1/xrpl/metrics/peg`), or to check that an issued currency is the canonical registry coin and read its issuer posture (use `/v1/xrpl/stablecoin/{asset}`); for an asset outside the registry, which this route refuses, read its order book (`/v1/xrpl/orderbook`) or its AMM pool (`/v1/xrpl/amm/{a}/{b}`).

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `asset` | query | yes | XRPL stablecoin of the registry whose liquidity stress is measured against its peg default, by its canonical code and issuer. `XRP`, or `CODE.issuer`: `CODE` is a 3-character standard code or 40 hexadecimal digits, and `issuer` is a classic XRPL address. Standard codes are case-sensitive: `usd` and `USD` are different tokens, so send the exact code. A standard code uses letters, digits or `?!@#$%^&*<>(){}[]\|` and is never `XRP`; percent-encode the symbols in a URL (for example `%3F` for `?`). A 40-hex code is read in any case, and the 40-hex form of a standard code means that code. | A stablecoin of the registry (see `/v1/xrpl/stablecoin/{asset}`); any other asset is rejected with 400. `XRP`, or `CODE.issuer`: `CODE` is a 3-character standard code or 40 hexadecimal digits, and `issuer` is a classic XRPL address. Standard codes are case-sensitive: `usd` and `USD` are different tokens, so send the exact code. A standard code uses letters, digits or `?!@#$%^&*<>(){}[]\|` and is never `XRP`; percent-encode the symbols in a URL (for example `%3F` for `?`). A 40-hex code is read in any case, and the 40-hex form of a standard code means that code. | `524C555344000000000000000000000000000000.rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/xrpl/metrics/liquidity-stress?asset=524C555344000000000000000000000000000000.rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De"
```

## Response example (200)

```json
{
  "components": [
    {
      "name": "peg",
      "value": "0.010874999978402401",
      "weight": 40,
      "contribution": "0.434999999136096054"
    },
    {
      "name": "spread",
      "value": "0.043290384254417998",
      "weight": 20,
      "contribution": "0.86580768508835997"
    },
    {
      "name": "depth",
      "value": "0",
      "weight": 25,
      "contribution": "0"
    },
    {
      "name": "amm_gap",
      "value": "0.012884941398014183",
      "weight": 15,
      "contribution": "0.193274120970212749"
    }
  ],
  "score": 1,
  "band": "low",
  "baseline": null,
  "reasons": [
    "not_tracked"
  ],
  "meta": {
    "ledger_index": 108267510,
    "as_of": "2026-11-11T20:23:03.000Z",
    "age_seconds": 0,
    "cache": "miss",
    "stale": false
  }
}
```

## Errors

- 400 [invalid-parameters](https://api.criptonlabs.com/errors/invalid-parameters.md)
- 400 [bad-request](https://api.criptonlabs.com/errors/bad-request.md)
- 429 [rate-limited](https://api.criptonlabs.com/errors/rate-limited.md)
- 503 [upstream-unavailable](https://api.criptonlabs.com/errors/upstream-unavailable.md)

## Caching

Fresh for 4 seconds; on upstream failure the last good value is served for up to 30 seconds (`meta.stale` is `true`), then the service answers 503. See the [freshness guide](https://api.criptonlabs.com/docs/guides/freshness.md).

## Rate limit

Tier `expensive`. See the [rate-limits guide](https://api.criptonlabs.com/docs/guides/rate-limits.md).

## MCP tool

The MCP tool `xrpl_metrics_liquidity_stress` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).
