# GET /v1/xrpl/metrics/arbitrage

Whether a pair's AMM pool and its order book are apart after the AMM fee: per direction the gap, the executable size and the profit after transfer fees.

## Purpose

Compares the AMM pool of `base`/`quote` with the pair's funded order book (up to 100 levels per side, both sides from one validated ledger: the same cached book as `/v1/xrpl/orderbook` at depth 100). Any pair is accepted; `quote` equal to `base` answers 400. `amm_to_clob` buys `base` on the pool and sells it into the bids, and `clob_to_amm` buys `base` from the asks and sells it into the pool. Each direction reports `gap_bps`, the gap in bps between the book's best price (the best bid for `amm_to_clob`, the best ask for `clob_to_amm`) and the pool's price after its trading fee; `executable_base`, the base quantity tradable against the book; and `net_quote_profit`, the quote profit of that size after transfer fees, `null` when a transfer rate cannot be read. With B and Q the pool's base and quote reserves, spot = Q / B its fee-free price in quote per base and f its trading fee as a decimal fraction (the `trading_fee` of `/v1/xrpl/amm/{a}/{b}`: `0.005` is 0.5 %), `amm_to_clob` has `gap_bps` = (best_bid − spot / (1 − f)) / (spot / (1 − f)) × 10000 and `clob_to_amm` has `gap_bps` = (spot × (1 − f) − best_ask) / best_ask × 10000, rounded half-up to 2 decimals. `status` is `open` when that reported `gap_bps` is above 0 and `no_opportunity` otherwise, so a gap below 0.005 bps is `no_opportunity`. For an open direction, `executable_base` comes from a walk of the book levels (the bids for `amm_to_clob`, the asks for `clob_to_amm`, best price first) against the closed-form marginal price of the pool, Q × B / ((B − x)² × (1 − f)) after buying x base from it and Q × B × (1 − f) / (B + y × (1 − f))² after selling y base into it: each level is taken until that marginal price reaches the level price, a level partly up to the size where it does, and the walk stops at equality. `net_quote_profit` follows the transfer-fee rule of an OfferCreate taker: the taker pays the transfer fee of the asset it sends, at its issuer's TransferRate / 1e9 (1e9, no fee, for XRP and for an issuer without a TransferRate), and the pool never pays one, so `amm_to_clob` gives Σ(take × bid price) ÷ (rate(base) / 1e9) − Q × x / ((B − x) × (1 − f)) × rate(quote) / 1e9 and `clob_to_amm` gives Q × y × (1 − f) / (B + y × (1 − f)) ÷ (rate(base) / 1e9) − Σ(take × ask price) × rate(quote) / 1e9, with x or y the `executable_base` and rate(base) and rate(quote) the TransferRate of each asset's issuer. A direction that is not open reports `executable_base` and `net_quote_profit` `"0"`, and one that cannot be evaluated (no pool, a frozen or empty pool, or the needed book side empty) also has `gap_bps` `null`. With `include_triangles=true` the answer adds `triangles`: the cycles XRP → RLUSD → USDC → XRP and XRP → USDC → RLUSD → XRP over the USD stablecoins of the registry, each with its `path`, `gap_bps` and `top_size_xrp`, both `null` when a leg's book side is empty or a transfer rate cannot be read. Each leg sells its input asset into the bids of the book with that asset as base, at the fee-inclusive leg rate best_bid ÷ (TransferRate / 1e9), with the TransferRate of the input asset's issuer (1e9 for XRP); `gap_bps` = (the product of the leg rates − 1) × 10000, and `top_size_xrp` is the smallest first-bid-level size of the legs, each in its leg's input asset and divided by the product of the preceding leg rates to carry it back to XRP. Without `include_triangles`, or with `false`, no triangle book is read and `triangles` is absent; any other value answers 400. The triangle books are read at depth 100 through the same cached books, the pool through the same cache entry as `/v1/xrpl/amm/{a}/{b}` and the transfer rates through the issuers' cached TransferRate; `meta` reports the lowest ledger, the oldest read and the worst cache state of the books and the pool, the transfer rates not included. A failed book read, a failed triangle 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 gaps, sizes and profits are defined computations over the ledger, not advice and not an executable quote. Bps fields are decimal strings rounded half-up to 2 decimals; quantities are decimal strings. An answer is fresh for 4 seconds, the shortest policy of its reads.

## When to use

To find whether a pair's AMM pool and its funded order book are apart after the AMM fee, in which direction, how much base the gap allows and the profit after transfer fees, optionally with the cycles of the USD registry stablecoins via XRP.

## When not to use

To estimate the cost of a trade of a given size, CLOB against AMM (use `/v1/xrpl/slippage`), or to read the order book levels (use `/v1/xrpl/orderbook`) or an AMM pool (use `/v1/xrpl/amm/{a}/{b}`); the answer measures the ledger and is not an executable quote.

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `base` | query | yes | Base currency of the pair. `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. | `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. | `XRP` |
| `quote` | query | yes | Quote currency of the pair, different from base. `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. | `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` |
| `include_triangles` | query | no | `true` adds `triangles`, the cycles of the USD stablecoins of the registry (RLUSD, USDC) via XRP; `false` or omitted leaves them out and reads no triangle book. | `true` or `false`, in lower case; any other value is rejected with 400. | `true` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/xrpl/metrics/arbitrage?base=XRP&quote=524C555344000000000000000000000000000000.rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De&include_triangles=true"
```

## Response example (200)

```json
{
  "amm_to_clob": {
    "status": "no_opportunity",
    "gap_bps": "-27.92",
    "executable_base": "0",
    "net_quote_profit": "0"
  },
  "clob_to_amm": {
    "status": "no_opportunity",
    "gap_bps": "-43.47",
    "executable_base": "0",
    "net_quote_profit": "0"
  },
  "triangles": [
    {
      "path": [
        "XRP",
        "RLUSD",
        "USDC",
        "XRP"
      ],
      "gap_bps": "-16.57",
      "top_size_xrp": "4.168124"
    },
    {
      "path": [
        "XRP",
        "USDC",
        "RLUSD",
        "XRP"
      ],
      "gap_bps": "-13.59",
      "top_size_xrp": "25.034013397752695592"
    }
  ],
  "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_arbitrage` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).
