Skip to main content

Create, cancel and fill listings

Learn how to utilize the orderbook SDK to create, cancel and fill listings.

Immutable's Orderbook APIs and SDKs make it simple to create and settle orders.

💡One settlement contract
On Immutable zkEVM, there is currently only one settlement contract for NFT trades. Only orders with royalties that adhere to ERC2981 standard will be approved by the Immutable operator and accepted by the settlement contract. More information on this is available in Introduction.



Node version

The Immutable SDK requires Node v18 (Active LTS version) or higher. Node v18 can be installed via nvm which allows to quickly install and use different versions of node via the command line.

The installation steps for nvm for Linux, Mac, and Windows Install & Update Script. You are now ready to install the Node LTS version:

nvm install --lts

Install the Immutable SDK

Run the following command in your project root directory.

npm install -D @imtbl/sdk

The Immutable SDK is still in early development. Should complications arise during the installation, please use the following commands to ensure the most recent release of the SDK is correctly installed:

rm -Rf node_modules
npm cache clean --force
npm i


npm install -D typescript ts-node

In order to get started, we'll first need to set up an Orderbook client:

import { config, orderbook } from '@imtbl/sdk';
import { ethers } from 'ethers'; // ethers v5

const client = new orderbook.Orderbook({
baseConfig: new config.ImmutableConfiguration({
environment: config.Environment.SANDBOX,

Create listing

The Orderbook is responsible for managing the status of NFT orders. It does this by monitoring on-chain events and updating order statuses.

See the table below for a list of the order statuses:

StatusDescriptionTerminal (status cannot be reversed)
PENDINGThis status is attached when an order has just been created and has not yet been validated. Additionally, another reason is that the listing time has not yet begun.No
ACTIVEThe order has passed all validation requirements and can be filled (purchased) by a user.No
INACTIVEThe order does not have the required approval or the owner's balance was not sufficient to successfully list the order. Note that INACTIVE orders can become ACTIVE if conditions are metNo
CANCELLEDThe order has been cancelled and can no longer by filled.Yes
FILLEDThe order has been filled (purchased)Yes
EXPIREDThe order has expired and can no longer be filled.Yes

To create a listing, you can use the createListing function provided by the Orderbook client. It's important to note that listing creation does not incur any gas fees but approval does require small amount of gas. The order will need to go through various validations before it becomes fulfillable and transitions to the ACTIVE state.

By adhering to royalty requirements and following the necessary validations, your listings will be ready for trading on the marketplace. Below is an example of how to create a listing:

import { orderbook } from '@imtbl/sdk';
import { Wallet, providers } from 'ethers'; // ethers v5

const createListing = async (
client: orderbook.Orderbook,
preparedListing: orderbook.PrepareListingResponse,
orderSignature: string
): Promise<void> => {
const order = await client.createListing({
orderComponents: preparedListing.orderComponents,
orderHash: preparedListing.orderHash,
// Optional maker marketplace fee
makerFees: [{
amount: '100',
recipient: '0xFooBar', // Replace address with your own marketplace address

Fill listing

The fullfilment function in the orderbook SDK returns two unsigned transactions. One for the approval and the other for the fulfillment of the listing. These need to be signed and submitted by the user's signer.

Approval transaction only need to be submitted for ERC20 tokens and where the current approved amount is not sufficient. Note also that filling an order will incur a gas fee.

import { orderbook } from '@imtbl/sdk';
import { Signer, providers } from 'ethers'; // ethers v5

const fulfillListing = async (
client: orderbook.Orderbook,
signer: Signer,
provider: providers.Provider,
listingId: string
): Promise<void> => {
const fulfiller = await signer.getAddress();

const { actions, expiration, order } = await client.fulfillOrder(
amount: '1000000',
recipient: '0xFooBar', // Replace address with your own marketplace address

console.log(`Fulfilling listing ${order}, transaction expiry ${expiration}`);

for (const action of actions) {
if (action.type === orderbook.ActionType.TRANSACTION) {
const builtTx = await action.buildTransaction();
console.log(`Submitting ${action.purpose} transaction`);
const signedTx = await signer.signTransaction(builtTx);
await provider.sendTransaction(signedTx);

After this transaction has been confirmed, the status of this order will change to FILLED. You can poll Get orders to monitor this transition.


Stay tuned for bulk orders fulfillment capability within the orderbook SDK.

Cancel listing

Cancellation will transition any order state into CANCELLED. This will render the order unfulfillable for the remainder of its time. Note also that order cancellations will incur a gas fee.

import { orderbook } from '@imtbl/sdk';
import { Signer } from 'ethers'; // ethers v5
import { TransactionResponse } from "@ethersproject/providers"; // ethers v5

const cancelListing = async (
client: orderbook.Orderbook,
signer: Signer,
listingId: string
): Promise<TransactionResponse> => {
const offerer = await signer.getAddress();
const { unsignedCancelOrderTransaction } = await client.cancelOrder(

const receipt = await signer.sendTransaction(unsignedCancelOrderTransaction);
return receipt;

After this transaction has been confirmed, the status of this order will change to CANCELLED. You can poll Get orders to monitor this transition.

Marketplace fees

One of the most attractive incentives that is unique to Immutable is Marketplace fees. Through our zkEVM Orderbook, any marketplace can attach fees to any order they create. When these orders are filled on any marketplace on the protocol, the originating marketplace will receive fees.

There will be two types of marketplace fees supported, they are maker and taker marketplace fees. These two fees incentivise marketplaces to share liquidity with each other.

Please also visit our Fees section for more information on Orderbook fees.