Hey there!
Currently there are only two APIs available for assets - listAssets and getAsset
Which means that if I want to get all the assets for the given token_address I would need to either look through all the assets via listAsset doing filtering on my end or find all token_ids and query them one by one via getAsset.
Either way your server would start blocking me after a while with HTTP 429 Too Many Requests response.
Do you have a plan to introduce an API for token_address like https://api.x.immutable.com/v1/assets/<token_address> that would return the page_size results of getAsset call?
if not - what to do about 429 HTTP response code if I want to get all the the data for the given token_address?
Hey Enigo, I am a bit confused. My understanding is, you’d like to get all the fees related to assets on Immutable Protocol? To do this, you are now querying ‘ListAsset’ and get all the token address + token ID, then querying ‘GetAsset’ to get the information that’s not on the ‘ListAsset’?
If my understand is correct, there is no current plans to build a ‘GetAsset’ to return the same page size as ‘ListAsset’, as the design for ‘GetAsset’ is to see the detail of a particular asset. There are potentially ways around the rule, but will involve some backend coding.
I personally think it’s probably easier/faster to query ‘orders’ endpoint first to get all information about a token that’s listed/sold before. Then find any assets that hasn’t been listed before by doing a left outer join. The last step is to query those tokens via ‘GetAsset’. And yes, without an API key, you’ll need to time these calls so that it doesn’t exceed 5 RPS. Otherwise you’ll likely get a 429 error.
Hey @Yaz
No no, this question has nothing to do with the fees nor with changing the existing GetAsset API.
I’m trying to fetch all the metadata associated with the given asset, say this one. And what I’m saying is to have another API that would be queried via https://api.x.immutable.com/v1/assets/<token_address>, so instead of me getting one response like
{"token_address":"0x9e0d99b864e1ac12565125c5a82b59adea5a09cd","token_id":"95681","id":"0x3c6714962d64c0fa1eae47397fb095b57c3c41d1d597faa93881e71e1042a556","user":"0x1a3b0ffc93f2e0037a536ce79d92028e2add26ce","status":"imx","uri":null,"name":"Halcyon Sea (603,538)","description":null,"image_url":"https://assets.illuvium-game.io/illuvidex/land/land-95681.svg","metadata":{"name":"Halcyon Sea (603,538)","tier":3,"fuels":6,"solon":4,"carbon":3,"region":"Halcyon Sea","crypton":2,"silicon":4,"elements":9,"hydrogen":2,"hyperion":0,"landmark":"Eternal Spring","image_url":"https://assets.illuvium-game.io/illuvidex/land/land-95681.svg","coordinate":"603,538"},"collection":{"name":"Illuvium Land","icon_url":"https://assets.illuvium-game.io/illuvidex/imx/land/icon.png"},"created_at":"2022-06-05T11:45:11.784671Z","updated_at":"2022-09-14T11:56:01.343226Z"}
I would get an aggregated response with the result node of page_size size like it is done for other APIs, e.g.:
{
"result": [
{
"token_address": "0x9e0d99b864e1ac12565125c5a82b59adea5a09cd",
"token_id": "16665",
"id": "0xd54a37510bf126e923b04619d4767d0ee2af6858b9d9d569564743fb11de41de",
"user": "0xaf2845418a7883231d95b90137d8b95bb385ceeb",
"status": "imx",
"uri": null,
"name": "Crystal Shores (749,428)",
"description": null,
"image_url": "https://assets.illuvium-game.io/illuvidex/land/land-16665.svg",
"metadata": {
"name": "Crystal Shores (749,428)",
"tier": 1,
"fuels": 1,
"solon": 1,
"carbon": 2,
"region": "Crystal Shores",
"crypton": 0,
"silicon": 1,
"elements": 3,
"hydrogen": 0,
"hyperion": 0,
"landmark": "None",
"image_url": "https://assets.illuvium-game.io/illuvidex/land/land-16665.svg",
"coordinate": "749,428"
},
"collection": {
"name": "Illuvium Land",
"icon_url": "https://assets.illuvium-game.io/illuvidex/imx/land/icon.png"
},
"created_at": "2022-06-03T05:05:12.470752Z",
"updated_at": "2022-09-14T11:53:36.728844Z"
},
{
"token_address": "0x9e0d99b864e1ac12565125c5a82b59adea5a09cd",
"token_id": "95681",
"id": "0x3c6714962d64c0fa1eae47397fb095b57c3c41d1d597faa93881e71e1042a556",
"user": "0x1a3b0ffc93f2e0037a536ce79d92028e2add26ce",
"status": "imx",
"uri": null,
"name": "Halcyon Sea (603,538)",
"description": null,
"image_url": "https://assets.illuvium-game.io/illuvidex/land/land-95681.svg",
"metadata": {
"name": "Halcyon Sea (603,538)",
"tier": 3,
"fuels": 6,
"solon": 4,
"carbon": 3,
"region": "Halcyon Sea",
"crypton": 2,
"silicon": 4,
"elements": 9,
"hydrogen": 2,
"hyperion": 0,
"landmark": "Eternal Spring",
"image_url": "https://assets.illuvium-game.io/illuvidex/land/land-95681.svg",
"coordinate": "603,538"
},
"collection": {
"name": "Illuvium Land",
"icon_url": "https://assets.illuvium-game.io/illuvidex/imx/land/icon.png"
},
"created_at": "2022-06-05T11:45:11.784671Z",
"updated_at": "2022-09-14T11:56:01.343226Z"
}
... more entries
],
"cursor": "<cursor>",
"remaining": 1
}
I have no idea about your backend (very sad it is not open-source, I’d gladly contribute), but that doesn’t look particularly complicated - instead of fetching one asset with the given id and token_address it would fetch all assets with the given token_address and return it in a paginated manner.
Hi Enigo,
Arthur here from the support team, based on the conversation above I understand that you are trying to retrieve a list of assets from a collection to then extract the metadata per asset. To do this you need to use the ListAsset call but use additional params to return a paginated lister page.
It really depends on the criteria of your search and the order in which you wish to proceed but based on your example you are targeting a specific collection so for your example you would need to do a 3-step approach.
- Query the list of assets with a maximum page size
- Query the asset page for each item in this result e.g.
https://api.x.immutable.com/v1/assets/0x9e0d99b864e1ac12565125c5a82b59adea5a09cd/22789
- Proceed to the next page of the list using the cursor value of the previous page.
"cursor": "eyJpZCI6IjB4ZmRjYzI3ZDE2MjBhMWEwYWQ0ZmMwNzkyMjczMDBlOTZhM2E0MWE4NjkzYTg1NTU2OGM3MGI4MDVmZjA0YjZiMyIsIm5hbWUiOiJDcnlzdGFsIFNob3JlcyAoNjU1LDQ4MykiLCJ1cGRhdGVkX2F0IjoiMjAyMi0wOS0xNFQxMTo1MzozOC45MjU4NTJaIn0",
"remaining": 1
{URI}/v1/assets?page_size=200&cursor=eyJpZCI6IjB4ZmRjYzI3ZDE2MjBhMWEwYWQ0ZmMwNzkyMjczMDBlOTZhM2E0MWE4NjkzYTg1NTU2OGM3MGI4MDVmZjA0YjZiMyIsIm5hbWUiOiJDcnlzdGFsIFNob3JlcyAoNjU1LDQ4MykiLCJ1cGRhdGVkX2F0IjoiMjAyMi0wOS0xNFQxMTo1MzozOC45MjU4NTJaIn0&collection=0x9e0d99b864e1ac12565125c5a82b59adea5a09cd
The cursor is a base64 value of data from the end of the previous list.
You could orchestrate it in different orders:
- Get first list
- Paginate through all the pages and persist the asset data
- Iterate through asset data to extract metadata
Hope this helps 
Hi Enigo,
Sorry I misread your request this morning. What you are asking for is not possible at the moment i’m afraid. Our engineering team is working on delivering more event driven and streaming features which should make data interactions more streamlined. In the meantime you will need to implement local functionality to index this data as you have already mentioned. I know it is a bit of a pain at the moment we are working on making things better
1 Like
Hey @Arthur
thanks for your reply, it was really helpful!
I actually missed collection query parameter option in listAssets API (altho I must say it is a bit confusing that in one place it is called collection whilst in some other - token_address)
And just a side note - an alternative implementation I ended up with initially was querying mint API to get all the token_ids and then query single asset API
Hi Enigo, glad it helped 
ah yes the mint endpoint I forgot about it myself well done. I take the point about the collection vs token_address, this is due to there being two separate context for the address type. A token_address can be a collection or a contract address for an ERC-20 token. Let me take a look a bit closer and see if there is a case for escalating this inconsistency.
Will get back to you once I have more
Hi Onigo,
I haven’t been able to find any inconsistencies in the API spec. Probably the most confusing part is the orders api as both sides of an order require a token address which is correct because there can be different token types on both sides
Hey @Arthur
I was referring to Get details of an asset vs Get a list of assets APIs.
In getAsset the URL path field is called token_address whereas in listAssets a similar API query parameter is called collection. As the user of your API I’d expect both of them to use either token_address or collection (or maybe both fields). Coz it is the same API root - assets
Yes thats a good point, I will create a ticket for improvement thanks