Thermos Proxy API
Technical documentation for interacting with Thermos Proxy API
First Steps
A detailed description of the API can be found in the Stoplight UI.
⚠️ Note: The Thermos Proxy API is currently in beta and may change frequently. We recommend checking the Stoplight UI for the latest version of the API.
General concepts
Currency and Pricing
All price values in this API (like floor
or price
) are represented as strings in nanotons. A string is used to avoid precision loss with very large numbers.
1 TON = 1,000,000,000 nanoton
Rarity
Some attributes include a rarity_per_mille
field. This indicates the rarity of the attribute out of 1,000. For example, a rarity_per_mille
of 30
means there is a 3% (30/1000) chance of this attribute appearing.
Some attributes also include a rarity_score
field. This number is a product of all rarity_per_mille
values. Foe example, if gift has model (10
), backdrop (20
) and symbol (5
), its rarity_score
is 1000
.
Colors
Colors are represented as integers (decimal format of a hex code). For example, 5470609
is #537791
.
Gifts API
List gift collections
You can use this endpoint to obtain the full list of gift collections & associated attributes (image url, floor, count)
The API will return a list of ApiGiftCollection
objects:
List gift backdrops
You can use this endpoint to obtain the full list of gift backdrops & associated attributes (colors, floor, count)
The API will return a list of ApiBackdrop
objects:
List gift symbols
You can use this endpoint to obtain the full list of gift symbols & associated attributes (image url, floor, count)
The API will return a list of ApiSymbol
objects:
List collection attributes
You can use this endpoint to obtain supported attributes (symbols, backdrops, models) for a list of collections
You must specify list of collection names in the request body:
The API will return an ApiGiftCollectionAttributesResponse
object,
which is a dictionary where keys are collection names and values are ApiCollectionAttributes
objects:
Gift search
You can use this endpoint to perform a complex search operation
You must specify request body which is a ApiGiftSearchRequest
object:
Every parameter here is optional, e.g. this request body, in fact, is valid:
Parameters overview:
ordering
: defines the sort order of gifts. Allowed values arePRICE_ASC
,PRICE_DESC
,MODEL_RARITY_ASC
,MODEL_RARITY_DESC
,BACKDROP_RARITY_ASC
,BACKDROP_RARITY_DESC
,SYMBOL_RARITY_ASC
,SYMBOL_RARITY_DESC
,RARITY_SCORE_ASC
,RARITY_SCORE_DESC
,NUMBER_ASC
,NUMBER_DESC
page
: defines current page. Minimum page is1
per_page
: defines number of gifts per pagequery
: defines full-text search queryprice_range
: defines min & max price; prices are specified in nanoton. min & max are optional, e.g. you can specify either one of them or bothnumber
: defines the gift numbercollections
: defines the list of gift collectionsmodels
: defines the list of gift modelsbackdrops
: defines the list of gift backdropssymbols
: defines the list of gift symbolsmarkets
: defines the list of gift markets
The API will return an ApiGiftSearchResponse
object:
Note that this api returns cached information and returned information may be outdated (e.g. price may be changed or gift may be already sold).
You should always validate the current gift info by calling the Get gift
endpoint
Get gift
You can use this endpoint to get a gift by its marketplace & external id. This endpoint always returns actual data
The API will return an ApiGiftExternal
object in case of success, or 404
if gift is not available anymore: