Skip to main content

Creating orders

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 ImmutableX's global orderbook service on StarkEx. This orderbook is shared by all applications built on the ImmutableX 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.

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:

// 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: '[REPLACE WITH TOKEN ADDRESS]',
tokenId: '[REPLACE WITH 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;

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
}