Sandbox version
For experimental use only. Proceed with caution.
composite
Unified search across tokens, MPTs, NFTs, collections, and accounts
get
/composite/search
operationId: composite-search

Single GET endpoint that returns matches across every asset/entity domain for a free-text query. Five buckets — tokens (IOU), mpts (XLS-33d Multi-Purpose Tokens), nfts, collections, accounts. Classification rules: a classic XRPL address (r + 24–34 base58) routes to accounts; a 64-char hex string routes to nfts by NFTokenID; a 48-char hex string routes to mpts by MPTokenIssuance ID; anything else triggers a case-insensitive substring match across token name / ticker / currency code, MPT XLS-89 name / ticker / issuer fields, NFT collection name, and account name. Each bucket returns up to limit items (default 10, max 25).

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
q
required
string
Free-text query (1–100 chars). Classified on the server: a classic XRPL address routes to `accounts` (and surfaces any AMM `pools` whose amm_id / owner is that address); a 64-char hex string routes to `nfts` by NFTokenID; a 48-char hex string routes to `mpts` by MPTokenIssuance ID; anything else triggers a case-insensitive substring match across token name/ticker, NFT collection name, MPT name/ticker, account name, and AMM pools (amm_id, owner, asset codes/issuers, asset display names/tickers).
limit
integer10
Responses
200
application/json
Successful response
FieldTypeDescription
tokens
object[]
Tokens (IOU) matching the query (up to `limit`).
tokens[].id
string
Token UUID primary key.
tokens[].currencyCode
string
Token currency code (3-char ISO or 40-char hex).
tokens[].issuerAddress
string
Issuer classic XRPL address.
tokens[].name
object
Display name (null when metadata missing).
tokens[].ticker
object
Normalized display code (null when metadata missing).
tokens[].iconUrl
object
Icon URL (null when metadata missing).
mpts
object[]
Multi-Purpose Tokens matching the query (up to `limit`). Populated by direct MPTokenIssuance ID lookup or by ILIKE on XLS-89 name / ticker / issuer fields.
mpts[].id
string
MPTokenIssuance ID (hex string).
mpts[].issuanceId
string
Same as `id`; surfaced under the MPT-canonical name for shape parity with `/mpt/list` responses.
mpts[].issuerAddress
string
Issuer classic XRPL address.
mpts[].name
object
Curated XLS-89 display name (null when metadata not yet resolved).
mpts[].ticker
object
Curated XLS-89 ticker (null when not declared).
mpts[].iconUrl
object
Curated XLS-89 icon URL (null when not declared).
mpts[].assetClass
object
XLS-89 asset class (`rwa` / `memes` / etc.).
nfts
object[]
NFTs matching the query (up to `limit`). Populated by direct NFTokenID lookup when `q` is a 64-char hex string, OR by substring match against `nft_metadata.name` / `description` and against `nfToken.tokenId` / `issuer` for partial-prefix queries.
nfts[].tokenId
string
64-char hex NFTokenID.
nfts[].issuer
string
Minter classic XRPL address.
nfts[].owner
string
Current owner classic XRPL address.
nfts[].taxon
integer
NFToken taxon (groups tokens into a collection).
nfts[].uri
object
Hex-encoded URI from the mint tx (null when absent).
collections
object[]
NFT collections matching the query (up to `limit`).
collections[].id
string
Collection UUID primary key.
collections[].issuer
string
Minter classic XRPL address (part of the canonical slug).
collections[].taxon
integer
NFToken taxon (second half of the canonical slug).
collections[].slug
string
Canonical slug — `issuer:taxon`.
collections[].name
object
Collection display name (null when not set).
collections[].imageUrl
object
Collection cover image URL (null when not set).
collections[].tokenCount
integer
Number of NFTs currently in the collection.
accounts
object[]
Accounts matching the query (up to `limit`). Populated directly when `q` is a classic XRPL address.
accounts[].address
string
Classic XRPL address.
accounts[].name
object
Display name (null when metadata missing).
accounts[].iconUrl
object
Icon URL (null when metadata missing).
accounts[].category
object
Account category: exchange | issuer | project | validator | launchpad | amm | gateway | other.
accounts[].verified
boolean
True when the account has been verified by a curated source.
pools
object[]
AMM pools matching the query (up to `limit`). Populated by ILIKE on `amm_id`, `owner_address`, both asset currency codes, both asset issuer addresses, and each asset's display name / ticker.
pools[].id
string
Pool UUID primary key.
pools[].ammId
string
On-ledger AMM account identifier (XRPL classic address).
pools[].pairLabel
string
`<asset1 ticker> / <asset2 ticker>` display label.
pools[].asset1Currency
string
Asset1 currency code.
pools[].asset1Issuer
object
Asset1 issuer (null for XRP).
pools[].asset2Currency
string
Asset2 currency code.
pools[].asset2Issuer
object
Asset2 issuer (null for XRP).
pools[].tradingFeeBps
integer
Trading fee in basis points.
Example
Json
{
  "tokens": [
    {
      "id": "0046f20d-4aa3-4c2e-b975-80d9d0895e7a",
      "currencyCode": "4249547800000000000000000000000000000000",
      "issuerAddress": "rBitcoiNXev8VoVxV7pwoQx1sSfonVP9i3",
      "name": "BITx",
      "ticker": "BITx",
      "iconUrl": "https://bitx.fyi/bitx-images/bitx-logo.png"
    }
  ],
  "mpts": [],
  "nfts": [],
  "collections": [],
  "accounts": [],
  "pools": []
}
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": []
}