PUBLIC API
Open read endpoints over the same chain-traced data the site uses. No key required. Responses are JSON.
/api/public/blocks/{height}Bitmap identity for a block height: name, holder, club, parcel count and inscription reference.
/api/public/blocks/{height}/metaExtended block statistics: transaction count, byte size and derived shape pattern.
/api/public/offersOpen marketplace offers across all bitmaps, newest first.
/api/public/offerA single offer with its signed PSBT metadata, by offer identifier.
/api/public/coin-rewardsBIT reward schedule and current attention-based daily distribution state.
/api/public/crawl-tradesTrigger a registry-wide crawl that traces bitmap transfers and confirmed sales from the chain.
/api/public/resolve-registryResolve a bitmap height to its canonical first inscription and current holder address.
/api/public/gallery/{inscriptionId}Membership of an inscribed ordinals gallery, decoded from its reveal transaction. Immutable, so it is cached hard.
/api/public/market/orderbook?depth=20TRADING · Best ask/bid, spread, mid, last price, 24h volume and the ask/bid ladders.
/api/public/market/listings?sort=price_asc&min_sats=&max_sats=&height=&seller=&limit=&offset=TRADING · Open listings with seller-signed PSBTs and checkout-hold status.
/api/public/market/trades?height=&limit=TRADING · On-chain sales tape (confirmed and mempool).
/api/public/market/bids?height=&limit=TRADING · Open bids, highest first.
/api/public/market/listingsTRADING · List: body is a seller-signed base64 PSBT (raw or JSON psbt field). Validated against the live UTXO set.
/api/public/market/listings/cancelTRADING · offerId, issuedAt, signature: BIP-322 signature of the unlist message by the seller address.
/api/public/market/buy/prepareTRADING · offerId, buyerPaymentAddress, buyerOrdinalsAddress, optional keys: places a 90s hold and returns the buyer PSBT to sign locally.
/api/public/market/buy/broadcastTRADING · offerId, psbt, buyerAddress: finalizes your signed PSBT and broadcasts it, returning the txid.
/api/public/market/bidsTRADING · bitmapHeight, bidderAddress, priceSats, expiresInHours?, issuedAt, signature: BIP-322 signature of the bid message.
/api/public/market/bids/cancelTRADING · bidId, address, issuedAt, signature: BIP-322 signature of the cancel message.
EXAMPLE
curl https://bitmapwin.app/api/public/blocks/382441
Endpoints are rate-limited and read-only apart from the crawler trigger. If a fact cannot be traced on chain, the API omits it rather than estimating it.
TRADING BOTS
Bots trade with their own keys: the API builds PSBTs and checks Bitcoin signatures, but never holds or uses your keys.
# 1. Watch the book
curl https://bitmapwin.app/api/public/market/orderbook
# 2. Prepare a buy (90s hold), sign the returned PSBT with YOUR key locally
curl -X POST https://bitmapwin.app/api/public/market/buy/prepare \
-H 'content-type: application/json' \
-d '{"offerId":"<id>","buyerPaymentAddress":"bc1q...","buyerOrdinalsAddress":"bc1p..."}'
# 3. Broadcast your signed PSBT
curl -X POST https://bitmapwin.app/api/public/market/buy/broadcast \
-H 'content-type: application/json' \
-d '{"offerId":"<id>","psbt":"<signed base64>","buyerAddress":"bc1p..."}'
# Signed messages (BIP-322). issuedAt = ISO UTC time, valid 10 min, each signature works once:
# bid: "BITMAPWIN API BID
parcel: <h>.bitmap
amount: <sats> sats
bidder: <addr>
issued: <issuedAt>"
# cancel: "BITMAPWIN API CANCEL BID
bid: <bidId>
address: <addr>
issued: <issuedAt>"
# unlist: "BITMAPWIN API UNLIST
listing: <offerId>
address: <seller>
issued: <issuedAt>"
#
# Limits: 120 reads/min per IP · 20 writes/min per IP · 10 writes/min per wallet
# · 6 checkout holds/min · max 2 live holds per buyer. HTTP 429 = slow down.
# Broadcast is refused if the seller payout or inscription delivery output is altered.TYPESCRIPT CLIENT
A typed, dependency-free client for browsers, Node, Bun and Deno. It builds the exact messages to sign; your wallet signs them.
import { BitmapWinClient } from "./bitmapwin-client";
const bw = new BitmapWinClient(); // baseUrl defaults to https://bitmapwin.app
const book = await bw.market.orderbook(10);
const { listings } = await bw.market.listings({ max_sats: 100_000, sort: "price_asc", limit: 1 });
// Bid: build the exact message, sign it with YOUR wallet (BIP-322), then submit
const issuedAt = bw.issuedAt();
const msg = bw.messages.bid(840000, 50_000, "bc1p...", issuedAt);
const signature = await wallet.signMessage(msg, "bip322-simple");
await bw.market.placeBid({ bitmapHeight: 840000, bidderAddress: "bc1p...", priceSats: 50_000, issuedAt, signature });
// Errors carry the HTTP status (e.g. 429 = slow down)
// catch (e) { if (e instanceof BitmapWinApiError && e.status === 429) ... }BOT STARTER KIT
A ready-to-run repository: TypeScript and Python floor monitors, the typed client above, the exact BIP-322 messages the server verifies, and bid / cancel / unlist helpers. MIT licensed — start your own bot from it in one click. Nothing signs or broadcasts on its own.