Creating orders
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.
Typescript SDK
1. Initialize the SDK
In order to use the 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. Then setup GenericIMXProvider
3. Set 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%
Order parameters required to fill is defined in UnsignedOrderRequest
These parameters can be set with the following code:
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
Combining the parameters from the previous step, you can create an order. The response will contain the order ID, status and timestamp.
Request
The following code snippet shows how to create an order with a provider and the parameters from the previous step:
const createOrderResponse = await imxProvider.createOrder(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
Let's say you wish to cancel the previous order. You can use the cancel order workflow. The response will contain the order ID and status of the order.
Request
const cancelData = {
order_id: 7215,
} as GetSignableCancelOrderRequest;
const response = await imxProvider.cancelOrder(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
}