This post is intended for all you Splinterlands community developers out there.
With Rebellion Conflicts coming soon, and already available for testing on the Mavs QA server, I figured it's time to go over the details of API additions that have been made to support this new airdrop mechanism.
Note that the following changes will not go live for the real game until Conflicts is released, but you can try them all out now in Mavs QA. All example links are for Mavs QA; for the real game you would replace api.mavs-sl.com with api.splinterlands.com
Conflicts are organized into a series of 9 roughly monthly events, which internally are known as Conflict Seasons (analogous to Ranked Play Seasons). There is an End-Of-Conflict (EOC) process, after which the Airdrop Card for that particular Conflict becomes claimable. The next Conflict Season begins immediately after the previous one finishes. At EOC, all cards & packs that players have staked will automatically carry over to the next Conflict Season, but contribution points will be reset and start accumulating from 0 again.
These APIs will have a wagon_uid field added to the data for each card, which will be set if that particular card is staked on a Mage Wagon. If the card is not staked, wagon_uid will be null.
Examples:
Fetches data about Conflict Seasons. Note that various fields for future Conflict Seasons that have not started yet may be null or set with dummy data, until such time as that season is about to start. We don't have all 9 Airdrop Cards finalized yet.
Examples:
Returns data about players participating in particular Conflict Seasons, including contribution points towards the Conflict and Airdrop Cards won in completed Conflicts, if any.
Note that if not explicitly specified with optional parameters, by default airdrop data is not included and the sort order will be reward_points DESC, player ASC
Examples:
ORDER BY reward_points DESC, progress_to_next DESC, player ASC and any number of columns / fields can be included.Notes about meaning of player data fields:
conflict_season ASC. This mode adds extra information about each Conflict Season and the number of airdrop cards awarded in the distribution for completed Conflict Seasons. This information, together, can be used to determine if a player has any outstanding Conflicts airdrops that need to be claimed.An optional parameter that can be combined with the player and mode parameters. Has no effect if you are retrieving data for all players. This will add a list of uids for airdrop cards received. It’s the most data intensive type of querying, so should be used sparingly.
Examples:
Returns airdrop distribution data for completed Conflicts, showing how many cards were awarded to each player. Note that this data does not indicate what proportion of cards are regular foil vs gold foil; for that you need to look at the airdrop claim data from the conflicts/players API.
Also, the default sort order of results is num_prizes DESC, player ASC
Examples:
ORDER BY num_prizes DESC, player ASC and any number of columns / fields can be included.conflict_season ASCUsed to get leaderboard data on top players for a given Conflict Season. Note that for the current Conflict, leaderboard data will only be updated once per hour, or for individual players whenever that player makes a changes to staked Rebellion cards or packs.
Leaderboard data is limited to the top 200 players, but does also include a totals.total_reward_points field that indicates the total Airdrop Chances that have accumulated for all players participating in the given Conflict Season.
Examples:
Used to get an individual player’s leaderboard position for a given Conflict Season.
Examples:
Fetches several different pieces of information about current Conflict status for a given player. Let's look at examples of each piece of information:
config = bits of static config data:
conflict = info on the current Conflict Season (if any):
stats = player specific info about pack & wagon staking:
player = player specific contribution info for the current Conflict Season (if any):
wagons = a list of player owned Mage Wagons and cards staked on them (if any). If the player does not own any wagons, this will be an empty array []. The wagons array will always be sorted in total_cp DESC, wagon_uid ASC order:
Parameters:
The only_xxxx and exclude_xxxx parameters can be used to optimize query performance by eliminating unneeded information. If all 3 of wagons, player, and stats data are excluded, then the username parameter becomes optional.
Examples:
Note that if wagons data is included, then stats.total_wagon_cp will also be included, regardless of whether other stats are included or not.
Returns information about assets staked on one particular wagon. Format of the return data is the same as the wagons data for the conflicts/status API above, but with the addition of a player field to indicate wagon ownership. Has one required parameter: uid
Example: https://api.mavs-sl.com/conflicts/wagon?uid=I-326-1MXYYBYC4W
Returns information about cards that are eligible to be placed on a player’s Battle Wagons. These cards will meet the following criteria:
Parameters:
A grouping represents all card UIDs that have the same Collection Power, Card Detail ID, Gold, and BCX values. Note that even if max_group_size is used, a grouping’s qty field will be set to the total number of card UIDs that exist in that group. Groups will always have the following ordering: collection_power DESC, card_detail_id ASC, gold DESC, bcx DESC
Within a group, the list of card UIDs will be sorted in ascending alphabetical order.
Examples:
An optional parameter lore=1 exists for the following APIs:
This flag indicates that extra lore related fields should be included in Conflict Season data. If you don’t use it, then by default the following seasonal fields will not be included in API data:
There you have it. Any questions about the above APIs can be referred to myself. Happy coding!