Fulfill Listing
This guide is primarily for developers and potentially project managers who want to understand the Orderbook integration process.
Fulfill Listing with Next.js
This tutorial demonstrates how to implement NFT listing fulfillment using the Immutable Orderbook SDK with Next.js. The application showcases how to fulfill both ERC721 and ERC1155 listings, providing a complete workflow from listing discovery to transaction execution.
Features Overview
- Fulfill ERC721 listings using the Orderbook SDK
- Fulfill ERC1155 listings with specific unit amounts using the Orderbook SDK
- Filter active listings by contract address and currency type
- Apply taker ecosystem fees during fulfillment
SDK Integration Details
Fulfill ERC721 Listing
Feature Name: Fulfill an active ERC721 listing on the Immutable orderbook.
Source Code: source code file
Implementation:
const fulfillERC721Listing = async (listingID: string) => {
const { actions } = await orderbookSDK.fulfillOrder(
listingID,
accountsState[0],
takerEcosystemFeeRecipient != "" ? [{
recipientAddress: takerEcosystemFeeRecipient, // Replace address with your own marketplace address
amount: takerEcosystemFeeAmount, // Insert taker ecosystem/marketplace fee here
}] : [],
);
for (const action of actions) {
if (action.type === orderbook.ActionType.TRANSACTION) {
const builtTx = await action.buildTransaction();
await signer?.sendTransaction(builtTx);
}
}
};
Explanation: The code first calls the fulfillOrder method from the Orderbook SDK, passing the listing ID, the buyer's wallet address, and optional taker ecosystem fees. The method returns a set of actions that need to be executed to complete the fulfillment. The code then iterates through these actions, builds transactions for actions of type TRANSACTION, and sends them using the connected wallet's signer. This process handles all the necessary on-chain interactions to complete the purchase of the NFT.
Fulfill ERC1155 Listing
Feature Name: Fulfill an active ERC1155 listing with specific unit amounts on the Immutable orderbook.
Source Code: source code file
Implementation:
const fulfillERC1155Listing = async (
listingID: string,
unitsToFill?: string, // Number of units to fill
) => {
const { actions } = await orderbookSDK.fulfillOrder(
listingID,
accountsState[0],
takerEcosystemFeeRecipient != "" ? [{
recipientAddress: takerEcosystemFeeRecipient, // Replace address with your own marketplace address
amount: takerEcosystemFeeAmount, // Insert taker ecosystem/marketplace fee here
}] : [],
unitsToFill,
);
for (const action of actions) {
if (action.type === orderbook.ActionType.TRANSACTION && signer) {
const builtTx = await action.buildTransaction();
await (await signer.sendTransaction(builtTx)).wait(1);
}
}
};
Explanation: Similar to the ERC721 fulfillment, this function calls the fulfillOrder method but includes an additional parameter for the number of units to fulfill. This is particularly important for ERC1155 tokens where a single listing might offer multiple units of the same NFT. The function processes the returned actions in the same way, building and sending transactions to complete the purchase. The implementation also waits for one confirmation of the transaction to ensure it's properly included in the blockchain.
Running the App
Prerequisites
Setup Instructions
- Clone the repository:
git clone https://github.com/immutable/ts-immutable-sdk.git
cd ts-immutable-sdk/examples/orderbook/fulfill-listing-with-nextjs
- Install dependencies:
pnpm i
- Set up environment variables:
cp .env.example .env
- Edit the
.envfile to add your Immutable Hub credentials:
NEXT_PUBLIC_PUBLISHABLE_KEY=your_publishable_key
NEXT_PUBLIC_CLIENT_ID=your_client_id
- Start the development server:
pnpm dev
- Open http://localhost:3000 in your browser.
Using the Application
- From the home page, select either "Fulfill listing - Complete fulfillment with ERC721" or "Fulfill listing - Complete fulfillment with ERC1155"
- Connect your Passport wallet by clicking the "Login" button
- Filter the available listings using:
- NFT Contract Address: Optional filter for specific NFT collections
- Currency Type: Choose between NATIVE or ERC20 currencies
- For ERC1155 listings, specify the number of units you want to purchase
- Click "Submit" on a listing to fulfill it
- Approve any required wallet interactions to complete the transaction
Summary
This example demonstrates how to implement NFT marketplace functionality for fulfilling both ERC721 and ERC1155 listings using the Immutable Orderbook SDK. The application showcases filtering active listings, user wallet integration via Passport, and executing fulfillment transactions with optional ecosystem fees. By following this example, developers can implement a complete purchasing flow for NFT marketplaces on Immutable.