Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sequence.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Import

import { useBuyModal } from "@0xsequence/marketplace-sdk/react";

​
Usage

Make sure you have followed the Getting Started guide to get the collection address and chainId.

​
Examples

Example of implementing a market purchase (secondary sales) using the useBuyModal hook:
This example uses the useLowestListing hook from marketplace-sdk. If there is no lowestListing with the given parameters, it means there is no orderId available, and therefore the item cannot be bought.
1

Setup handler component with marketplace config validation

First, create a main component that handles marketplace configuration loading and validation:
import {
  useBuyModal,
  useLowestListing,
  useMarketplaceConfig,
} from '@0xsequence/marketplace-sdk/react';
import type { Address } from 'viem';

function MarketPurchaseExample() {
  const { data: marketplaceConfig, isLoading: isMarketplaceConfigLoading } =
    useMarketplaceConfig();

  // Handle loading states
  if (isMarketplaceConfigLoading) {
    return <div style={{ padding: '20px' }}>Loading marketplace config...</div>;
  }

  if (!marketplaceConfig) {
    return (
      <div style={{ padding: '20px' }}>No marketplace config available</div>
    );
  }

  const collection = marketplaceConfig.market.collections[0];

  if (!collection) {
    return <div style={{ padding: '20px' }}>No collections available</div>;
  }

  const chainId = collection.chainId;
  const collectionAddress = collection.itemsAddress as Address;

  return (
    <MarketPurchase
      chainId={chainId}
      collectionAddress={collectionAddress}
      collectibleId="0"
    />
  );
}
2

Create market purchase component

Next, create the actual market purchase component that uses properly validated data:
interface MarketPurchaseProps {
  chainId: number;
  collectionAddress: Address;
  collectibleId: string;
}

function MarketPurchase({
  chainId,
  collectionAddress,
  collectibleId,
}: MarketPurchaseProps) {
  const {
    data: lowestListing,
    isLoading: isLoadingLowestListing,
    isError: isErrorLowestListing,
  } = useLowestListing({
    collectionAddress,
    chainId,
    tokenId: collectibleId,
  });

  const { show: showMarketModal } = useBuyModal({
    onSuccess: ({ hash, orderId }) => {
      console.log('Market purchase successful', { hash, orderId });
    },
    onError: (error) => {
      console.error('Market purchase failed:', error.message);
    },
  });

  const handleMarketBuy = () => {
    if (!lowestListing || isLoadingLowestListing) return;

    showMarketModal({
      chainId,
      collectionAddress,
      collectibleId,
      orderId: lowestListing.orderId,
      marketplace: lowestListing.marketplace,
    });
  };

  if (isLoadingLowestListing) {
    return <div style={{ padding: '20px' }}>Loading listing...</div>;
  }

  if (isErrorLowestListing || !lowestListing) {
    return (
      <div style={{ padding: '20px' }}>
        Error loading listing or no listing found
      </div>
    );
  }

  return (
    <div style={{ padding: '20px' }}>
      <h3>Market Purchase</h3>

      <p>Price: ${lowestListing.priceUSDFormatted}</p>

      <button
        type="button"
        onClick={handleMarketBuy}
        disabled={isLoadingLowestListing || isErrorLowestListing}
      >
        Buy from Market
      </button>
    </div>
  );
}

​
Parameters

The hook accepts an optional callbacks object with the following properties: 
interface ModalCallbacks {
  onSuccess?: ({ hash, orderId }: { hash?: Hash; orderId?: string }) => void;
  onError?: (error: Error) => void;
  successActionButtons?: Array<{ label: string; action: () => void }>;
}
ParameterTypeDescription
callbacks.onSuccess({ hash, orderId }: { hash?: Hash; orderId?: string }) => voidOptional callback function called when the purchase is successful
callbacks.onError(error: Error) => voidOptional callback function called when an error occurs during the purchase
callbacks.successActionButtonsArray<{ label: string; action: () => void }>Optional array of action buttons to show on success

​
Return Type

The hook returns an object with the following methods: 
{
  show: (args: BuyModalProps) => void
  close: () => void
}

​
Methods

​
show

(args: BuyModalProps) => void Opens the buy modal with the specified parameters. The BuyModalProps can be either ShopBuyModalProps or MarketplaceBuyModalProps depending on the purchase type. For market purchases (Secondary sales): 
interface MarketplaceBuyModalProps extends BuyModalBaseProps {
  marketplaceType?: "market";
  collectibleId: string;
  marketplace: MarketplaceKind;
  orderId: string;
}
For shop purchases (Primary sales): 
interface ShopBuyModalProps extends BuyModalBaseProps {
  marketplaceType: "shop";
  salesContractAddress: Address;
  items: Array<Partial<CheckoutOptionsItem> & { tokenId?: string }>;
  quantityDecimals: number;
  quantityRemaining: number;
  salePrice: {
    amount: string;
    currencyAddress: Address;
  };
  unlimitedSupply?: boolean;
}
Both types extend from BuyModalBaseProps: 
interface BuyModalBaseProps {
  chainId: number;
  collectionAddress: Address;
  skipNativeBalanceCheck?: boolean;
  nativeTokenAddress?: Address;
  marketplaceType?: MarketplaceType;
  customCreditCardProviderCallback?: (buyStep: Step) => void;
  successActionButtons?: Array<{ label: string; action: () => void }>;
}

​
close

() => void Closes the buy modal.

​
Notes

The useBuyModal hook provides a convenient way to manage the buy modal interface for collectible purchases. It handles:
  • Opening and closing the modal
  • Managing the purchase flow state
  • Error handling and success callbacks
  • Support for both primary and secondary sales