Skip to main content

Creating orders

The fee model is changing in the latest version (v3) of the API.

Please refer to this guide to learn more about maker taker fees when you plan your migration to the upgraded v3 endpoints.

An order is a sale listing for an asset. It contains details like price and sale period. Some applications, such as marketplaces, may want to allow users to create orders in order to sell their assets.

Where is the order created?​

When an order is created, it is added to Immutable X's global orderbook service on StarkEx. This orderbook is shared by all applications built on the Immutable X protocol, which means that it can be accessed and displayed by any of them - allowing your order to be visible and available to be transacted with by all protocol participants.

This means that transations aren't siloed within certain applications, and has massive interoperability advantages for all assets and applications on the protocol.

📝Guides

Core SDK​

1. Initialize the Core SDK​

In order to use the Core SDK, you need to initialize it.

2. Generate signers​

Creating an order for a user requires a user's signature, so your application will need to create signers. See the guide on how to generate signers.

3. Set the order params​

When setting maker fees in the order params
  • You cannot set more than 3 recipients
  • You cannot set the same recipient more than once
  • The combined fee percentage can’t exceed 100%
  • Individual percentage fees can’t be <= 0% :::
📚SDK reference

The createOrder workflow is available in the Core SDK and is used to create an order for a user. It takes the following parameters:



/**
  * Function to create an Order
  * @param walletConnection - the pair of L1/L2 signers
  * @param request - the request object to be provided in the API request
  * @returns a promise that resolves with the created Order
  * @throws {@link index.IMXError}
  */
createOrder(walletConnection: WalletConnection, request: UnsignedOrderRequest): Promise<CreateOrderResponse>;

The parameters required to fill the UnsignedOrderRequest are:

/**
 * Parameter required to create an Order
 */
interface UnsignedOrderRequest {
  /**
   * The amount of tokens that will be bought for this order
   */
  buy: TokenAmount;
  /**
   * The amount of tokens that will be sold for this order
   */
  sell: TokenAmount;
  /**
   * ExpirationTimestamp in Unix time. Note: will be rounded down to the nearest hour
   */
  expiration_timestamp?: number;
  /**
   * Inclusion of either maker or taker fees
   */
  fees?: Array<FeeEntry>;
}

These parameters can be set with the following code:

note

Please be advised that all fees and quantities within our system are denoted in the smallest unit of the respective currency, and decimal representations are not supported.

For instance, IMX, which has 18 decimal places, will have a fee of 0.000000000000000001 IMX represented as "1".

Similarly, 1 IMX is represented as "1000000000000000000" in our system.

// OPTIONAL: Generate the date when order expire, in this case after one month by now
const timestamp = new Date(Date.now());
timestamp.setMonth(timestamp.getMonth() + 1);
const timestampUnix = Math.round(timestamp.getTime() / 1000); // Unix format is required

const orderData = {
  buy: {
    // The amount of tokens to purchase the asset
    amount: '10000000000000000', // Wei amount, equal to 0.01 ETH
    type: 'ETH',
  },
  sell: {
    // The asset to sell
    amount: '1',
    tokenAddress: YOUR_TOKEN_ADDRESS,
    tokenId: YOUR_TOKEN_ID,
    type: 'ERC721',
  },
  expiration_timestamp: timestampUnix, // OPTIONAL: order expiry date
  fees: [
    // OPTIONAL: Inclusion of either maker or taker fees
    {
      address: '0x383b14727ac2bD3923f1583789d5385C3A26f91E',
      fee_percentage: 0.5, // equal to 0.5%
    },
  ],
} as UnsignedOrderRequest;

Note: If creating a bid, the buy token will be the ERC721 and the sell token will be ERC20 / ETH.

4. Create the order​

📚SDK reference

Combining the parameters from the previous step, you can create an order. The response will contain the order ID, status and timestamp.

The following code snippet shows how to create an order with the parameters from the previous step:

const createOrder = async (
  wallet: WalletConnection, // WalletConnection containing the L1 and L2 signers
  orderData: UnsignedOrderRequest // Order Data from the previous step
) => {
  const response = await client.createOrder(wallet, orderData);
  return response;
};

createOrder(wallet, orderData)
  .then((result) => {
    console.log(result);
  })
  .catch((e) => {
    console.log(e);
  });

Example response​

{
  order_id: 7215, // ID of the created order
  status: '', // Status of the created order
  time: 0 // Timestamp of the created order
}

5. Cancel an order​

📚SDK reference

Let's say you wish to cancel the previous order. You can use the cancelOrder workflow. The response will contain the order ID and status of the order.

const cancelData = {
  order_id: 7215,
} as GetSignableCancelOrderRequest;

const cancelOrder = async (
  wallet: WalletConnection,
  cancelData: GetSignableCancelOrderRequest
) => {
  const response = await client.cancelOrder(wallet, cancelData);
  return response;
};

cancelOrder(wallet, cancelData)
  .then((result) => {
    console.log(result);
  })
  .catch((e) => {
    console.log(e);
  });

Example response​

{
  order_id: 7215, // ID of the cancelled order
  status: '' // New status of the order
}