Rebellion Conflicts APIs

avatar
(Edited)

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

Conflict Seasons

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.

cards/collection

cards/collection_by_card

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:

conflicts/seasons

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:

conflicts/players

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:

Notes about meaning of player data fields:

  • reward_point_threshold = how much reward progress must be made to earn a single Airdrop Chance
  • reward_points = this is the number of Airdrop Chances that have been earned by this player for the Conflict Season in question.
  • progress_to_next = how much reward progress has been made so far towards the next Airdrop Chance. When this reaches reward_point_threshold, it will reset to 0 and the player's reward_points will go up by 1
  • last_rp_update = timestamp of the last time a player's reward progress was saved to the back-end database. There is a Reward Point Updater process that will save data every hour. Data also gets updated whenever a player makes a change to cards or packs staked for Conflicts.
  • rp_per_hour = reward progress per hour; this is the sum total of Collection Power of a player's staked cards on all Mage Wagons + contribution from staked Rebellion packs. It indicates how much reward progress accrues towards the next Airdrop Chance every hour. For example, if reward_point_threshold = 100000 and rp_per_hour = 200000, then reward_points will increment by 2 for every hour that passes.

Alternative usage for multiple Conflict Seasons:

  • https://api.mavs-sl.com/conflicts/players?player=davemccoy&mode=all_conflicts - use the mode parameter to indicate you want data for a single player across all Conflict Seasons. This usage requires that player be set, and disallows all of the other optional parameters (except uids, see below). The sort order used is 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.

uids parameter:

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:

conflicts/airdrop_distribution

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:

Alternative usage for multiple Conflict Seasons:

conflicts/leaderboard

Used 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:

conflicts/leaderboard_with_player

Used to get an individual player’s leaderboard position for a given Conflict Season.

Examples:

conflicts/status

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:

  • username = player to fetch data for
  • only_xxxx = flag to indicate you only want 1 of the above types of data. Must be set to 1 if used.
  • exclude_xxxx = flag to indicate you want to exclude one of the above types of data. Must be set to 1 if used. Can have multiple exclusions.

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.

conflicts/wagon

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

conflicts/wagon_eligible_cards

Returns information about cards that are eligible to be placed on a player’s Battle Wagons. These cards will meet the following criteria:

  • Card Set is Rebellion
  • Card is not on the market
  • Card is not delegated / rented out
  • Card is not already staked on a Mage Wagon
  • Card is not staked on Land

Parameters:

  • username = player to fetch data for
  • max_group_size = integer >= 1 that represents the max number of card UIDs that should be returned for a given grouping. This is optional; if not included, then all card UIDs will be returned. You may wish to use this parameter to reduce the size of the return data, if the UIDs of the cards are not important for your use case.

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:

Including flavor text (lore) in Conflict Season data:

An optional parameter lore=1 exists for the following APIs:

  • conflicts/seasons
  • conflicts/players
  • conflicts/status
  • conflicts/airdrop_distribution

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:

  • title
  • sub_title
  • description
  • epilogue
  • url

And that's it!

There you have it. Any questions about the above APIs can be referred to myself. Happy coding!

splinterlands rebellion conflicts gaming api developer reference dev
0
0
0.000
3 comments
avatar

Great, thank you. I tested Conflict and it worked very smooth on Mavs

0
0
0.000
Reply
avatar

Extensive information, nice and thanks. I think i miss a few elementary ones though...

  1. Buy a wagon
  2. Assign a card or pack to a wagon
0
0
0.000
Reply