How to migrate from the v1 trading endpoints

The v1 order and trade endpoints will be sunset in September 2023. Users must migrate from v1 to v3. This documents explains the difference between the API versions and provides a migration guide for common order and trade scenarios.

Requisite pre-reading

Summary of changes between v1 & v3

Fees are no longer the sole responsibility of the buyer, with the new fees model both the buyer and seller are liable to pay fees - this fee model is referred to as “split fees” in this document.
The maker of the order will always pay the maker marketplace fees, the taker of the order will always pay the taker marketplace fees.
In addition to the prior point, the buyer always pays the royalty and protocol fees.
It is only possible for the legacy v1 orders to have a "maker" fee entry inside the taker_fees section but it is not possible to have a "taker" fee entry inside the maker_fees section for any orders.
The newer v3 orders, where both maker and taker are liable to pay fees, will always have a "maker" fee entry inside the maker_fees section only and a "taker" fee entry inside the taker_fees section only.

Deprecated fields and their replacements

Deprecated field from v1/orders	Replacement field in v3/orders	Comments
fees	fees field in maker_fees / taker_fees section	fees split for each side of the order
N/A	maker_taker_type	Identify the type of order
buy.quantity_with_fees	quantity_with_fees field in maker_fees / taker_fees section	fees inclusive amount
sell.quantity_with_fees	quantity_with_fees field in maker_fees / taker_fees section	fees inclusive amount

How to target v3 trade endpoints from Link

Initialise link with the following parameter

const link = new Link(linkAddress)

List of scenarios and sample responses

Create a listing

Scenario - As a marketplace user, I want to sell my NFT asset on a marketplace and will therefore need to list said asset for sale.

A listing is a sell order and is a maker order as this user is adding / making liquidity to the orderbook.

Steps:

Assuming asset is minted and seller is the owner of the asset, first request the protocol and royalty fee percentages & recipients applicable for an asset using /v1/assets/{token_address}/{token_id}
Perform local calculation to
a. Show the seller the final amount they stand to receive exclusive of maker market_place fees (if applicable).
b. Show the estimated price a buyer will need to pay to purchase the asset by adding the base_price to royalty, protocol fees & taker marketplace fees if applicable.
c. Show the seller the breakdown of the fees contributing to the overall buy price.

Sample calculation logic for listing price

The amount that is passed to link.Sell() is the base_price of the asset which is calculated taking into account the maker_fees.

base_price = user_entered_amt + fee_amt

Assuming the UI allows the seller to enter a value that they expect to receive in their wallet for the sale, the marketplace needs to calculate the base_price of the asset inclusive of the maker fees. This base_price will be used to calculate / estimate the final buy_price which may include protocol, royalty and taker fees.

Let's consider a scenario where the user expects to receive 0.4 ETH for the sale and there is 0.5% maker fee, the base_price will then be 0.402010050251256

Detailed explanation:

Considering the maker fee is 0.5% of the base_amt, the user_entered_amt will be 99.5% of the base_amt.

Therefore the base_amt can be calculated by,

0.4/0.995 = 0.402010050251256

Passing this amount to link.Sell() will ensure the seller gets 0.4 ETH for the sale.

Final maker fees amt = 0.402010050251256 * 0.005 = 0.002010050251256

Final seller received amt = 0.402010050251256 -0.002010050251256 = 0.4

Example /v1/assets/{token_address}/{token_id}

Request

https://api.x.immutable.com/v1/assets/0xacb3c6a43d15b907e8433077b6d38ae40936fe2c/14761092?include_fees=true

Response

{
  "token_address": "0xacb3c6a43d15b907e8433077b6d38ae40936fe2c",
  "token_id": "14761092",
  ...
  "fees": [
    {
      "type": "royalty",
      "address": "0x43d6c1b85579dacab253a82be40a2f19113ca9c4",
      "percentage": 1
    },
    {
      "type": "royalty",
      "address": "0x7b31c77f126421206690dc2e52c0fd4cf7275af5",
      "percentage": 3
    },
    {
      "type": "protocol",
      "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
      "percentage": 2
    }
  ]
}

Show active orders - NFTs for sale

Scenario - As a marketplace user, I want to view all the assets that are currently listed for sale along with the buy price i.e total amount inclusive of fees that should be paid to acquire the asset.

Steps:

Assuming that you show assets available for sale on a per collection basis - Request a list of orders that are specific for a collection.
a. Use the sell_token_address parameter to specify the collection address.
b. Provide auxiliary fee information parameter so fee calculation can take into account the aux fees.
c. Additional params as required - e.g status, order_by etc
Use the quantity_with_fees value inside the taker_fees section to display the amount that a buyer (order taker) will need to pay to acquire the asset.
Use the fees array inside the taker_fees section to show the breakdown of the fees for the buyer.

Request

https://api.x.immutable.fyi/v3/orders?order_by=created_at&direction=desc&status=active&sell_token_address=0x8cceea8cfb0f8670f4de3a6cd2152925605d19a8

Response

{
  "result": [
    {
      "order_id": 295334897,
      ....
      "maker_taker_type": "maker",
      ....
      "taker_fees": {
        "quantity_with_fees": "466400000000000",
        "token_type": "ETH",
        "decimals": 18,
        "symbol": "ETH",
        "fees": [
          {
            "type": "protocol",
            "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
            "token": {
              "type": "ETH",
              "data": {
                "decimals": 18
              }
            },
            "amount": "8800000000000"
          },
          {
            "type": "royalty",
            "address": "0x9989818ae063f715a857925e419ba4b65b793d99",
            "token": {
              "type": "ETH",
              "data": {
                "decimals": 18
              }
            },
            "amount": "13200000000000"
          },
          {
            "type": "maker",
            "address": "0x73b6616316e6048284658f6bda58c17eb40db542",
            "token": {
              "type": "ETH",
              "data": {
                "decimals": 18
              }
            },
            "amount": "4400000000000"
          }
        ]
      }
    }
    }
  ],
  "cursor": "xyz",
  "remaining": 1
}

N.B

Legacy orders in the platform (created prior to v3/orders) followed a fee model where the buyer / taker paid all the fees. Hence when legacy maker orders are returned in the v3/orders [GET] endpoint, the taker_fees section can include a maximum of four fee types - maker marketplace, taker marketplace, royalty and protocol fees as shown below.

"taker_fees": {
  "quantity_with_fees": "466400000000000",
  "token_type": "ETH",
  "decimals": 18,
  "symbol": "ETH",
  "fees": [
    {
      "type": "protocol",
      "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
      ....
    },
    {
      "type": "royalty",
      "address": "0x9989818ae063f715a857925e419ba4b65b793d99",
      ....
    },
    {
      "type": "maker",
      "address": "0x73b6616316e6048284658f6bda58c17eb40db542",
      ....
    },
  {
      "type": "taker",
      "address": "0x73b6616316e6048284658f6bda58c17eb40db542",
      ....
    }
  ]
}

When listings created using the v3/orders endpoint, which implements split fees, are returned in the v3/orders [GET] endpoint, the taker_fees section can only include a maximum of three fee types - taker marketplace, royalty and protocol fees as shown below.

"taker_fees": {
  "quantity_with_fees": "466400000000000",
  "token_type": "ETH",
  "decimals": 18,
  "symbol": "ETH",
  "fees": [
    {
      "type": "protocol",
      "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
      ....
    },
    {
      "type": "royalty",
      "address": "0x9989818ae063f715a857925e419ba4b65b793d99",
      ....
    },
    {
      "type": "taker",
      "address": "0x73b6616316e6048284658f6bda58c17eb40db542",
      ....
    }
  ]
}

Buy an asset - Fill a listing

Scenario - As a marketplace user, I want to buy a NFT asset on a marketplace and will need to be informed of the buy price i.e total amount inclusive of fees that should be paid to acquire the asset.

Steps:

Request order information for the order in question using the order_id
a. Provide auxiliary fee information parameter so fee calculation can take into account the taker fees.
Use the quantity_with_fees value inside the taker_fees section to display the amount that a buyer (order taker) will need to pay to acquire the asset.
Use the fees array inside the taker_fees section to show the breakdown of the fees for the buyer.

Order without split fees:

taker_fees.quantity_with_fees is the total amount that an order taker will pay to buy the asset.

Request

https://api.x.immutable.fyi/v3/orders/295334897?auxiliary_fee_percentages=1&auxiliary_fee_recipients=0x11

Response

{
  "order_id": 295334897,
  ....
  "maker_taker_type": "maker",
  "maker_fees": {
    "quantity_with_fees": "440000000000000",
    "token_type": "ETH",
    "decimals": 18,
    "symbol": "ETH",
    "fees": [],
  },
  "taker_fees": {
    "quantity_with_fees": "470800000000000",
    "token_type": "ETH",
    "decimals": 18,
    "symbol": "ETH",
    "fees": [
      {
        "type": "protocol",
        "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
        ....
        "amount": "8800000000000"
      },
      {
        "type": "royalty",
        "address": "0x9989818ae063f715a857925e419ba4b65b793d99",
        ....
        "amount": "13200000000000"
      },
      {
        "type": "maker",
        "address": "0x73b6616316e6048284658f6bda58c17eb40db542",
        ....
        "amount": "4400000000000"
      },
      {
        "type": "taker",
        "address": "0x11",
        ....
        "amount": "4400000000000"
      }
    ]
  }
}

Order with split fees

taker_fees.quantity_with_fees is the total amount that an order taker will pay to buy the asset.

maker_fees.quantity_with_fees is the total amount that an order maker will receive as part of the asset sale.

Request

https://api.sandbox.x.immutable.fyi/v3/orders/322130?auxiliary_fee_percentages=1&auxiliary_fee_recipients=0x11

Response

{
  "order_id": 322130,
  ....
  "maker_taker_type": "maker",
  "maker_fees": {
    "quantity_with_fees": "10000000000000000000",
    "token_type": "ETH",
    "decimals": 18,
    "symbol": "ETH",
    "fees": [
      {
        "type": "maker",
        "address": "0x9c782e4f67064d5cb2bd3080d043de1c5081aad3",
        "token": {
          "type": "ETH",
          "data": {
            "decimals": 18
          }
        },
        "amount": "101010101000000000"
      }
    ]
  },
  "taker_fees": {
    "quantity_with_fees": "10404040404000000000",
    "token_type": "ETH",
    "decimals": 18,
    "symbol": "ETH",
    "fees": [
      {
        "type": "protocol",
        "address": "0xa6c368164eb270c31592c1830ed25c2bf5d34bae",
        "token": {
          "type": "ETH",
          "data": {
            "decimals": 18
          }
        },
        "amount": "202020202000000000"
      },
      {
        "type": "taker",
        "address": "0x11",
        "token": {
          "type": "ETH",
          "data": {
            "decimals": 18
          }
        },
        "amount": "101010101000000000"
      }
    ]
  }
}

N.B

Explanation for fees returned in the taker_fees section for maker orders in legacy v1 and newer v3 orders are applicable for v3/orders/{id} endpoint also.

Bids - Creating a bid

When creating a bid or a buy order, the buyer (party creating the bid / making an offer) will be liable to pay maker marketplace fees (as they are the maker in this scenario) in addition to the protocol and royalty fees.

The system currently only supports creating a bid on a listed asset i.e an asset that is already listed for sale and has an active sell order associated with it.

N.B - Bids will always follow the split fee model i.e maker will always pay maker marketplace fees and taker will pay taker marketplace fees.

Scenario

As a buyer, I want to make an offer / place a bid on a listed asset.

Steps - To determine current listing price of the asset:

Request order information for the sell order in question using the order_id.
a. Provide taker fees percentage and recipient as auxiliary fee information.
Use the quantity_with_fees value inside the taker_fees section to determine the final buy price of the asset.
Use the quantity value inside the buy section to determine the base price of the asset / calculate the minimum bid price. Note - Minimum allowed bid price is 10% of base_price of the asset.

Steps - To determine final bid price:

To determine the final bid price, request the protocol and royalty fee percentages & recipients applicable for an asset using /v1/assets/{token_address}/{token_id}
Apply royalty and protocol fee percentage on user entered base bid amount.
Add user entered base price with the calculated royalty & protocol fees along with the maker marketplace fees (if applicable) to arrive at the final bid amount.

Accepting a bid / offer

Scenario

As a seller, I want to accept a bid / offer and sell my NFT asset for fungible tokens / ETH.

Steps

Request order information for the buy order / bid in question using the order_id
a. Provide auxiliary fee information parameter so fee calculation can take into account the taker fees.
Use the quantity_with_fees value inside the taker_fees section to display the amount that the seller (taker) will need to pay to sell the asset.
Use the fees array inside the taker_fees section to show the breakdown of the fees that the taker is liable to pay (the taker in this scenario is the seller of the asset)

maker_fees.quantity_with_fees is the total amount that an order maker (bidder) will pay to buy the asset.

taker_fees.quantity_with_fees is the total amount that an order taker (seller) will receive as part of the asset sale.

Request

https://api.x.immutable.com/v3/orders/296089354?auxiliary_fee_percentages=1&auxiliary_fee_recipients=0x111

Response

{
  "order_id": 296089354,
  ....
  "maker_taker_type": "maker",
  "maker_fees": {
    "quantity_with_fees": "45150000",
    ....
    "fees": [
      {
        "type": "royalty",
        "address": "0xf3b26b98fe1fe510a06c2b6c30a8e13f01630302",
        "token": {
          "type": "ERC20",
          "data": {
            "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "decimals": 6
          }
        },
        "amount": "1290000"
      },
      {
        "type": "protocol",
        "address": "0xe0e2953ca1cf5412cdc8b991cee9143909dbddf4",
        "token": {
          "type": "ERC20",
          "data": {
            "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "decimals": 6
          }
        },
        "amount": "860000"
      }
    ]
  },
  "taker_fees": {
    "quantity_with_fees": "43430000",
    "token_type": "ERC20",
    "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": 6,
    "symbol": "USDC",
    "fees": [
      {
        "type": "taker",
        "address": "0x111",
        "token": {
          "type": "ERC20",
          "data": {
            "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "decimals": 6
          }
        },
        "amount": "430000"
      }
    ]
  }
}

Requisite pre-reading​

Summary of changes between v1 & v3​

Deprecated fields and their replacements​

How to target v3 trade endpoints from Link​

List of scenarios and sample responses​

Create a listing​

Steps:​

Sample calculation logic for listing price​

Example /v1/assets/{token_address}/{token_id}​

Show active orders - NFTs for sale​

Steps:​

Buy an asset - Fill a listing​

Steps:​

Order without split fees:​

Order with split fees​

Bids - Creating a bid​

Scenario​

Steps - To determine current listing price of the asset:​

Steps - To determine final bid price:​

Accepting a bid / offer​

Scenario​

Steps​

Requisite pre-reading

Summary of changes between v1 & v3

Deprecated fields and their replacements

How to target v3 trade endpoints from Link

List of scenarios and sample responses

Create a listing

Steps:

Sample calculation logic for listing price

Example /v1/assets/{token_address}/{token_id}

Show active orders - NFTs for sale

Steps:

Buy an asset - Fill a listing

Steps:

Order without split fees:

Order with split fees

Bids - Creating a bid

Scenario

Steps - To determine current listing price of the asset:

Steps - To determine final bid price:

Accepting a bid / offer

Scenario

Steps