amm
Free-text search for AMM pools
get
/liquidity/pools/search
operationId: pool-search

Returns up to limit AMM pools matching q via case-insensitive substring against amm_id, owner_address, both asset currency codes / issuer addresses, and each asset's display name / ticker. Mirrors /token/search and /mpt/search for the AMM domain.

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
cursor
string
limit
integer20
query
required
string
Free-text search over `amm_id`, `owner_address`, both asset currency codes / issuer addresses, and each asset's display name / ticker (1–100 chars).
Responses
200
application/json
Successful response
FieldTypeDescription
items
object[]
Page of results.
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.
nextCursor
object
Cursor to fetch the next page, or null if this is the last page.
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
        }
      }
    }
  ],
  "nextCursor": "string"
}
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": []
}