BigBlocks

Buy Listing

Purchase an ordinal NFT from the global BSV orderbook with ORDFS thumbnail, price breakdown, and one-click buy

A card block for buying an ordinal NFT listing. Resolves a thumbnail from ORDFS, shows the price, optional seller info, marketplace fee breakdown, and a "Buy Now" action. Supply onPurchase to handle the on-chain transaction. The underlying useBuyListing hook is also exported for headless usage.

Installation

bunx shadcn@latest add https://registry.bigblocks.dev/r/buy-listing.json

Usage

import { BuyListing, type PurchaseOrdinalParams, type PurchaseOrdinalResult } from "@/components/blocks/buy-listing"
 
export default function MarketItemPage() {
  const handlePurchase = async (params: PurchaseOrdinalParams): Promise<PurchaseOrdinalResult> => {
    try {
      const result = await purchaseOrdinal.execute(ctx, params)
      return { txid: result.txid }
    } catch (err) {
      return { error: err instanceof Error ? err.message : "Purchase failed" }
    }
  }
 
  return (
    <BuyListing
      outpoint="abc123...def.0"
      price={50000}
      name="Rare Pepe #42"
      seller="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      contentType="image/png"
      origin="abc123...def.0"
      onPurchase={handlePurchase}
      onPurchased={(result) => console.log("Purchased:", result.txid)}
      marketplaceAddress="1MarketAddress..."
      marketplaceRate={0.02}
    />
  )
}

Size Variants

The card accepts a size variant prop.

<BuyListing outpoint={outpoint} price={50000} onPurchase={handlePurchase} size="default" />

API Reference

BuyListing

PropTypeDefaultDescription
outpointstringRequired. Listing outpoint in txid.vout format.
pricenumberRequired. Listing price in satoshis.
namestringDisplay name of the ordinal.
sellerstringSeller display name or address.
contentTypestringMIME type used to render the thumbnail.
originstringOrigin outpoint for ORDFS thumbnail resolution. Falls back to outpoint.
onPurchase(params: PurchaseOrdinalParams) => Promise<PurchaseOrdinalResult>Required. Executes the on-chain purchase.
onPurchased(result: PurchaseOrdinalResult) => voidCalled after a successful purchase.
onError(error: Error) => voidCalled when the purchase fails.
marketplaceAddressstringAddress that receives the marketplace fee. Required when marketplaceRate is set.
marketplaceRatenumberFee rate between 0 and 1 (e.g. 0.02 for 2%).
sizeVariantProps<typeof buyListingVariants>"default"Visual size of the card.
classNamestringAdditional CSS classes applied to the card.

PurchaseOrdinalParams

interface PurchaseOrdinalParams {
  outpoint: string             // Listing outpoint to purchase
  marketplaceAddress?: string  // Fee recipient address
  marketplaceRate?: number     // Fee rate 0–1
}

PurchaseOrdinalResult

interface PurchaseOrdinalResult {
  txid?: string   // Transaction ID on success
  rawtx?: string  // Raw transaction hex (optional)
  error?: string  // Error message when purchase failed
}

Hook

Use useBuyListing directly for custom card layouts or when embedding purchase logic into an existing component.

import { useBuyListing } from "@/components/blocks/buy-listing"
 
function CustomBuyCard({ outpoint, price, onPurchase }) {
  const buy = useBuyListing({ outpoint, price, onPurchase })
 
  return (
    <div>
      <p>Price: {price.toLocaleString()} sats</p>
      {buy.marketFee > 0 && <p>Fee: {buy.marketFee.toLocaleString()} sats</p>}
      <p>Total: {buy.totalCost.toLocaleString()} sats</p>
      {buy.error && <p className="text-destructive">{buy.error}</p>}
      <button
        onClick={buy.handlePurchase}
        disabled={buy.isPurchasing}
      >
        {buy.isPurchasing ? "Buying..." : "Buy Now"}
      </button>
    </div>
  )
}

UseBuyListingReturn

PropertyTypeDescription
isPurchasingbooleanWhether a purchase transaction is in progress.
resultPurchaseOrdinalResult | nullResult from the most recent purchase attempt.
errorstring | nullError message from the most recent attempt.
imgErrorbooleanWhether the ORDFS thumbnail failed to load.
setImgError(failed: boolean) => voidMark the thumbnail as failed (to show a fallback).
marketFeenumberCalculated marketplace fee in satoshis.
totalCostnumberTotal cost in satoshis (price + marketplace fee).
handlePurchase() => Promise<void>Execute the purchase.