Create orders - listings

This page explains how to create a listing using the Immutable Unreal Orderbook module, enabling you to list an NFT for sale on the Orderbook.

There are several steps required, so make sure you follow the instructions carefully to ensure a successful listing.

💡Who is this for?

Developers who want to build an in-game marketplace in Unreal.

💡Alpha version

This module is experimental and may change in the future. We recommend using it for testing purposes only.

Overview

Creating an order is the first step in trading an NFT on the Immutable Orderbook. This process involves setting the price, contract address, and token ID for the NFT the player wishes to sell, as well as the seller's wallet address. Once orders are successfully created, they can then be filled by other players, allowing them to purchase the NFTs which has been listed. Or they can ben cancelled by the owner if they wish to remove the listing.

To list an NFT at a fixed price, you need to do the following:

1. Prepare the listing.
2. Sign and submit the approval transaction (if required).
3. Sign the typed order data.
4. Submit the listing.

Below are partial code snippets that demonstrate the essential parts of each of these steps. If you want to see the full implementation, you can take a look at SearchNFTsWidget.cpp in our Unreal sample game and the Build a marketplace in Unreal tutorial.

💡Core functionality

There are other mechanisms for selling NFTs available in the Typescript Orderbook, such as creating bulk listings. In this initial release, the Unreal SDK is limited to creating a single listing using the CreateListing method described in this page.

Create listings workflow

1. Prepare the listing

This step sets up the necessary data for a listing request, including the buy and sell details, and then sends the request using PrepareListing method of Immutable Orderbook API.

ImmutableTsSdkApi::OpenAPIPrepareListingRequest RequestData;
ImmutableTsSdkApi::OpenAPIOrderbookApi::PrepareListingRequest Request;
ImmutableTsSdkApi::OpenAPIPrepareListingRequestBuy BuyData;
ImmutableTsSdkApi::OpenAPIPrepareListingRequestSell SellData;

BuyData.Amount = FMathUtility::ConvertFloatValueStringToWeiString(18, Dialog->GetPrice());
BuyData.ContractAddress = Policy->GetBalanceContractAddress();
BuyData.Type = ImmutableTsSdkApi::OpenAPIPrepareListingRequestBuy::TypeEnum::ERC20;

SellData.ContractAddress = SelectedItemWidget->GetContractAddress();
SellData.Type = ImmutableTsSdkApi::OpenAPIPrepareListingRequestSell::TypeEnum::ERC721;
SellData.TokenId = SelectedItemWidget->GetTokenId();

RequestData.MakerAddress = LocalPlayer->GetPassportWalletAddress();
RequestData.Buy = BuyData;
RequestData.Sell = SellData;

Request.OpenAPIPrepareListingRequest = RequestData;

Policy->GetTsSdkAPI()->PrepareListing(Request, ImmutableTsSdkApi::OpenAPIOrderbookApi::FPrepareListingDelegate::CreateUObject(this, &USearchNfTsWidget::OnPrepareListing));

2. Sign and submit the approval transaction

Once the listing request is prepared and sent, the response will contain actions that need to be taken. If the player has never approved your contract to interact with the Immutable Orderbook before, the Transaction action will be present in the response.

This Transaction action must be signed and submitted to the blockchain through the Immutable SDK to grant the approvals required to create listings in the Orderbook. This action only needs to be taken once per user per collection.

If the Transaction action is not present, you can skip this step and continue to sign then submit the listing.

GetOwningCustomLocalPLayer()->SignSubmitApproval(PopulatedTransactionsTo, PopulatedTransactionsData, [this, SignDataLambda](FString TransactionHash, FString Status)
{
    ...
});

3. Sign the typed order data

Once the approval transaction is signed and submitted, or if the Transaction action is not present, the listing can be signed using the typed order data. To successfully sign the listing, the typed order data must be serialised into a JSON string and signed using the player's wallet.

FString JsonText;
TSharedRef<TJsonWriter<TCHAR, TCondensedJsonPrintPolicy<TCHAR>>> JsonWriter = TJsonWriterFactory<TCHAR, TCondensedJsonPrintPolicy<TCHAR>>::Create(&JsonText);

Message.WriteJson(JsonWriter);
JsonWriter->Close();

GetOwningCustomLocalPLayer()->SignData(JsonText, [this, Content](const FString& Signature)
{
    ...
});

4. Create the listing

After the typed order data is signed, the listing can be created using the CreateListing method of the Immutable Orderbook API.

ImmutableTsSdkApi::OpenAPIOrderbookApi::CreateListingRequest Request;
ImmutableTsSdkApi::OpenAPICreateListingRequest RequestData;

RequestData.OrderComponents = Content.OrderComponents;
RequestData.OrderHash = Content.OrderHash;
RequestData.OrderSignature = Signature;
Request.OpenAPICreateListingRequest = RequestData;

Policy->GetTsSdkAPI()->CreateListing(Request, ImmutableTsSdkApi::OpenAPIOrderbookApi::FCreateListingDelegate::CreateUObject(this, &USearchNfTsWidget::OnCreateListing));

After creating the listing

The order creation transaction is now being processed. Orders created will initially be in PENDING status. Upon further validating the required contract approvals and ownership of the NFT being listed on‑chain, the order will asynchronously transition to the ACTIVE status.

We recommend taking an optimistic view and showing the order as ACTIVE as soon as it is created, then polling the order status to check for updates for the most seamless player experience.

💡Status polling

You can poll the Get Listing endpoint to check on status updates - in the near future we also plan on introducing push based (webhook) integration for order events.

You can see all the different order status types in the table in the order statuses documentation.

For more details on each step, you can read the Typescript documentation for creating orders since the Unreal Orderbook closely follows this implementation. You can also view a full example in the Unreal sample game.

---

Related content

Create Order

Further information about filling orders can be found in the Typescript documentation.

Learn more

Order Statuses

Understand the different order statuses and what they mean using this reference table.

Learn more

Unreal Marketplace Tutorial

This tutorial series walks you through the in-game marketplace in our Unreal sample game.

Learn more