Sandbox version
For experimental use only. Proceed with caution.
amm
List liquidity pools
get
/liquidity/pools
operationId: pool-list

Paginated list of indexed AMM pools. Uses 1-indexed page + pageSize and returns total / pageCount. Optional search filters case-insensitively across amm_id, owner_address, both asset currency codes / issuer addresses, and each asset's display name / ticker. Optional denomination (XRP or currency.issuer) filters to pools where one side matches AND flips the response so the matched asset always lands in assets.asset1 — useful for rendering "all USDC pools" with USDC consistently on the denominator side. Default sort is top (composite depth+flow ranking, descending). metadata defaults to true; metrics defaults to false (opt in explicitly because the windowed aggregates cost extra DB work). When metadata=true each row carries per-asset metadata (assets.asset1.metadata, assets.asset2.metadata) and pool-level metadata (metadata.pair_label, metadata.trading_fee_percent, metadata.owner_metadata); when metrics=true each row carries metrics.tvl.{value, change.last_24h}, windowed metrics.volume (5m/1h/6h/24h/7d + total + dominance.last_24h) and metrics.swaps (5m/1h/6h/24h/7d), windowed metrics.deposits.last_24h / metrics.withdrawals.last_24h, metrics.fees.last_24h, metrics.apr.last_24h, metrics.price ratios with metrics.price_change.last_24h.{absolute, percent}, metrics.lp_holders, metrics.indicators.{is_destroyed, is_empty}.

Unlock protected endpoints

Enter your Bearer token once to enable every protected route in this API reference.

HTTP bearer

Saved for this browser tab only. The credential is never sent until you test an endpoint.

Authorizations
NameLocationDetails
BearerAuthAuthorization header · bearerJWT issued by the Honeycluster auth service for the `indexer` audience. Present as `Authorization: Bearer <token>`.
Query Parameters
NameTypeDefaultDescription
page
integer1
pageSize
integer20
search
string
denomination
string
metadata
boolean
metrics
boolean
sort
enum<string>"top"
Available
createdupdatedledger_indextrading_feetvlvolume_24hswaps_24hlp_holders
sortDir
enum<string>"desc"
Available
ascdesc
Responses
200
application/json
Successful response
FieldTypeDescription
items
object[]
Items on the current page.
items[].id
string
Internal UUID primary key for the pool.
items[].amm_id
string
On-ledger AMM account identifier.
items[].owner_address
object
Address that created the AMM; NULL when unknown.
items[].lp_token
object
LP token reference (currency + issuer = the AMM account).
items[].lp_token.currency
string
Currency code (3-char ISO or 40-char hex).
items[].lp_token.issuer
object
Issuer XRPL address; NULL for native XRP.
items[].ledger_index
integer
Ledger sequence of the most recent pool state update.
items[].created_at
integer
Record creation timestamp, Unix-seconds.
items[].updated_at
integer
Record update timestamp, Unix-seconds.
items[].assets
object
The two pool assets with current reserves and joined token metadata.
items[].assets.asset1
object
items[].assets.asset1.currency
string
Currency code (3-char ISO or 40-char hex).
items[].assets.asset1.issuer
object
Issuer XRPL address; NULL for native XRP.
items[].assets.asset1.code
string
Raw on-chain currency code (3-char ISO or 40-char hex).
items[].assets.asset1.code_normalized
string
UTF-8-decoded currency code when the raw code is hex-encoded; otherwise the raw code unchanged.
items[].assets.asset1.ticker
object
Display ticker (≤5 chars uppercased). Falls back to a normalized currency code when no curated ticker is available.
items[].assets.asset1.reserve
string
Current reserve balance, decimal string.
items[].assets.asset1.metadata
object
Token metadata for this asset, or NULL for native XRP / unknown tokens.
items[].assets.asset2
object
items[].assets.asset2.currency
string
Currency code (3-char ISO or 40-char hex).
items[].assets.asset2.issuer
object
Issuer XRPL address; NULL for native XRP.
items[].assets.asset2.code
string
Raw on-chain currency code (3-char ISO or 40-char hex).
items[].assets.asset2.code_normalized
string
UTF-8-decoded currency code when the raw code is hex-encoded; otherwise the raw code unchanged.
items[].assets.asset2.ticker
object
Display ticker (≤5 chars uppercased). Falls back to a normalized currency code when no curated ticker is available.
items[].assets.asset2.reserve
string
Current reserve balance, decimal string.
items[].assets.asset2.metadata
object
Token metadata for this asset, or NULL for native XRP / unknown tokens.
items[].metadata
object
Pool-level curated / derived metadata. Present only when the request had `metadata=true` (default).
items[].metadata.pair_label
string
`<asset1 ticker> / <asset2 ticker>` label. Falls back to raw currency codes when tickers are unavailable.
items[].metadata.trading_fee_bps
integer
Trading fee in basis points (0–1000; 1000 = 1%).
items[].metadata.trading_fee_percent
string
Trading fee as a percentage decimal string (e.g. "0.5" for 50 bps).
items[].metadata.owner_metadata
object
Metadata for the AMM's `owner_address`, or NULL when the owner is unknown / anonymous.
items[].metrics
object
Live and rolling pool metrics (TVL, volume, swaps, fees, price, depth). Present only when the request had `metrics=true` (defaults to `false`).
items[].metrics.lp_token_supply
string
Outstanding LP tokens, decimal string.
items[].metrics.tvl
object
items[].metrics.tvl.value
object
Latest TVL for the pool, decimal string denominated in XRP — sum of each side's reserve × that side's XRP-price (sourced from `token_xrp_price_v`). NULL when neither side has a resolvable XRP price.
items[].metrics.tvl.asset1_xrp_value
object
Asset1 reserve × asset1 XRP-price, decimal string in XRP. NULL when the asset1 side has no resolvable XRP price.
items[].metrics.tvl.asset2_xrp_value
object
Asset2 reserve × asset2 XRP-price, decimal string in XRP. NULL when the asset2 side has no resolvable XRP price.
items[].metrics.tvl.confidence
object
Pricing-confidence label. `direct` — XRP-paired pool (TVL/volume use the AMM's own implied rate, not a bridge price), or an IOU/IOU pool where both sides are priced via their own XRP-paired ohlcv data and fresh (last 24h). `bridged` — IOU/IOU pool with stablecoin-shortcut pricing on at least one side. `stale` — IOU/IOU pool where any side's last close is older than 24h. `unpriced` — IOU/IOU pool with at least one side that has no resolvable XRP price.
items[].metrics.tvl.change
object
TVL change per window. Currently only `last_24h`; additional windows may light up over time.
items[].metrics.price
object
items[].metrics.price.asset1_per_asset2
object
asset1_reserve / asset2_reserve — price of asset2 in asset1 terms. NULL when asset2_reserve is zero.
items[].metrics.price.asset2_per_asset1
object
asset2_reserve / asset1_reserve — price of asset1 in asset2 terms. NULL when asset1_reserve is zero.
items[].metrics.price_change
object
Rolling price change per window, sourced from per-pool OHLCV (`pool_ohlcv_1h`). `absolute` is the `asset2_per_asset1` swap-implied price delta; `percent` is dimensionless. Window entries are `null/null` when the pool had no swap in the window. Mirrors `tokenMetrics.price_change`.
items[].metrics.price_change.last_5m
object
items[].metrics.price_change.last_1h
object
items[].metrics.price_change.last_6h
object
items[].metrics.price_change.last_24h
object
items[].metrics.price_change.last_7d
object
items[].metrics.volume
object
Rolling swap volume per window, denominated in XRP (each side's asset amount × XRP-price, summed across buckets).
items[].metrics.volume.last_5m
object
items[].metrics.volume.last_1h
object
items[].metrics.volume.last_6h
object
items[].metrics.volume.last_24h
object
items[].metrics.volume.last_7d
object
items[].metrics.volume.total
string
Cumulative lifetime swap volume, decimal string in raw asset1 currency units (this is the only column that has not been re-priced into XRP yet — kept as-is for backwards compatibility with existing dashboards; will be revisited).
items[].metrics.volume.dominance
object
This pool's share of all-pools volume, per window.
items[].metrics.swaps
object
items[].metrics.swaps.last_5m
object
items[].metrics.swaps.last_1h
object
items[].metrics.swaps.last_6h
object
items[].metrics.swaps.last_24h
object
items[].metrics.swaps.last_7d
integer
Swap count over the last 7d.
items[].metrics.deposits
object
Deposit-event counts per window.
items[].metrics.deposits.last_24h
object
items[].metrics.withdrawals
object
Withdraw-event counts per window.
items[].metrics.withdrawals.last_24h
object
items[].metrics.fees
object
Trading fees collected per window, denominated in XRP.
items[].metrics.fees.last_24h
string
Estimated trading fees collected in the last 24h — `volume_24h × trading_fee_bps / 10000`, decimal string in XRP.
items[].metrics.fees.last_7d
string
Estimated trading fees collected in the last 7d — `volume_7d × trading_fee_bps / 10000`, decimal string in XRP.
items[].metrics.apr
object
Annualised-fee return on TVL per window.
items[].metrics.apr.last_24h
object
APR annualised from the last 24h of fees — `fees.last_24h × 365 / tvl × 100` (percentage decimal). NULL when TVL is unknown / zero. Both fees and TVL are XRP-denominated, so this is a true APR figure.
items[].metrics.apr.last_7d
object
APR annualised from the last 7d of fees — `fees.last_7d × (365 / 7) / tvl × 100` (percentage decimal). NULL when TVL is unknown / zero.
items[].metrics.lp_holders
integer
Distinct accounts holding a positive LP-token trustline balance.
items[].metrics.indicators
object
items[].metrics.indicators.is_destroyed
boolean
True when the AMM has been removed from the ledger.
items[].metrics.indicators.is_empty
boolean
True when both reserves are zero / near-zero.
page
integer
1-indexed page number of the returned page.
pageSize
integer
Items per page (echoed from the request).
total
integer
Total number of items across all pages.
pageCount
integer
Total number of pages at the requested pageSize.
Example
Json
{
  "items": [
    {
      "id": "3c4a3de8-4218-400c-8c55-87dc27206753",
      "amm_id": "rEgH8Y8nF9XuvvRECnp6e9VRZqKM3KZUtN",
      "owner_address": "rOwnerExample1234567890",
      "lp_token": {
        "currency": "03CE3395056E7BEDE14E4CA83D6B80FF83D51F97",
        "issuer": "rEgH8Y8nF9XuvvRECnp6e9VRZqKM3KZUtN"
      },
      "ledger_index": 103801288,
      "created_at": 1745212800,
      "updated_at": 1745798400,
      "assets": {
        "asset1": {
          "currency": "XRP",
          "issuer": null,
          "code": "XRP",
          "code_normalized": "XRP",
          "ticker": "XRP",
          "reserve": "639300",
          "metadata": null
        },
        "asset2": {
          "currency": "5048494E495800000000000000000000000000",
          "issuer": "rPHNIXIssuerExample1234567890",
          "code": "5048494E495800000000000000000000000000",
          "code_normalized": "PHNIX",
          "ticker": "PHNIX",
          "reserve": "589000000",
          "metadata": {
            "name": "Phineas",
            "ticker": "PHNIX",
            "icon": "https://cdn.honeycluster.dev/icons/phnix.png",
            "asset_class": null,
            "verified": true
          }
        }
      },
      "metadata": {
        "pair_label": "XRP / PHNIX",
        "trading_fee_bps": 34,
        "trading_fee_percent": "0.34",
        "owner_metadata": {
          "name": null,
          "verified": false
        }
      },
      "metrics": {
        "lp_token_supply": "267207784.32",
        "tvl": {
          "value": "639300",
          "asset1_xrp_value": "319650",
          "asset2_xrp_value": "319650",
          "confidence": "direct",
          "change": {
            "last_24h": {
              "absolute": "12500",
              "percent": "1.99"
            }
          }
        },
        "price": {
          "asset1_per_asset2": "0.00108540",
          "asset2_per_asset1": "921.42"
        },
        "price_change": {
          "last_5m": {
            "absolute": null,
            "percent": null
          },
          "last_1h": {
            "absolute": null,
            "percent": null
          },
          "last_6h": {
            "absolute": "0.00004",
            "percent": "4.10"
          },
          "last_24h": {
            "absolute": "0.00012",
            "percent": "12.4"
          },
          "last_7d": {
            "absolute": "0.00031",
            "percent": "31.5"
          }
        },
        "volume": {
          "last_5m": {
            "value": "420.5",
            "change_absolute": "15",
            "change_percent": "3.7"
          },
          "last_1h": {
            "value": "4120.8",
            "change_absolute": "120",
            "change_percent": "3.0"
          },
          "last_6h": {
            "value": "14580.2",
            "change_absolute": "1500",
            "change_percent": "11.5"
          },
          "last_24h": {
            "value": "46300",
            "change_absolute": "5800",
            "change_percent": "14.3"
          },
          "last_7d": "956100",
          "total": "4218750",
          "dominance": {
            "last_24h": "2.1093"
          }
        },
        "swaps": {
          "last_5m": {
            "value": 4,
            "change_absolute": 1,
            "change_percent": "33.3"
          },
          "last_1h": {
            "value": 38,
            "change_absolute": 6,
            "change_percent": "18.7"
          },
          "last_6h": {
            "value": 187,
            "change_absolute": 22,
            "change_percent": "13.3"
          },
          "last_24h": {
            "value": 1675,
            "change_absolute": 188,
            "change_percent": "12.6"
          },
          "last_7d": 11842
        },
        "deposits": {
          "last_24h": {
            "value": 3,
            "change_absolute": -1,
            "change_percent": "-25.0"
          }
        },
        "withdrawals": {
          "last_24h": {
            "value": 4,
            "change_absolute": 1,
            "change_percent": "33.3"
          }
        },
        "fees": {
          "last_24h": "155.98",
          "last_7d": "3250.75"
        },
        "apr": {
          "last_24h": "8.9",
          "last_7d": "26.3"
        },
        "lp_holders": 485,
        "indicators": {
          "is_destroyed": false,
          "is_empty": false
        }
      }
    }
  ],
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "pageCount": 0
}
400
application/json
Invalid input data
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}
401
application/json
Authorization not provided
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}
403
application/json
Insufficient access
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}
404
application/json
Not found
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "NOT_FOUND",
  "message": "Not found",
  "issues": []
}
500
application/json
Internal server error
FieldTypeDescription
message
string
The error message
code
string
The error code
issues
object[]
An array of issues that were responsible for the error
issues[].message
string
Example
Json
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}