Gods Unchained Marketplace API - how to use with examples in Python. Part. 1

Have you ever wondered where websites like gucards have data about marketplace that powers theirs website? Immutable X actually exposes an API that lets anyone fetch it. I have used it to create some of the datasets that I previously pasted on this sites such as: Comparison of mint cost of core cards with their market price or Price comparison of Gods Unchained cards in ETH/Gods. I wanted to present some cool examples of this api usage with examples of code in python. Today, I am going to show you how to get a list of card listings.

Getting cards listed for sale.

In order to get list of cards listed for sale, we need to send a get request to the following endpoint: https://api.x.immutable.com/v1/orders
(you can actually click at the link to see the type of response we get.)
You will see something like this.

As a result we get a response in JSON format containing 100 latest listings. Each listed trade will contain - among others - buy and sell sections. Sell section specifies the type of token that is being offered, whereas buy section specifies the kind of token user wants in return. The name of the offered card will be listed under the properties section. When it comes to sell section, it specifies the type of currency and requested amount. Specified amount should be divided by normalization factor (in case of $GODS and ETH 10^18). The type of cryptocurrency required is specified by token_adress according to the table below:

There are 2 caveats to the above. First of all, the list we get will specify both the active listings, as well as those that are not active. To get around that we just need to specify "status=active" as part of our get call. The other issue is that we only get 100 listings. We can actually change that amount by specifying the page_size argument, but unfortunately maximal accepted value is 200. How to get around that? Immutable X API uses mechanism called pagination. After providing us with 100 latest listings, it also provides us with pointer called "cursor" as part of endpoint response. This cursor actually points to the earliest item we have not been given in our previous request. If we provide this pointer in our next API call, we will get our next 100 items starting from that one. So all we need to do is to always provide the last cursor we got until we get all of the listings.

The following code snippet enables you to fetch the data from an API and puts them at all_active_orders list.

import datetime
import json

import requests

all_active_orders = []
all_trades_ids = set()

headers = {"Accept": "*/*"}
url = f"https://api.x.immutable.com/v1/orders?page_size=200&status=active"

while True:
    response = requests.request("GET", url, headers=headers)
    response = json.loads(response.content)
    all_active_orders.extend(response['result'])
    cursor = response['cursor']
    new_trade_ids = {x['order_id'] for x in response['result']}
    if len(all_trades_ids.intersection(new_trade_ids)) > 0:
        break
    all_trades_ids = all_trades_ids.union(new_trade_ids)
    url = f"https://api.x.immutable.com/v1/orders?page_size=200&status=active&cursor={cursor}"

Let me know your thoughts on the tutorial. I'd be happy to provide information about other endpoints present in Immutable X API.