Create, cancel and fill listings

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

Setup​

Prerequisites​

nvm install --lts

Install the Immutable SDK​

Run the following command in your project root directory.

npm install -D @imtbl/sdk

yarn add --dev @imtbl/sdk

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

rm -Rf node_modules
yarn cache clean
yarn

Dependencies​

npm install -D typescript ts-node

yarn add --dev 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:

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,
    orderSignature,
    // 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(
    listingId,
    fulfiller,
    [{
      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.

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(
    listingId,
    offerer
  );

  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.