Asset Trading

Building a marketplace which supports the trading of Immutable X assets is quick and easy. You'll need to:

  • Use our Orderbook APIs to display assets which are currently for sale
  • Use our Immutable Link SDK to prompt user actions

You should be familiar with Immutable X assets from our Supporting Asset Ownership tutorial.

Order Types

There are two types of order supported by Immutable X: it is important to understand the difference between the two.

Action

Description

Fill Order

Fill an existing order. If the existing order is filled by the time this order reaches the order book, revert without adding this order to the book.

Order

Create an order which will be either filled immediately or added to the order book.

The structure of an order is as follows:

{
    "user": "0x...",
    "buy": {
    "contract": "0x...",
    "amount": "1000000"
  },
  "sell": {
    "contract": "0x...",
    "token_id": "1000"
  }
}
{
    "user": "0x...",
  "buy": {
    "contract": "0x...",
    "amount": "1000000"
  },
  "sell": {
    "contract": "0x...",
    "token_id": "1000"
  },
  "fill_order_id": "23332-1221121"
}

Central Orderbook

To help facilitate liquidity, Immutable maintains a central orderbook which can be immediately accessed by any application via our API. Adding your orders to this book will enable them to be filled by any other client application, improving your likelihood of being able to capture fees from these orders.

The APIs for this orderbook are as follows:

Currently, Immutable X doesn't support updating existing orders, only cancellation and replacement.

Submitting Trades

If you have matched two orders on L2, you can submit those directly to the API using the Create Trade endpoint. Note that these trades must still be signed by the relevant users.

Immutable Link

Immutable X allows users to keep their existing Ethereum wallet: no installations, upgrades or changes required.

To ensure that users are able to sign trades which can be processed by Immutable X, and to ensure that applications display the correct assets to users and provide them with informed consent, Immutable provides a bridging service called Immutable Link. This service uses a signed security string to derive a STARK-friendly Immutable X key, which the user will use to sign L2 interactions. This ensures that users can always recover assets as long as they retain access to their Ethereum wallet.

Immutable Link is a separate web application, now with iframe support more information here. All StarkEx-specific Immutable X interactions are abstracted away from your marketplace and into Immutable Link.

Immutable Link will soon be open source and made publicly available.

Link SDK

Immutable provides a convenient interface for initiating Immutable Link actions in the form of a Typescript SDK. To install the SDK in your project, use:

npm install @imtbl/imx-link-sdk

This SDK allows users to prompt the Immutable Link window using a simple set of Typescript functions (draft interface presented below):

interface ETH {
    amount: string; 
}

interface ERC20 {
    contract: string;
  amount: string;
}

interface ERC721 {
    contract: string;
    token_id: string;
}

type Asset = ETH | ERC20 | ERC721;

interface Order {
  user: string;
  buy: Asset;
  sell: Asset;
}

interface ETHTxResponse {
  rejectedSignature: boolean;
  rejectedLink: boolean;
  txhash: string;
}

interface ImXTxResponse {
    id: string; 
  success: boolean;
}
 
class Link {    
  public deposit(user: string, assets: Array<Asset>): Promise<ETHTxResponse>;
  public withdraw(user: string, assets: Array<Asset>): Promise<ETHTxResponse>;
  public transfer(user: string, to: string, assets: Array<Asset>): Promise<ImXTxReponse>;
  public fill(user: string, orderIDs: Array<string>): Promise<ImXTxReponse>;
  public order(user: string, orders: Array<Order>, broadcast = true): Promise<ImXTxReponse>;
}

A high-level overview of the trading process is as follows.

Example

To help make all this a little more concrete, consider a marketplace for Axies.

First, the marketplace uses the Get Orders endpoint to load a list of active orders. Our buyer decides to buy a Mystic Axie for 3 ETH. The marketplace uses the Link SDK to prompt the Link by calling link.fill(buyer_address, [id of order]). The Link will then use the Get Order Details endpoint to get the required parameters for the user to sign. The user will sign the order, and the Link will use the Submit Order endpoint to send it to Immutable X. The exchange will confirm or reject the trade, and notify the Link, which will send an ImXTxResponse back to the marketplace, which can display the success or failure of the trade to our user. The asset will be immediately available for trading or use within Axie Infinity (provided they support asset ownership).

Frequent Questions

1. Is there an auction flow functionality?
Currently, the auction flow functionality is not supported yet. It will be coming later.

2. What happens when a trade happens on Immutable? Is there a callback sent to our servers to adjust our application inventory?
At the moment, we recommend polling our /mints, /transfers and /trades APIs at regular intervals - we'll likely set up webhooks/sockets in future.

3. How do we ensure the Smart Contract is utilised whenever the NFT is traded?
To ensure this, you will need to ban direct transferring from user to user. Best way to combat this is providing the best place to trade and ensuring it’s within Immutable X.


Did this page help you?