Documentation
Docs
What BTCFi.ai does, how buying works today, and the public API.
What BTCFi.ai is
BTCFi.ai is an Ordinals marketplace aggregator. Rather than operating its own orderbook, it queries the marketplaces that already hold Ordinals liquidity, normalises what they return, and shows you a single price comparison per inscription — including the fees each venue charges, so the number you compare is total cost rather than headline price.
The scope is deliberately narrow: NFTs only. Inscriptions are supported; fungible token standards on Bitcoin are not, and adding them is a deliberate future decision rather than a backlog item.
How buying works
We aggregate and price; the venue settles. When you click through to buy, the purchase completes on the marketplace holding the listing, with your own wallet, under that marketplace’s terms. BTCFi.ai does not build, co-sign, or broadcast the transaction, and never takes custody of your bitcoin or your inscription.
Connecting a wallet is read-only. We use your public address to show what you own and to populate your watchlist — nothing is signed, and there is no account or signup.
We charge no fee. What you pay is the listing price, the Bitcoin network fee, and whatever the venue itself charges. See the Terms for the full breakdown.
Which marketplaces are aggregated
Each venue is a separate adapter that is enabled independently, so coverage changes as venues are brought online. Rather than list a snapshot that goes stale, the API reports the truth live: /health returns every adapter and its current status, and /health/adapters breaks out per-adapter latency and rate-limit budget.
An adapter that is configured but has no credentials runs dark — it is skipped entirely rather than reported as failing, so a venue we have not yet enabled never degrades your results.
Public API
The read API is open and needs no key. Base URL: https://api.btcfi.ai. Responses are JSON; satoshi amounts are returned as strings to survive JSON number precision. The full machine-readable spec lives at /openapi.json.
Health
| Endpoint | Returns | |
|---|---|---|
GET | /livez | Process liveness only |
GET | /readyz | Whether this node can serve traffic, with the reason |
GET | /health | Full verdict — database, cache, and every adapter |
GET | /health/adapters | Per-adapter latency and rate-limit budget |
Collections
| Endpoint | Returns | |
|---|---|---|
GET | /collections | Paginated collections with floor and volume |
GET | /collections/{slug} | One collection |
GET | /collections/{slug}/listings | Live listings across every enabled venue |
GET | /collections/{slug}/inscriptions | Known inventory, listed or not |
GET | /collections/{slug}/recent-sales | Recent settled sales |
GET | /collections/{slug}/trait-facets | Trait facets for filtering |
GET | /collections/trending | Ranked by volume change |
Inscriptions, market, and addresses
| Endpoint | Returns | |
|---|---|---|
GET | /inscriptions/{id} | One inscription |
GET | /inscriptions/{id}/listings | Every venue offering it, cheapest first |
GET | /inscriptions/{id}/history | Mint and transfer history |
GET | /activity | Cross-collection sales feed |
GET | /search | Collections and inscriptions |
GET | /addresses/{address}/inscriptions | What an address holds |
GET | /prices/btc-usd | BTC/USD reference price |
Requests are rate limited per IP. Settlement endpoints exist in the API surface but are disabled in production and return 403 checkout_disabled — buying goes through the venue, as described above.
Real-time updates
A WebSocket endpoint streams new listings, sales, and floor-price changes so a client does not have to poll. It is the same host as the REST API over wss://. Clients should treat it as an accelerator rather than a source of truth and fall back to REST when the socket is unavailable.
Data accuracy
Listings come from third-party marketplace APIs and are refreshed on a tiered schedule — the busiest collections most frequently. A listing shown here may already be sold, repriced, or withdrawn at the venue, so always confirm in the marketplace’s own interface before paying. Rarity and trait data is derived from indexed inscription metadata and is provided for reference, not as valuation advice.
Questions
General enquiries: hello@btcfi.ai. Security disclosures: security@btcfi.ai. BTCFi.ai is part of the Uniside ecosystem, built in Switzerland.