Exploring Splinterlands API with a card search Discord bot

Trading Splinterland cards with a friend a week ago was a fun experience. It was much more gratifying than buying and selling cards in the marketplace. So it got me thinking if I could find more opportunities to acquire the cards that I want from my friends. I started looking for specific cards in their collection, but it was a long and tedious process that made me give up after several attempts.

After recalling from somewhere or someone that there was a Splinterlands API ... it led to this.

Splinter Scry Bot Command

After several minutes were wasted thinking of a name for the function, I decided on splinterscry. 'search' would have been more accurate but 'scry' sounded way cooler.


!splinterscry command first acquires your follower's list from Hive using HiveSQL. I assumed if my followers aren't that bothered to see me on their feed, then it's likely they are at least tolerating me. I'll take that as an opening for a potential trade.

Once the bot has the list, it checks for the card collection of each user using this API endpoint: https://api.splinterlands.io/cards/collection/romeskie, where romeskie can be replaced with any Hive username.

The bot lists down the quantity per level of the target players' collection. Cards that were delegated to other users or those that are being rented out are excluded from the list. It is possible to specify if you're looking for an Alpha or Beta edition. Recent cards such as in Untamed edition need not be specified in the bot commands, since all those beyond Beta are unique across all editions. It's also possible to search specifically for gold versions.

_{The results are so few. Either the card I'm searching for is very rare or I don't have many followers to search cards from. It's the latter.}

Is this command available to HiveBotPH users? Not at the moment. I'm still deciding and discovering more about the usage of this API so I'm unsure whether I should extend this beyond personal use.

A fair use of the API?

Part of the reason why I posted this on my blog is to allow more experienced developers to cross-check the concept of this function. The bot function's goal feels so inconsequential so I was wary of using the API endpoints in the first place. But my desire to learn something new and the utility in searching for potential trades pushed me into exploring the API.

I purposely made the information gathering process longer to maintain what I think is the standard minimum API call rate of 60 requests per minute (1 request/second). All the card details information was stored in code to minimize the request count -- the server keeps a permanent copy of this endpoint's data since it very rarely changes: https://api.splinterlands.io/cards/get_details

Any pointers or corrections with this prototype are greatly appreciated!

Some acknowledgments

Thank you to the whole development team who gave third-party developers the tools to interact with Splinterlands. There's also this well-documented API endpoint information prepared by KioKizz found here: https://github.com/kiokizz/Splinterlands-API. It has an organized list of all available endpoints and a better context of each endpoint's purpose. So thanks to KioKizz too!

For anyone who has questions with the bot, just drop a message in the comments section and I'll try to answer them as best as I can.

Random trivia: There are currently 351 unique cards in Splinterlands! More to come when the Chaos Legion edition arrives! Head to Splinterlands.com to start collecting!