Sandbox version
For experimental use only. Proceed with caution.
tokens
Search tokens
get
/token/search
operationId: token-search

Case-insensitive substring search over token currencyCode and issuer domain. The query matches either field — useful for typeahead/autocomplete UIs. Results are ordered newest-first and include metadata and issuer details.

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 token symbol, name, or issuer (1–100 chars).
Responses
200
application/json
Successful response
FieldTypeDescription
items
object[]
Page of results.
items[].currency
string
Currency code (3-char ISO or 40-char hex).
items[].issuer
string
XRPL classic address of the issuer.
items[].id
string
Internal UUID primary key for the token record.
items[].slug
string
Natural token identifier in `<currency>.<issuer>` form (e.g. `USD.rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B`). Round-trips through `/v1/token/{slug}` for detail lookup and is the canonical key for fetching this token's orderbook depth via `/v1/liquidity/orderbook-depth` or similar pair-scoped endpoints.
items[].launched_at
object
Unix-seconds timestamp of the token's first on-ledger appearance. Present only when the request had `metadata=true`.
items[].launched_ledger_index
object
Ledger sequence of the token's first trustline or offer. Present only when the request had `metadata=true`.
items[].indicators
object
Boolean trust-signal indicators for the token. Named `indicators` rather than `flags` to avoid confusion with on-chain XRPL issuer flags. Present only when the request had `metadata=true`.
items[].indicators.is_lp_burnt
boolean
True when AMM LP tokens for this pool were permanently burned.
items[].indicators.is_anti_snipe
boolean
True when issuer has anti-snipe protections active.
items[].indicators.is_first_ledger_launch
boolean
True when the token launched in its first ledger of existence.
items[].indicators.is_whale_free
boolean
True when no single holder exceeds the 5% whale threshold.
items[].indicators.is_first_token_for_issuer
boolean
True when this is the issuer's earliest token by creation time. Aggregators display this as "First token: 1".
items[].indicators.is_renounced
object
True when the issuer has disabled its master key with no regular key set (no further minting possible). Derived from issuer AccountRoot flags; NULL when issuer data is missing.
items[].metadata
object
Curated / slow-changing metadata about the token and its issuer. Dev-wallet attribution lives at `metadata.token.dev_address`. Present only when the request had `metadata=true`.
items[].metadata.token
object
items[].metadata.token.token_name
object
Display name of the token (alias of `name`).
items[].metadata.token.name
object
Display name of the token.
items[].metadata.token.ticker
object
Uppercase 3–5 letter abbreviation suitable for compact UI display (e.g. "USD", "RLUSD", "FUZZY"). Derived from the curated metadata ticker when present, otherwise from the normalized currency code; non-alphanumeric characters stripped, then truncated to 5 chars and uppercased.
items[].metadata.token.code
string
Raw on-chain currency code exactly as stored on the ledger — either the 3-char ISO form (e.g. `USD`) or the 40-char hex form (e.g. `524C555344000000000000000000000000000000`). Never normalized.
items[].metadata.token.code_normalized
object
Human-readable form of `code`. Hex codes are decoded to UTF-8 when printable (e.g. `524C555344000000000000000000000000000000` → `RLUSD`); 3-char ISO codes pass through unchanged. Use this for display when you want the full unabbreviated label.
items[].metadata.token.desc
object
Token project description.
items[].metadata.token.icon
object
URL to the token logo image.
items[].metadata.token.asset_class
object
Broad asset category (e.g. `stablecoin`, `native`, `meme`).
items[].metadata.token.asset_subclass
object
Narrower asset sub-category (e.g. `fiat-backed`, `algorithmic`).
items[].metadata.token.display_decimals
object
Suggested decimal places for UI rendering, when the metadata resolver has one.
items[].metadata.token.trust_level
object
Trust rating 0–3: 0 = unknown, 1 = listed, 2 = trusted list, 3 = curated.
items[].metadata.token.verified
boolean
True when the issuer has been attested by a crawler or operator (mirror of `metadata.issuer.verified`).
items[].metadata.token.urls
object[]
External links associated with the token (website, socials, whitepaper, …).
items[].metadata.token.website
object
Primary website URL, extracted from `urls` for convenience.
items[].metadata.token.twitter
object
Twitter / X handle or profile URL, extracted from `urls` for convenience.
items[].metadata.token.created
object
Unix-seconds timestamp of the token's first on-ledger appearance (mirror of top-level `launched_at`).
items[].metadata.token.dev_address
object
Dev / hot-wallet address — first non-issuer recipient of the token from the issuer. NULL until a distribution tx has been observed.
items[].metadata.issuer
object
items[].metadata.issuer.name
object
Human-readable issuer name.
items[].metadata.issuer.domain
object
Verified domain from the issuer's AccountRoot.
items[].metadata.issuer.icon
object
Resolved issuer avatar URL.
items[].metadata.issuer.kyc
object
True when the issuer has completed third-party KYC.
items[].metadata.issuer.trust_level
object
Issuer trust rating 0–3 (same scale as token trust_level).
items[].metadata.issuer.verified
boolean
True when the issuer's identity has been attested by a crawler or operator.
items[].metadata.issuer.is_blackholed
boolean
True when the issuer account has disabled its master key with no regular key — no further minting possible.
items[].metadata.issuer.advisory_severity
object
Advisory severity on the issuer account: caution | warning | danger. NULL = no advisory.
items[].metadata.issuer.advisory
object
Human-readable advisory message — most commonly set by the Xaman blacklist sync.
items[].metrics
object
Live and rolling market state for the token: price, supply/market_cap/fdv, vesting, rolling price change / volume / txn windows, takers, buy-sell split, and the composite `quality_score`. Present only when the request had `metrics=true`.
items[].metrics.trustlines
integer
Current number of trustlines set for the token.
items[].metrics.holders
integer
Current number of accounts with a positive balance.
items[].metrics.supply
string
Total issued supply (decimal string).
items[].metrics.circulating_supply
object
Supply minus issuer-held / locked (decimal string). NULL until first reconciliation.
items[].metrics.price
object
Latest observed XRP-denominated price (decimal string).
items[].metrics.market_cap
object
Price × circulating_supply, XRP-denominated (decimal string). NULL when price is unknown.
items[].metrics.fdv
object
Fully-diluted valuation: Price × total supply, XRP-denominated. Contrasts with `market_cap` which uses circulating supply.
items[].metrics.tvl
object
Total Value Locked in XRP — sum of the latest TVL across every AMM pool pairing this token on either side. NULL when the token does not appear in any AMM pool.
items[].metrics.vesting
object
Escrowed IOU vesting schedule for pending escrows.
items[].metrics.vesting.total
object
Currently-vested amount — sum across pending escrows for this `(currency, issuer)`. Decimal string; zero when no pending escrows exist.
items[].metrics.vesting.next_7d
object
Portion of `total` whose `finish_after` falls in the next 7d. Escrows without a `finish_after` are excluded.
items[].metrics.vesting.next_30d
object
Portion of `total` whose `finish_after` falls in the next 30d. Superset of `next_7d`.
items[].metrics.price_change
object
Rolling price change per window. Each entry carries the absolute XRP delta (`absolute`) and the percentage (`percent`). 24h/7d windows fall back to the inception price when the token is younger than the window (see `since_inception`).
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 volume windows plus lifetime total and XRPL dominance.
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
Summed XRP-denominated volume over the last 7d (decimal string). NULL when no data is available for the window.
items[].metrics.volume.total
object
Cumulative lifetime base-amount volume for the pair. NULL when the token has no indexed trade pair.
items[].metrics.volume.dominance
object
This token's share of all-XRPL volume, per window.
items[].metrics.txn
object
Rolling trade-count windows per same-length bucket.
items[].metrics.txn.last_5m
object
items[].metrics.txn.last_1h
object
items[].metrics.txn.last_6h
object
items[].metrics.txn.last_24h
object
items[].metrics.txn.last_7d
object
Trade count over the last 7d. NULL when no data is available for the window.
items[].metrics.takers_24h
integer
Distinct taker addresses over the last 24h.
items[].metrics.takers_7d
integer
Distinct taker addresses over the last 7d.
items[].metrics.buy_sell_24h
object
Buy/sell breakdown over the last 24h, inferred from the taker's XRP balance delta per trade (positive = sell, negative = buy). Accurate for XRP-quoted pairs; token/token pairs report zeros.
items[].metrics.buy_sell_24h.buys
object
items[].metrics.buy_sell_24h.sells
object
items[].metrics.quality_score
string
Composite 0–100 quality score. Rubric (additive, capped at 100): +20 issuer verified, +15 issuer renounced (master key disabled, no regular key), +15 metadata present (name + icon), +10 trustlines ≥ 100, +10 LP burnt, +10 whale-free, +10 recent activity (≥10 trades in last 24h), +10 TVL > 0.
nextCursor
object
Cursor to fetch the next page, or null if this is the last page.
Example
Json
{
  "items": [
    {
      "currency": "string",
      "issuer": "string",
      "id": "00000000-0000-0000-0000-000000000000",
      "slug": "string",
      "launched_at": 1745798400,
      "launched_ledger_index": 0,
      "indicators": {
        "is_lp_burnt": false,
        "is_anti_snipe": false,
        "is_first_ledger_launch": false,
        "is_whale_free": false,
        "is_first_token_for_issuer": false,
        "is_renounced": false
      },
      "metadata": {
        "token": {
          "token_name": "string",
          "name": "string",
          "ticker": "string",
          "code": "string",
          "code_normalized": "string",
          "desc": "string",
          "icon": "string",
          "asset_class": "string",
          "asset_subclass": "string",
          "display_decimals": 0,
          "trust_level": 0,
          "verified": false,
          "urls": [
            {
              "url": "string",
              "type": "string"
            }
          ],
          "website": "string",
          "twitter": "string",
          "created": 1745798400,
          "dev_address": "string"
        },
        "issuer": {
          "name": "string",
          "domain": "string",
          "icon": "string",
          "kyc": false,
          "trust_level": 0,
          "verified": false,
          "is_blackholed": false,
          "advisory_severity": "string",
          "advisory": "string"
        }
      },
      "metrics": {
        "trustlines": 0,
        "holders": 0,
        "supply": "string",
        "circulating_supply": "string",
        "price": "string",
        "market_cap": "string",
        "fdv": "string",
        "tvl": "string",
        "vesting": {
          "total": "string",
          "next_7d": "string",
          "next_30d": "string"
        },
        "price_change": {
          "last_5m": {
            "absolute": "string",
            "percent": "string"
          },
          "last_1h": {
            "absolute": "string",
            "percent": "string"
          },
          "last_6h": {
            "absolute": "string",
            "percent": "string"
          },
          "last_24h": {
            "absolute": "string",
            "percent": "string",
            "since_inception": false
          },
          "last_7d": {
            "absolute": "string",
            "percent": "string",
            "since_inception": false
          }
        },
        "volume": {
          "last_5m": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_1h": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_6h": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_24h": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_7d": "string",
          "total": "string",
          "dominance": {
            "last_24h": "string"
          }
        },
        "txn": {
          "last_5m": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "string"
          },
          "last_1h": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "string"
          },
          "last_6h": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "string"
          },
          "last_24h": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "string"
          },
          "last_7d": 0
        },
        "takers_24h": 0,
        "takers_7d": 0,
        "buy_sell_24h": {
          "buys": {
            "txns": 0,
            "traders": 0,
            "xrp": "string"
          },
          "sells": {
            "txns": 0,
            "traders": 0,
            "xrp": "string"
          }
        },
        "quality_score": "string"
      }
    }
  ],
  "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": []
}