Response shapes are pre-release and may change.
Hive Engine NFT Directory

Endpoint reference

Draft API — response fields may change before v0.1.0 (see the changelog). Every endpoint is GET, unauthenticated, and returns JSON. See the data model for what display means below.

GET /accounts/{account}/nfts

Wallet display — owned, delegated-in, and listed NFTs

Owned + delegated-in NFTs, plus NFTs the account has listed on the market (held in escrow by the `nftmarket` contract, so they would otherwise disappear from a naive owner query). All three groups are keyed by symbol. If this account has never been queried before, it is populated synchronously from Hive Engine first — expect a few seconds' latency on that first call only; every later call is served from the cache.

Name In Type Required Description
account path string true Hive account name.
symbol query string false Restrict results to one NFT symbol.

Errors

  • 400 Bad Request — a path or query parameter failed to parse.
  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/accounts/alice/nfts?symbol=MYNFT 
GET /he-nft/accounts/alice/nfts?symbol=MYNFT
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "account": "alice",
  "owned": {
    "MYNFT": [
      {
        "nft_id": 1,
        "account": "alice",
        "owned_by": "u",
        "delegated_to": null,
        "properties": {
          "Name": "Cool NFT #1",
          "thumb": "https://images.example/mynft/1.png",
          "rarity": "rare"
        },
        "display": {
          "name": "Cool NFT #1",
          "image": "https://images.example/mynft/1.png",
          "collection": "My Collection",
          "attributes": {
            "rarity": "rare",
            "speed": 87
          }
        }
      }
    ]
  },
  "delegated_in": {
    "MYNFT": [
      {
        "nft_id": 1,
        "account": "alice",
        "owned_by": "u",
        "delegated_to": null,
        "properties": {
          "Name": "Cool NFT #1",
          "thumb": "https://images.example/mynft/1.png",
          "rarity": "rare"
        },
        "display": {
          "name": "Cool NFT #1",
          "image": "https://images.example/mynft/1.png",
          "collection": "My Collection",
          "attributes": {
            "rarity": "rare",
            "speed": 87
          }
        }
      }
    ]
  },
  "listed": {
    "MYNFT": [
      {
        "nft_id": 1,
        "account": "alice",
        "owned_by": "u",
        "delegated_to": null,
        "properties": {
          "Name": "Cool NFT #1",
          "thumb": "https://images.example/mynft/1.png",
          "rarity": "rare"
        },
        "display": {
          "name": "Cool NFT #1",
          "image": "https://images.example/mynft/1.png",
          "collection": "My Collection",
          "attributes": {
            "rarity": "rare",
            "speed": 87
          }
        },
        "price": "12.500",
        "price_symbol": "SWAP.HIVE"
      }
    ]
  }
}
GET /accounts/{account}/activity

Recent activity — rolling window of NFT events

NFT events (issue, transfer, burn, delegation, market list/cancel/ price-change/buy) where the account was the actor or counterparty, newest first. This is a rolling recent-activity feed, NOT a transaction-history archive: events older than the retention window (`coverage.window_days`) are pruned, and coverage may still be filling backward shortly after a deployment (`coverage.backfill_ complete`). Serves whatever is captured immediately — never blocks on backfill, and never triggers a holdings fetch.

Name In Type Required Description
account path string true Hive account name.
symbol query string false Restrict results to one NFT symbol.
op query string false Restrict to one event type (e.g. `transfer`, `market_buy`).
cursor query integer false Pagination cursor — the previous page's `next_cursor`. Omit for the first page.
limit query integer false Page size, capped server-side at 1000.

Errors

  • 400 Bad Request — a path or query parameter failed to parse.
  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/accounts/alice/activity?symbol=MYNFT&op=op 
GET /he-nft/accounts/alice/activity?symbol=MYNFT&op=op
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "account": "alice",
  "events": [
    {
      "he_block": 1,
      "symbol": "MYNFT",
      "nft_id": 1,
      "op": "issue",
      "account": "alice",
      "counterparty": "counterparty",
      "price": "12.500",
      "price_symbol": "SWAP.HIVE",
      "tx_id": "tx_id",
      "ts": "2026-07-01T12:00:00Z"
    }
  ],
  "coverage": {
    "window_days": 1,
    "oldest_event_ts": "oldest_event_ts",
    "backfill_complete": true,
    "backfill_cursor_block": 1,
    "backfill_target_block": 1
  },
  "next_cursor": null
}
GET /collections

Directory browse — all known NFT symbols

A full mirror of Hive Engine's own NFT catalog, refreshed periodically in full (unlike instances, which are cached per account) — every symbol that exists on HE appears here regardless of whether any of its instances have been queried yet.

Name In Type Required Description
cursor_symbol query string false Pagination cursor: the last `symbol` seen on the previous page. Symbols sort lexicographically, not by creation order.
limit query integer false Page size, capped server-side at 1000.

Errors

  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/collections?cursor_symbol=&limit=100 
GET /he-nft/collections?cursor_symbol=&limit=100
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "collections": [
    {
      "symbol": "MYNFT",
      "name": "Cool NFT #1",
      "org_name": "Example Org",
      "product_name": "My NFT Collection",
      "issuer": "issuer-account",
      "url": "https://example.org/mynft",
      "metadata": {
        "external_url": "https://example.org/mynft"
      },
      "group_by": [
        "rarity"
      ],
      "properties": {
        "Name": "Cool NFT #1",
        "thumb": "https://images.example/mynft/1.png",
        "rarity": "rare"
      },
      "delegation_enabled": false,
      "market_enabled": true,
      "supply": 10000,
      "circulating_supply": 9988,
      "burned": 12,
      "max_supply": 10000,
      "undelegation_cooldown_days": 1,
      "refreshed_at": "2026-07-05T00:04:02Z",
      "has_display_mapping": true
    }
  ],
  "next_cursor_symbol": null
}
GET /collections/{symbol}

Collection detail

Name In Type Required Description
symbol path string true Hive Engine NFT symbol.

Errors

  • 404 Not Found — no resource matched the given path.
  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/collections/MYNFT 
GET /he-nft/collections/MYNFT
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "symbol": "MYNFT",
  "name": "Cool NFT #1",
  "org_name": "Example Org",
  "product_name": "My NFT Collection",
  "issuer": "issuer-account",
  "url": "https://example.org/mynft",
  "metadata": {
    "external_url": "https://example.org/mynft"
  },
  "group_by": [
    "rarity"
  ],
  "properties": {
    "Name": "Cool NFT #1",
    "thumb": "https://images.example/mynft/1.png",
    "rarity": "rare"
  },
  "delegation_enabled": false,
  "market_enabled": true,
  "supply": 10000,
  "circulating_supply": 9988,
  "burned": 12,
  "max_supply": 10000,
  "undelegation_cooldown_days": 1,
  "refreshed_at": "2026-07-05T00:04:02Z",
  "has_display_mapping": true
}
GET /nfts/{symbol}/{id}

Single NFT detail

Current instance state plus its normalized display object (if the symbol has a display mapping) and any open market listing. If this instance isn't already cached (its current holder has never been queried), a single live point lookup resolves its current owner and populates that account before responding.

Name In Type Required Description
symbol path string true Hive Engine NFT symbol.
id path integer true NFT instance id, unique within its symbol.

Errors

  • 404 Not Found — no resource matched the given path.
  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/nfts/MYNFT/1 
GET /he-nft/nfts/MYNFT/1
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "symbol": "MYNFT",
  "nft_id": 1,
  "account": "alice",
  "owned_by": "u",
  "delegated_to": null,
  "delegated_to_type": null,
  "soul_bound": true,
  "properties": {
    "Name": "Cool NFT #1",
    "thumb": "https://images.example/mynft/1.png",
    "rarity": "rare"
  },
  "refreshed_at": "2026-07-05T00:04:02Z",
  "collection_name": "My Collection",
  "display": {
    "name": "Cool NFT #1",
    "image": "https://images.example/mynft/1.png",
    "collection": "My Collection",
    "attributes": {
      "rarity": "rare",
      "speed": 87
    }
  },
  "open_order": {
    "price": "12.500",
    "price_symbol": "SWAP.HIVE",
    "account": "alice",
    "ts": "2026-07-01T12:00:00Z"
  }
}
GET /market/{symbol}

Open orders and price rollups for a symbol

Name In Type Required Description
symbol path string true Hive Engine NFT symbol.
account query string false Filter open orders to one seller account.
cursor query integer false Pagination cursor — the previous page's `next_cursor`. Omit for the first page.
limit query integer false Page size, capped server-side at 1000.

Errors

  • 400 Bad Request — a path or query parameter failed to parse.
  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/market/MYNFT?account=alice&cursor=0 
GET /he-nft/market/MYNFT?account=alice&cursor=0
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "symbol": "MYNFT",
  "rollups": [
    {
      "price_symbol": "SWAP.HIVE",
      "grouping": {
        "MYNFT": "MYNFT"
      },
      "floor_price": "9.900",
      "open_orders": 3
    }
  ],
  "open_orders": [
    {
      "nft_id": 1,
      "account": "alice",
      "owned_by": "u",
      "price": "12.500",
      "price_symbol": "SWAP.HIVE",
      "fee": 500,
      "ts": "2026-07-01T12:00:00Z"
    }
  ],
  "last_sales": [
    {
      "price_symbol": "SWAP.HIVE",
      "last_price": "last_price",
      "last_ts": "last_ts",
      "sales_30d": 1,
      "volume_30d": "volume_30d"
    }
  ],
  "next_cursor": null
}
GET /status

Trust surface — cache freshness and mapping coverage

Per-loop last-seen HE block (block_watcher; also written by the catalog/market sweeps), how many accounts are cached, how deep the refresh queue currently is, display-mapping coverage, and the activity feed's window/backfill coverage. There is no reconciliation metric in this design — the cache doesn't derive state, it mirrors HE directly on every refresh, so "correct" just means "not yet due for a refresh."

Errors

  • 500 Internal Server Error — unhandled failure, no stack trace.
GET /he-nft/status 
GET /he-nft/status
Host: hive-apis.freebeings.io
Accept: application/json
Example response
Draft shape 
{
  "sync": {
    "block_watcher": {
      "name": "block_watcher",
      "last_he_block": 92114006,
      "updated_at": "2026-07-05T00:04:02Z"
    }
  },
  "known_accounts": 1204,
  "refresh_queue_depth": 3,
  "refresh_retries": {
    "pending": 2,
    "max_attempts": 3,
    "next_retry_at": "2026-07-05T00:05:12Z"
  },
  "display_mapping_coverage": {
    "mapped": 189,
    "total": 214
  },
  "activity": {
    "window_days": 1,
    "oldest_event_ts": "oldest_event_ts",
    "backfill_complete": true,
    "backfill_cursor_block": 1,
    "backfill_target_block": 1
  },
  "disclosure": "This service is a read-through cache over Hive Engine’s own current state, populated only for accounts that have been queried at least once. It is not a historical ledger -- there is no transaction-history endpoint, and holdings reflect the last refresh, not necessarily this exact instant."
}