nftokens
Free-text search across NFTs and collections
get
/nft/search
operationId: nft-search

Cursor-paginated free-text search scoped to the NFT domain. Returns both matched NFTs (in nfts[]) and matched collections (in collections[]) so a single query can drive a unified result page. NFT match: token_id, issuer, owner, and asset name (from nft_metadata). Collection match: issuer, curated name, and description on nft_collections. Use includeNfts=false / includeCollections=false to scope to one half. Distinct from the cross-domain /search endpoint (which mixes tokens / NFTs / collections / accounts) — this is the NFT-focused variant for marketplace UIs. Pagination state is encoded across both kinds inside nextCursor; null when neither kind has more rows.

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 applied across NFT identity / metadata (`token_id`, `issuer`, `owner`, asset `name`) and collection identity / metadata (`issuer`, `name`, `description`).
includeNfts
boolean
includeCollections
boolean
metadata
boolean
metrics
boolean
Responses
200
application/json
Successful response
FieldTypeDescription
nfts
object[]
Matched NFT rows, ordered by `created_at DESC` (newest mints first). Empty when `includeNfts=false` or no matches.
nfts[].id
string
Internal UUID primary key for the NFT record.
nfts[].token_id
string
XRPL NFTokenID (64-char hex).
nfts[].issuer
string
Minter XRPL address.
nfts[].owner
string
Current owner XRPL address.
nfts[].taxon
integer
Collection-grouping identifier assigned at mint.
nfts[].serial_number
integer
Sequential number within (issuer, taxon).
nfts[].uri
object
On-chain URI — `ipfs://…` or `https://…`.
nfts[].transfer_fee
integer
Royalty in basis points (0–50000; 50000 = 50%).
nfts[].flags
object
Decoded XLS-20 flag bits.
nfts[].flags.burnable
boolean
Flag bit 0x01 — issuer can burn the NFT.
nfts[].flags.only_xrp
boolean
Flag bit 0x02 — sale offers must be XRP-denominated.
nfts[].flags.trust_line
boolean
Flag bit 0x04 — issuer trust line created on mint.
nfts[].flags.transferable
boolean
Flag bit 0x08 — NFT can be transferred by non-issuers.
nfts[].flags.mutable
boolean
Flag bit 0x10 — URI is mutable (XLS-46).
nfts[].burned
boolean
True when the NFT has been burned.
nfts[].burned_at
object
Timestamp of the burn as Unix-seconds, if any.
nfts[].minted_at_ledger
integer
Ledger sequence where the NFT was minted.
nfts[].mint_tx_hash
object
Hash of the NFTokenMint transaction that created this NFT.
nfts[].metadata
object
Asset metadata and (optional) collection context. Present when `metadata=true` (the default); omitted entirely when the caller passes `metadata=false`.
nfts[].metadata.asset
object
nfts[].metadata.asset.name
object
Display name from resolved metadata.
nfts[].metadata.asset.description
object
Project / artwork description.
nfts[].metadata.asset.meta_url
object
CDN URL of the resolved metadata JSON (backed by S3).
nfts[].metadata.asset.media_url
object
CDN URL of the primary media asset (backed by S3).
nfts[].metadata.asset.external_url
object
External project or marketplace link.
nfts[].metadata.asset.marketplace
object
Launchpad that minted this NFT (e.g. "xrp.cafe", "OnXRP", "XPMarket"). Resolved by minter address with fallback to attribution from upstream metadata.
nfts[].metadata.collection
object
nfts[].metrics
object
Per-NFT market state — sales count, lifetime volume, last sale, and the current lowest open XRP sell offer for this specific NFT. Present when `metrics=true`; omitted when the caller leaves it at the default `false`. Collection-scope metrics live on `/nft/collections` and `/nft/collection`.
nfts[].metrics.total_sales
integer
Lifetime count of sale transfers for this NFT (transfers with non-null amount).
nfts[].metrics.total_volume_xrp
string
Sum of XRP-denominated sale amounts across the NFT's lifetime, as a decimal XRP string. Excludes IOU sales.
nfts[].metrics.last_sale_price_xrp
object
XRP-denominated price of the most recent sale, decimal string. `null` when the most recent sale was IOU-denominated or no sales have been recorded.
nfts[].metrics.last_sale_at
object
Unix-seconds timestamp of the most recent sale (any currency). `null` when no sales recorded.
nfts[].metrics.current_floor_offer_xrp
object
Lowest open XRP sell offer for **this specific NFT**, decimal XRP. `null` when no open XRP sell offer exists. Distinct from the collection-level floor returned by `/nft/collections`.
collections
object[]
Matched collection rows, ranked by `total_volume` DESC (most-traded first). Empty when `includeCollections=false` or no matches.
collections[].id
string
Internal UUID primary key for the collection.
collections[].issuer
string
XRPL address that minted the collection.
collections[].slug
string
Canonical collection slug — `<issuer>:<taxon>`. Use the per-collection sub-routes (`/nft/collection/...`) keyed by this slug to drill into traits, holders, traders, etc.
collections[].taxon
integer
NFToken taxon grouping identifier.
collections[].createdAt
integer
Record creation timestamp, Unix-seconds.
collections[].updatedAt
integer
Record update timestamp, Unix-seconds.
collections[].metadata
object
Curated / slow-changing metadata about the collection. Present when `metadata=true` (the default); omitted when the caller passes `metadata=false`.
collections[].metadata.name
object
Collection display name.
collections[].metadata.description
object
Collection description text.
collections[].metadata.image_url
object
Collection cover / banner image URL.
collections[].metrics
object
Live / rolling sales and floor metrics, plus lifetime totals. Present when `metrics=true`; omitted when the caller leaves it at the default `false`.
collections[].metrics.token_count
integer
Number of NFTs minted in this collection.
collections[].metrics.current_floor
object
Current lowest active sell offer across the collection, decimal XRP. NULL when no open sell offers exist. (Floor as a live state, not a window.)
collections[].metrics.total_volume
string
Cumulative lifetime trade volume, decimal XRP.
collections[].metrics.floor
object
Minimum observed sale price per window. `value` is the window minimum; `change_*` compares to the prior same-length window.
collections[].metrics.floor.last_24h
object
collections[].metrics.floor.last_7d
object
collections[].metrics.volume
object
Summed XRP-denominated sale volume per window.
collections[].metrics.volume.last_24h
object
collections[].metrics.volume.last_7d
object
collections[].metrics.sales
object
Count of sales per window.
collections[].metrics.sales.last_24h
object
collections[].metrics.sales.last_7d
object
nextCursor
object
Opaque cursor for the next page across both kinds. `null` when neither kind has more rows.
Example
Json
{
  "nfts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "token_id": "string",
      "issuer": "string",
      "owner": "string",
      "taxon": 0,
      "serial_number": 0,
      "uri": "string",
      "transfer_fee": 0,
      "flags": {
        "burnable": false,
        "only_xrp": false,
        "trust_line": false,
        "transferable": false,
        "mutable": false
      },
      "burned": false,
      "burned_at": 1745798400,
      "minted_at_ledger": 0,
      "mint_tx_hash": "string",
      "metadata": {
        "asset": {
          "name": "string",
          "description": "string",
          "meta_url": "string",
          "media_url": "string",
          "external_url": "string",
          "marketplace": "string"
        },
        "collection": {
          "issuer": "string",
          "taxon": 0,
          "name": "string",
          "description": "string",
          "image_url": "string"
        }
      },
      "metrics": {
        "total_sales": 0,
        "total_volume_xrp": "string",
        "last_sale_price_xrp": "string",
        "last_sale_at": 1745798400,
        "current_floor_offer_xrp": "string"
      }
    }
  ],
  "collections": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "issuer": "string",
      "slug": "string",
      "taxon": 0,
      "createdAt": 1745798400,
      "updatedAt": 1745798400,
      "metadata": {
        "name": "string",
        "description": "string",
        "image_url": "string"
      },
      "metrics": {
        "token_count": 0,
        "current_floor": "string",
        "total_volume": "string",
        "floor": {
          "last_24h": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_7d": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          }
        },
        "volume": {
          "last_24h": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          },
          "last_7d": {
            "value": "string",
            "change_absolute": "string",
            "change_percent": "string"
          }
        },
        "sales": {
          "last_24h": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "string"
          },
          "last_7d": {
            "value": 0,
            "change_absolute": 0,
            "change_percent": "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": []
}