Orderbook

Immutable’s decentralised trading protocol. Orders created on any marketplace are visible and fillable across the entire ecosystem.

Why Orderbook?

Shared Liquidity

Orders are visible across all Immutable marketplaces. Your players access the entire ecosystem’s liquidity, not just your marketplace.

Gasless Listings

Creating orders is free—sellers only sign a message. Gas is only paid when orders are filled.

Enforced Royalties

Royalties are enforced at the protocol level. Creators always get paid on secondary sales.

Instant Settlement

Trades settle on-chain immediately. No waiting, no counterparty risk.

Installation

TypeScript
Unity
Unreal

npm install @imtbl/orderbook @imtbl/config

Open Window → Package Manager
Click + → Add package from git URL
Enter: https://github.com/immutable/unity-immutable-sdk.git
Click Add

Unity Orderbook is in Alpha. API may change.

Download the plugin from GitHub releases
Copy ImmutableSDK folder to your project’s Plugins directory
Restart Unreal Editor
Enable the plugin in Edit → Plugins → Immutable SDK

Unreal Orderbook is in Alpha. API may change.

Setup

TypeScript
Unity
Unreal

import { Orderbook } from '@imtbl/orderbook';
import { Environment } from '@imtbl/config';

const orderbook = new Orderbook({
  baseConfig: {
    environment: Environment.SANDBOX,
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  },
});

using Immutable.Orderbook.Api;
using Immutable.Orderbook.Client;
using Immutable.Passport;

// Orderbook requires an authenticated Passport instance
var passport = await Passport.Init("YOUR_CLIENT_ID", Environment.Sandbox);
await passport.Login();

// Initialize the OrderbookApi
var orderbookApi = new OrderbookApi(new Configuration 
{ 
    BasePath = "https://api.sandbox.immutable.com" // or https://api.immutable.com for mainnet
});

Install the Orderbook package: In Package Manager, click + → Add package from git URL and enter https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Orderbook

#include "Immutable/ImmutablePassport.h"
#include "Immutable/ImmutableSubsystem.h"

// Orderbook requires an authenticated Passport instance
UImmutableSubsystem* Subsystem = GetGameInstance()->GetSubsystem<UImmutableSubsystem>();
UImmutablePassport* Passport = Subsystem->GetPassport();

// Initialize Passport first (see Authentication docs)
// Then connect to zkEVM for orderbook operations
Passport->ConnectEvm(
    FImtblPassportResponseDelegate::CreateLambda([](FImmutablePassportResult Result) {
        if (Result.Success) {
            UE_LOG(LogTemp, Log, TEXT("Ready for orderbook operations"));
        }
    }));

Unreal Orderbook support is limited. Check the Unreal SDK GitHub for current orderbook feature availability.

Creating Listings

Listings let users sell NFTs at a fixed price. Creating a listing is gasless—only the buyer pays gas when filling.

List an ERC-721 NFT

TypeScript
Unity
Unreal

import { Orderbook } from '@imtbl/orderbook';

// Get the user's wallet address
const address = await walletClient.getAddresses().then(a => a[0]);

// Prepare the listing
const { orderComponents, orderHash, typedData } = await orderbook.prepareListing({
  makerAddress: address,
  buy: {
    type: 'NATIVE',
    amount: '1000000000000000000', // 1 IMX in wei
  },
  sell: {
    type: 'ERC721',
    contractAddress: NFT_CONTRACT,
    tokenId: '123',
  },
});

// Sign the order (gasless)
const signature = await walletClient.signTypedData({
  account: address,
  ...typedData,
});

// Submit the listing
const { result } = await orderbook.createListing({
  orderComponents,
  orderHash,
  orderSignature: signature,
  makerFees: [],
});

console.log('Listing created:', result.id);

The Unity Orderbook SDK involves two packages working together:

Orderbook package (Immutable.Orderbook.Api.OrderbookApi) - Prepares listings and fulfills orders
zkEVM API package (Immutable.Api.ZkEvm.Api.OrdersApi) - Creates and queries orders

The general flow for creating a listing:

Call OrderbookApi.PrepareListingAsync() to get typed data
Execute any approval transactions via passport.ZkEvmSendTransaction()
Sign the order data with passport.ZkEvmSignTypedDataV4()
Call OrdersApi.CreateListingAsync() to submit

See the Unity sample marketplace for complete working examples.

Orderbook listing creation in Unreal follows the same flow as TypeScript:

Prepare the listing via API
Sign the typed data with ZkEvmSignTypedDataV4
Submit the listing

The Unreal SDK provides ZkEvmSignTypedDataV4 for signing typed data. Implementation details depend on your game’s architecture.

List an ERC-1155 NFT

For semi-fungible tokens, specify the quantity:

TypeScript
Unity
Unreal

const { orderComponents, orderHash, typedData } = await orderbook.prepareListing({
  makerAddress: address,
  buy: {
    type: 'NATIVE',
    amount: '500000000000000000', // 0.5 IMX per item
  },
  sell: {
    type: 'ERC1155',
    contractAddress: NFT_CONTRACT,
    tokenId: '456',
    amount: '10', // Selling 10 copies
  },
});

ERC-1155 listings follow the same pattern as ERC-721. Use ERC1155Item instead of ERC721Item and specify the amount parameter.

ERC-1155 listings follow the same pattern as ERC-721 listings—specify the amount field in the sell item.

Filling Listings (Buying)

When a buyer fills a listing, the trade executes on-chain.

TypeScript
Unity
Unreal

import { Orderbook } from '@imtbl/orderbook';

// Prepare the fill
const { actions } = await orderbook.fulfillOrder(
  listingId,
  address, // buyer address
  []       // taker fees (optional)
);

// Execute all required actions (approvals + fill)
for (const action of actions) {
  if (action.type === 'TRANSACTION') {
    const hash = await walletClient.sendTransaction({
      to: action.to,
      data: action.data,
      value: BigInt(action.value || '0'),
    });
    await publicClient.waitForTransactionReceipt({ hash });
  }
}

console.log('Purchase complete!');

To fill (buy) a listing:

Call OrderbookApi.FulfillOrderAsync() with the listing ID
Execute the returned transactions via passport.ZkEvmSendTransactionWithConfirmation()

See the Unity sample marketplace for complete implementation.

To fill orders, execute the transaction returned by the fulfill API:

// After getting transaction data from the fulfill API
FImtblTransactionRequest Request;
Request.To = TransactionTo;
Request.Data = TransactionData;
Request.Value = TransactionValue;

Passport->ZkEvmSendTransactionWithConfirmation(Request,
    FImtblPassportResponseDelegate::CreateLambda([](FImmutablePassportResult Result) {
        if (Result.Success) {
            UE_LOG(LogTemp, Log, TEXT("Purchase complete!"));
        }
    }));

Creating Bids

Bids let users make offers on specific NFTs.

TypeScript
Unity
Unreal

import { Orderbook } from '@imtbl/orderbook';

// Prepare the bid
const { orderComponents, orderHash, typedData } = await orderbook.prepareBid({
  makerAddress: address,
  buy: {
    type: 'ERC721',
    contractAddress: NFT_CONTRACT,
    tokenId: '123',
  },
  sell: {
    type: 'NATIVE',
    amount: '500000000000000000', // Offering 0.5 IMX
  },
});

// Sign and submit (same pattern as listings)
const signature = await walletClient.signTypedData({
  account: address,
  ...typedData,
});

const { result } = await orderbook.createBid({
  orderComponents,
  orderHash,
  orderSignature: signature,
  makerFees: [],
});

console.log('Bid created:', result.id);

Creating bids uses OrdersApi.CreateBidAsync(). The flow is similar to listings:

Prepare the bid data
Sign with passport.ZkEvmSignTypedDataV4()
Submit via the API

See the Unity SDK sample for implementation details.

Bidding follows the same pattern as creating listings: prepare via API, sign with ZkEvmSignTypedDataV4, then submit.

Order Expiration

Set when orders should expire:

TypeScript
Unity
Unreal

const prepared = await orderbook.prepareListing({
  makerAddress: address,
  buy: { type: 'NATIVE', amount: '1000000000000000000' },
  sell: { type: 'ERC721', contractAddress: NFT_CONTRACT, tokenId: '123' },
  // Expire in 7 days
  expiration: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
});

Pass the orderExpiry parameter when preparing a listing. The PrepareListingRequest accepts a DateTime value for expiration.

Expiration	Use Case
1 hour	Flash sales
24 hours	Daily auctions
7 days	Standard listings
30 days	Long-term listings

Next Steps

Order Management

Query orders, check status, and cancel

Collection Bids

Bid on any NFT in a collection

Fees

Protocol fees, royalties, and marketplace fees

Build a Marketplace

Complete marketplace tutorial

PRODUCTS

GUIDES

Why Orderbook?

Installation

Setup

Creating Listings

List an ERC-721 NFT

List an ERC-1155 NFT

Filling Listings (Buying)

Creating Bids

Order Expiration

Next Steps

Order Management

Collection Bids

Fees

Build a Marketplace

PRODUCTS

GUIDES

​Why Orderbook?

​Installation

​Setup

​Creating Listings

​List an ERC-721 NFT

​List an ERC-1155 NFT

​Filling Listings (Buying)

​Creating Bids

​Order Expiration

​Next Steps

Order Management

Collection Bids

Fees

Build a Marketplace

Why Orderbook?

Installation

Setup

Creating Listings

List an ERC-721 NFT

List an ERC-1155 NFT

Filling Listings (Buying)

Creating Bids

Order Expiration

Next Steps