Fill orders

To purchase an NFT the player needs to “fill” an existing order. This page explains how to fill an order using the Immutable Unreal Orderbook module.

For fulfilment to occur, the player must have sufficient funds to cover the asking price of the order.

💡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

Filling an existing order is the most common way for players to purchase NFTs in a marketplace. This process is pretty straight forward, the player simply needs to sign a the fulfillment transaction that includes the listing ID of the order they are wanting to fill and the buyer's wallet address.

To list fill a listing, you need to do the following:

1. Prepare the order fulfillment.
2. Sign and submit the approval transaction (if required).
3. Submit the order fulfillment.

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 SearchStacksListingWidget.cpp in our Unreal sample game and the Build a marketplace in Unreal tutorial.

💡Core functionality

There are other mechanisms for buying NFTs available in the Typescript Orderbook, such as placing bids or filling bulk orders. In this initial release, the Unreal SDK is limited to filling a single order using the FulfillOrder method described in this page.

Fill order workflow

1. Prepare the order fulfillment

This step sets up the necessary data for a filling an order, including the the listing's ID and the buyer's wallet address, and then sends the request using FulfillOrder method of Immutable Orderbook API.

ImmutableTsSdkApi::OpenAPIFulfillOrderRequest RequestData;
ImmutableTsSdkApi::OpenAPIOrderbookApi::FulfillOrderRequest Request;

RequestData.ListingId = ListingItemWidget->GetListingId();
RequestData.TakerAddress = LocalPlayer->GetPassportWalletAddress();

Request.OpenAPIFulfillOrderRequest = RequestData;

Policy->GetTsSdkAPI()->FulfillOrder(Request, ImmutableTsSdkApi::OpenAPIOrderbookApi::FFulfillOrderDelegate::CreateUObject(this, &USearchStacksListingWidget::OnFulfillOrder));

2. Sign and submit the approval transaction (if required)

Once the order fillfilment 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 ApprovalAction action will be present in the response.

This ApprovalAction 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 ApprovalAction action is not present, you can skip this step and continue to submit the order fulfillment.

GetOwningCustomLocalPLayer()->SignSubmitApproval(ApprovalAction->PopulatedTransactions->To.GetValue(), ApprovalAction->PopulatedTransactions->Data.GetValue(), [this, FulfillOrderLambda](FString TransactionHash, FString Status)
{
  ...
});

3. Submit the order fulfillment

Once the approval transaction is signed and submitted, the order fulfillment can be finalized. This step involves sending the fulfillment request to the Immutable Orderbook API, which will process the transaction and update the order status.

GetOwningCustomLocalPLayer()->SignSubmitApproval(Action.PopulatedTransactions->To.GetValue(), Action.PopulatedTransactions->Data.GetValue(), [this](FString TransactionHash, FString Status)
{
  ...
});

After filling the order

The order fulfilment transaction is now being processed. Upon validating the required contract approvals and wallet balance requirements on‑chain, the order will asynchronously transition to the FILLED status.

We recommend taking an optimistic view and showing the order as FILLED as soon as it is submitted, 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 filling orders since the Unreal Orderbook closely follows this implementation. You can also view a full example in the Unreal sample game.

---

Related content

Fill 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