Jump to content

Data API: Difference between revisions

From Bconomy Wiki
← Older editNewer edit →

TheCarriedOne (talk | contribs)

4 user groups
1,270 edits
undo
VisualWikitext
No edit summary
Publish from docs/data-api.md
Line 1: Line 1:
The '''Data API''' is an official method of retrieving live game information from Bconomy. The fetched data is returned in a machine-readable format, allowing it to be used by third-party tools and integrations that respect the [[Guide:Getting Started#Follow the game rules|Game Rules]].
__TOC__


==API key==
The Data API is Bconomy's official HTTP interface for reading live game data as JSON. Third-party tools may use it as long as they follow the [https://bconomy.net Game Rules].
An API key is required when accessing the Data API to prevent abuse and allow access of sensitive information. This key must be included in every call to the API to authenticate your client.


You can complete the following steps to generate an API key:
== Getting an API key ==


# Access the [https://bconomy.net/play Web Client], making sure you are logged in with your primary Bconomy account.
# Open the [https://bconomy.net/play Web Client], signed in with your main Bconomy account.
# Open your Console and run command <code>/resetapikey</code> to generate a new API key.
# Run <code><nowiki>/resetapikey</nowiki></code> in the Console. Running it again replaces your key, so any tool using the old key stops working.
## '''NOTE: If you have an existing API key, running this command will invalidate it!'''
# Copy the key. It is shown only once. You may be asked to complete a verification step first.
## You may be asked to complete some verification steps before an API key can be produced.
# Save your API key, as it won't be displayed again.


API keys should never be shared! They may allow access to sensitive information, and abuse by other parties could lead to your account being terminated. Treat it like a password and store it somewhere secure.
Treat the key like a password. Anyone holding it can read anything your account can, and their requests count against your rate limit.


==Specification==
== Quick start ==
The Data API endpoint is located at <code><nowiki>https://bconomy.net/api/data</nowiki></code> and can be consumed as a REST API. It accepts HTTP POST requests and returns structured data in JSON format. All POST requests to this endpoint must include an API key (provided in the <code>x-api-key</code> request header) and a query payload that specifies the data to be returned (provided in the request body as JSON).


A rate limit is in place; up to 120 requests can be executed per minute before access is limited. The API is not versioned and the structure of returned data may change without notice.
Send a <code><nowiki>POST</nowiki></code> to <code><nowiki>https://bconomy.net/api/data</nowiki></code> with your key in the <code><nowiki>x-api-key</nowiki></code> header and a JSON body naming the query in <code><nowiki>type</nowiki></code>:


===Example===
<pre>const res = await fetch("https://bconomy.net/api/data", {
Making an API call using JavaScript:
<pre>
// Fetch raw data for Pet with ID#1
const rawData = await fetch("https://bconomy.net/api/data", {
   method: "POST",
   method: "POST",
   headers: {
   headers: { "Content-Type": "application/json", "x-api-key": MY_KEY },
    "Content-Type": "application/json",
   body: JSON.stringify({ type: "pets/pet", id: 1 }),
    "x-api-key": process.env.MY_BCONOMY_API_KEY,
  },
   body: JSON.stringify({ type: "pet", id: 1 }),
});
});
const pet = await res.json();</pre>


// Parse raw data into JSON object
The response is the requested data itself, with no wrapper. For <code><nowiki>pets/pet</nowiki></code> that is a single [[Data API/Types#Pet|<code><nowiki>Pet</nowiki></code>]] object.
const parsedData = await rawData.json();


// Display parsed, fetched data
== Conventions ==
console.log(parsedData);
</pre>
The following data is returned:
<pre>
{
  "id": 1,
  "ownerBcId": 1,
  "hatchDate": "2021-02-05T04:03:26.000Z",
  "name": "Genesis",
  "tier": 3,
  "xp": 14393909664,
  "species": "goose",
  "generation": 1,
  "parentAId": null,
  "parentBId": null,
  "timesBred": 5,
  "lastBred": "2025-05-04T06:19:29.000Z",
  "heldItemId": null,
  "unsyncedEnergy": 342000000,
  "adventureType": "fish",
  "adventureBoost": { "multiplier": 4, "endTime": 1750789954828 },
  "lastAdventureSync": "2025-07-01T19:18:09.000Z",
  "lifetimeItemsFound": 531526205,
  "craving": { "itemId": 71, "amount": 5415 },
  "skin": "gamma",
  "aura": "cyan"
}
</pre>


==Payload structure==
{| class="wikitable"
The query payload and returned data for all Data API requests are identical in structure to those present in <code>dataFetch</code> messages in WebSocket connections established by the Web Client.
|-
! Topic
! Rule
|-
| Endpoint
| <code><nowiki>POST https://bconomy.net/api/data</nowiki></code>
|-
| Authentication
| <code><nowiki>x-api-key</nowiki></code> header on every request
|-
| Query
| <code><nowiki>type</nowiki></code> field in the JSON body, written as <code><nowiki>area/name</nowiki></code> (for example <code><nowiki>market/listings</nowiki></code>); other fields are that query's parameters
|-
| IDs
| <code><nowiki>id</nowiki></code> is a BcID for player queries and the object's own ID for pets, eggs and factions; each endpoint says which
|-
| Dates
| Fields documented as ISO 8601 are strings; fields documented as Unix ms are numbers of milliseconds since 1970
|-
| Pagination
| <code><nowiki>page</nowiki></code> is 1-based; <code><nowiki>pageSize</nowiki></code> is optional unless an endpoint says otherwise
|-
| Large numbers
| Some totals can exceed <code><nowiki>Number.MAX_SAFE_INTEGER</nowiki></code> and lose precision in JavaScript; those fields are marked
|-
| Rate limit
| 120 requests per minute, counted per IP address and per BcID; heavy API use also slows your own Web Client
|-
| Versioning
| None. Fields can be added, changed or removed without notice
|}


Two type string formats are accepted interchangeably. This page uses the canonical namespaced format; see [[#Legacy type aliases|§ Legacy type aliases]] for the mapping from the old flat names that pre-existing code may use.
=== Errors ===


===Common types===
Errors return a JSON body of <code><nowiki>{ "error": string }</nowiki></code>:
These types are referenced throughout the table below.


====User====
{| class="wikitable"
The full <code>User</code> object returned by several endpoints. Key fields:
|-
<pre>
! Status
{
! Meaning
  "id": 1,                        // BcID
|-
  "name": "Alice",
| <code><nowiki>400</nowiki></code>
  "registrationDate": "2021-01-01T00:00:00.000Z",
| The game rejected the request, for example when you are over the rate limit. <code><nowiki>error</nowiki></code> explains why
  "rank": 50,
|-
  "tier": 3,
| <code><nowiki>403</nowiki></code>
  "bc": 1000000,                  // BC balance
| The query type exists but is not available through the HTTP API
  "sp": 200,                       // store points
|-
  "kr": 5,                         // karma
| <code><nowiki>500</nowiki></code>
  "buddyId": null,
| Anything else, including a missing or invalid key, an unknown <code><nowiki>type</nowiki></code>, or invalid parameters
  "factionId": 2,
|}
  "factionTag": "ALPH",
  "factionJoinDate": "2022-06-01T00:00:00.000Z",
  "factionDepositWeekly": 5000,
  "factionDepositTotal": 120000,
  "questLevel": 47,
  "questLevelClaimed": 46,
  "dailyClaimStreak": 30,
  "petsBredDaily": 0,
  "farmPlots": [
    { "level": 2, "status": { "isPlanted": false }, "boost": { "multiplier": 1, "endTime": 0 }, "isExtra": false }
  ],
  "generators": [ { "level": 1, "isExtra": false } ],
  "quests": [ { "itemId": 5, "amountRequired": 500, "amountFulfilled": 200 } ],
  "cooldowns": { "fish": 0, "hunt": 1751000000000, "explore": 0, "mine": 0, "work": 0, "daily": 0, "water": 0, "claimGenerators": 0, "setBuddy": 0, "buddyBossAttack": 0, "resetPerks": 0, "eternalsnowflakeUse": 0 },
  "effects": {},
  "upgrades": { "fish": 3, "fishExtra": 0, "hunt": 1, "huntExtra": 0, "explore": 1, "exploreExtra": 0, "mine": 1, "mineExtra": 0, "petsStable": 2, "petsStableExtra": 0 },
  "augments": [],
  "equippedFlatInventory": {},
  "perks": {},
  "pinnedItemIds": [],
  "pinnedPetIds": [],
  "autosellLimits": {},
  "itemReserveAmounts": {},
  "settings": { "profileShowStatId": null, "title": null, "syncDiscordName": true, "publicDiscordProfile": true, "discordPingOnResponse": true, "petsBulkFeedFoundItemsFirst": true, "petsBulkFeedCravingsOnly": false, "aggregateBulkOutput": true },
  "custom": { "profileHideAvatar": false, "profileHideTitleName": false, "profileUseChatEmblemEmoji": false, "profileBackground": null, "chatEmblemEmoji": null, "chatUsernameColor": null, "chatUsernameStyle": null, "chatMessageBackgroundColor": null },
  "discordServerIds": [],
  "blockedBcIds": [],
  "banExpiryDate": "1970-01-01T00:00:00.000Z",
  "premiumExpiryDate": null
}
</pre>


====Pet====
== Endpoints ==
<pre>
{
  "id": 1,
  "ownerBcId": 1,            // null for wild pets
  "hatchDate": "2021-02-05T04:03:26.000Z",
  "name": "Genesis",
  "tier": 3,
  "xp": 14393909664,
  "species": "goose",        // see §Enumerations
  "generation": 1,
  "parentAId": null,
  "parentBId": null,
  "timesBred": 5,
  "lastBred": "2025-05-04T06:19:29.000Z",
  "heldItemId": null,
  "unsyncedEnergy": 342000000,
  "adventureType": "fish",  // "fish" | "hunt" | "explore" | "mine" | null
  "adventureBoost": { "multiplier": 4, "endTime": 1750789954828 },
  "lastAdventureSync": "2025-07-01T19:18:09.000Z",
  "lifetimeItemsFound": 531526205,
  "craving": { "itemId": 71, "amount": 5415 },
  "skin": "gamma",          // see §Enumerations; null if no skin
  "aura": "cyan"            // see §Enumerations; null if no aura
}
</pre>


====Egg====
Each endpoint page lists the request, the response and any limits. Shared shapes such as <code>User</code> and <code>Pet</code> are on [[Data API/Types|Types]].
<pre>
{
  "id": 1,
  "ownerBcId": 1,              // null for abandoned eggs
  "parentAId": 12,
  "parentBId": 34,
  "parentAHeldItemId": null,
  "parentBHeldItemId": 5
}
</pre>


====Faction====
{| class="wikitable"
<pre>
|-
{
! Query
  "id": 1,
! Returns
  "tag": "ALPH",
|-
  "name": "Alpha",
! colspan="2" | [[Data API/Profile|Profile]]
  "ownerBcId": 1,
|-
  "rankOverrides": {},
| [[Data API/Profile#user/profile|<code><nowiki>user/profile</nowiki></code>]]
  "isRecruiting": true,
| Returns a single user's full public profile, enriched with inventory, faction, linked Discord info (if public), and BCS roles.
  "about": "We are recruiting!",
|-
  "motd": "Good luck today",
| [[Data API/Profile#user/get|<code><nowiki>user/get</nowiki></code>]]
  "unsyncedFp": 0,
| Returns the core [[Data API/Types#User|<code><nowiki>User</nowiki></code>]] object.
  "lastFpSync": "2025-07-01T00:00:00.000Z",
|-
  "boostSteps": {
| [[Data API/Profile#user/lbPositions|<code><nowiki>user/lbPositions</nowiki></code>]]
    "fish":    { "lastChange": 1750000000000, "amount": 2 },
| Returns a user's leaderboard positions, scoped to that profile's own type (main / ironman / hardcore rank among their own kind only).
    "hunt":    { "lastChange": 0, "amount": 0 },
|-
    "explore": { "lastChange": 0, "amount": 0 },
| [[Data API/Profile#user/inventory|<code><nowiki>user/inventory</nowiki></code>]]
    "mine":    { "lastChange": 0, "amount": 0 }
| Returns the inventory of a user.
  },
|-
  "halls": 3,
| [[Data API/Profile#stats/user|<code><nowiki>stats/user</nowiki></code>]]
  "fpDepositedMonthly": 50000,
| Returns all tracked lifetime and periodic statistics for a user.
  "fpDepositedTotal": 1200000,
|-
  "customizationSettings": { "emblemEmoji": null, "tagColor": null, "nameColor": null, "nameStyle": null },
| [[Data API/Profile#stats/trophies|<code><nowiki>stats/trophies</nowiki></code>]]
  "ownerPremiumExpiryDate": null,
| Returns the trophy record for a user.
  "memberCount": 12,
|-
  "pendingRequests": 2
| [[Data API/Profile#user/otherProfiles|<code><nowiki>user/otherProfiles</nowiki></code>]]
}
| Returns public summary information for other profiles belonging to the same account as the requested profile.
</pre>
|-
 
| [[Data API/Profile#stats/userWindowed|<code><nowiki>stats/userWindowed</nowiki></code>]]
====Inventory====
| Returns time-windowed statistics for a user across multiple aggregation buckets.
A JSON object where keys are item <code>idName</code> strings and values are the owned quantity (positive integer). Only items owned in non-zero amounts are present.
<pre>
{ "rocks": 500, "wood": 120, "lunarShard": 3 }
</pre>
 
====LeaderboardPage====
Envelope returned by all leaderboard endpoints. <code>T</code> is [[#Faction|<code>Faction</code>]] for the faction board, [[#Pet|<code>Pet</code>]] for the pet board, or LeaderboardUser (a slimmer object, see below) for user stat/rank boards.
<pre>
{
  "data": [ /* array of T */ ],
  "total": 4200,          // total entries across all pages
  "pageSize": 50,
  "lastUpdated": 1751000000000,  // Unix ms of last cache refresh
  "ownEntry": {            // requesting user's entry + 1-based rank, or null if not on board; omitted for some lbTypes
    /* T fields... */
    "rank": 14
  }
}
</pre>
The <code>data</code> entries for user leaderboards (<code>stats/userLeaderboard</code>) are <b>LeaderboardUser</b> objects:
<pre>
{
  "id": 1,                    // BcID
  "name": "Alice",
  "custom": { /* User.custom fields */ },
  "premiumExpiryDate": null,
  "lbValue": 999999,          // primary sort value (may exceed MAX_SAFE_INTEGER)
  "secondaryLbValue": 500      // optional secondary sort value
}
</pre>
 
====GameLogResponse====
<pre>
{
  "entries": [ /* GameLog[] */ ],
  "refs": {
    "profiles":  { "1": { /* User */ } },  // keyed by BcID
    "factions":  { "2": { /* Faction */ } },
    "pets":      { "5": { /* Pet */ } }
  },
  "total": 310,
  "pageSize": 50,
  "page": 1
}
</pre>
Each <b>GameLog</b> entry:
<pre>
{
  "id": 1,
  "date": "2025-07-01T12:00:00.000Z",
  "senderBcId": 1,
  "recipientBcId": null,
  "factionId": null,
  "itemId": 5,
  "type": "marketItemTransaction",  // see §Enumerations
  "data": {
    "amount": 10,
    "listingPrice": 500
    // other optional fields: ballPitType, newFactionRank, action, petId, eggId, special
  }
}
</pre>
 
====MarketListing====
<pre>
{ "id": 1, "bcId": 1, "itemId": 5, "price": 500, "amount": 10 }
</pre>
 
====MarketActivityEntry====
<pre>
{
  "itemId": 5,
  "itemName": "Lunar Shard",
  "itemEmoji": "🌙",
  "type": "buy",              // "buy" | "list" | "delist"
  "actorBcId": 1,
  "actorName": "Alice",
  "amount": 5,
  "price": 1000,
  "date": "2025-07-01T12:00:00.000Z"
}
</pre>
 
===Enumerations===
<div style="overflow-x:auto;">
{| class="wikitable" style="width:100%"
!Name!!Values
|-
|-
|Pet species (base)||<code>poodle</code> <code>dog</code> <code>bat</code> <code>mustang</code> <code>pig</code> <code>eagle</code> <code>otter</code> <code>tiger</code> <code>peacock</code> <code>donkey</code> <code>gorilla</code> <code>ox</code> <code>junglefowl</code> <code>crocodile</code> <code>goose</code> <code>rat</code> <code>seal</code> <code>whale</code> <code>rabbit</code> <code>dove</code> <code>kangaroo</code> <code>snake</code> <code>turtle</code> <code>snail</code> <code>dolphin</code> <code>lizard</code> <code>scorpion</code> <code>owl</code> <code>cockroach</code>
| [[Data API/Profile#stats/burnOdds|<code><nowiki>stats/burnOdds</nowiki></code>]]
| Returns daily and weekly first-draw Burn odds for a user in their profile mode, using all eligible positive burns, with no leaderboard page cutoff.
|-
|-
|Pet species (supporter)||<code>dragon</code> <code>phoenix</code> <code>visitor</code> <code>invader</code> <code>sauropod</code> <code>tyrannosaurus</code> <code>jack</code> <code>ghost</code> <code>snowman</code>
! colspan="2" | [[Data API/Pets|Pets]]
|-
|-
|Pet skin||Base: <code>alpha</code> <code>beta</code> <code>gamma</code> <code>delta</code> <code>epsilon</code> <code>zeta</code> <code>eta</code> — Unique: <code>sunkissed</code> <code>grayscale</code> <code>whiteout</code>
| [[Data API/Pets#pets/pet|<code><nowiki>pets/pet</nowiki></code>]]
| Returns a single pet.
|-
|-
|Pet aura||<code>green</code> <code>purple</code> <code>orange</code> <code>cyan</code> <code>red</code> <code>pink</code> <code>blue</code> <code>yellow</code> <code>black</code>
| [[Data API/Pets#pets/egg|<code><nowiki>pets/egg</nowiki></code>]]
| Returns a single egg.
|-
|-
|GameLogType||<code>itemFind</code> <code>ballPitWin</code> <code>marketItemTransaction</code> <code>tradeItemTransaction</code> <code>tradeBcTransaction</code> <code>factionJoin</code> <code>factionCreate</code> <code>factionDelete</code> <code>factionDemote</code> <code>factionPromote</code> <code>factionTransfer</code> <code>factionVaultDeposit</code> <code>factionVaultUpgrade</code> <code>factionKick</code> <code>factionLeave</code> <code>factionIncreaseBoost</code> <code>factionDecreaseBoost</code> <code>lbReceiveItemReward</code> <code>lbReceiveSpecialReward</code> <code>bossReceiveItemReward</code> <code>bossReceiveSpecialReward</code> <code>eggCreate</code> <code>eggAbandon</code> <code>eggTransfer</code> <code>eggLocate</code> <code>eggHatch</code> <code>petTransfer</code> <code>petRelease</code> <code>specialUse</code> <code>specialFind</code> <code>giveawayItemTransfer</code> <code>supportGrantItem</code> <code>marketListingCreated</code> <code>marketListingDelisted</code>
| [[Data API/Pets#pets/userPetsAndEggs|<code><nowiki>pets/userPetsAndEggs</nowiki></code>]]
| Returns pets and eggs owned by a user.
|-
|-
|UserLeaderboardType||<code>wallet</code> <code>inventoryWorth</code> <code>rank</code> <code>questLevel</code> <code>streak</code> <code>stat</code> <code>item</code> <code>trophy</code>
| [[Data API/Pets#pets/offspring|<code><nowiki>pets/offspring</nowiki></code>]]
|}
| Returns all pets and eggs that have the specified pet as a parent.
</div>
 
===Query reference===
<div style="overflow-x:auto;">
{| class="wikitable" style="width:100%"
!Query
!Request body
!Response
!Notes
|-
|-
| colspan="4" | '''Profile'''
| [[Data API/Pets#pets/leaderboard|<code><nowiki>pets/leaderboard</nowiki></code>]]
|- style="vertical-align:top"
| Returns a paginated page of the pets leaderboard (sorted by lifetime items found descending).
|Profile
|<pre>{ "type": "user/profile", "id": 1 }</pre>
|[[#User|<code>User</code>]] extended with <code>bcsRoles</code>, [[#Inventory|<code>Inventory</code>]], optional [[#Faction|<code>Faction</code>]], <code>lbPositions</code>, optional <code>displayStatValue</code>, and optional Discord fields
|<code>bcsRoles</code>: array of <code>"moderator"</code>, <code>"developer"</code>, <code>"inactiveModerator"</code>. Discord fields only present when the user has set <code>publicDiscordProfile: true</code>. <code>lbPositions</code> is a record of leaderboard type to 1-based rank.
|- style="vertical-align:top"
|User
|<pre>{ "type": "user/get", "id": 1 }</pre>
|[[#User|<code>User</code>]]
|
|- style="vertical-align:top"
|Inventory
|<pre>{ "type": "user/inventory", "id": 1 }</pre>
|[[#Inventory|<code>Inventory</code>]]
|Keys are item <code>idName</code> strings. Only non-zero amounts included.
|- style="vertical-align:top"
|Stats
|<pre>{ "type": "stats/user", "id": 1 }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{
  "bcId": 1,
  "incomeDaily": 0, "incomeWeekly": 0, "incomeTotal": 0,
  "timesFished": 0, "timesHunted": 0, "timesExplored": 0,
  "timesMined": 0,  "timesWorked": 0,
  "itemsFound": 0, "rareItemsFound": 0,
  "itemsCrafted": 0, "itemsHarvested": 0, "timesWatered": 0,
  "bcEarnedFromGens": 0,
  "petItemsFound": 0, "petItemsFed": 0, "petsBred": 0,
  "questsCompleted": 0, "fpContributed": 0,
  "timesPlayedCoinflip": 0,
  "netCoinflipProfitDaily": 0, "netCoinflipProfitWeekly": 0, "netCoinflipProfitTotal": 0,
  "bcBurnedDaily": 0, "bcBurnedWeekly": 0, "bcBurnedTotal": 0,
  "bossDamage": 0,
  "marketListingsSold": 0, "marketListingsRevenue": 0,
  "netBallPitProfit": 0,
  "museumCollectiblesFound": 0,
  "globalBoostsUsed": 0, "worthGivenAway": 0
}</pre></div>
|<code>bossDamage</code> and <code>marketListingsRevenue</code> can exceed <code>Number.MAX_SAFE_INTEGER</code> for high-activity users.
|- style="vertical-align:top"
|Trophies
|<pre>{ "type": "stats/trophies", "id": 1 }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{
  "bcId": 1,
  "trophyRecord": {
    "topDayIncome": { "count": 3, "timeFirstAchieved": 1700000000000 }
  }
}</pre></div>
|<code>trophyRecord</code> is a partial record; unearned trophies are absent.
|-
|-
| colspan="4" | '''Pets'''
! colspan="2" | [[Data API/Menagerie|Menagerie]]
|- style="vertical-align:top"
|Pet
|<pre>{ "type": "pets/pet", "id": 1 }</pre>
|[[#Pet|<code>Pet</code>]]
|
|- style="vertical-align:top"
|Egg
|<pre>{ "type": "pets/egg", "id": 1 }</pre>
|[[#Egg|<code>Egg</code>]]
|
|- style="vertical-align:top"
|Owned
|<pre>{ "type": "pets/userPetsAndEggs", "id": 1 }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{ "pets": [ /* Pet[] */ ], "eggs": [ /* Egg[] */ ] }</pre></div>
|Returns all Pets and Eggs whose owner is the provided BcID.
|- style="vertical-align:top"
|Offspring
|<pre>{ "type": "pets/offspring", "id": 1 }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{ "eggs": [ /* Egg[] */ ], "pets": [ /* Pet[] */ ] }</pre></div>
|Returns all Eggs and Pets that have the provided Pet ID as a parent.
|- style="vertical-align:top"
|Leaderboard
|<pre>{
  "type": "pets/leaderboard",
  "page": 1,
  "pageSize": 50
}</pre>
|[[#LeaderboardPage|<code>LeaderboardPage</code>]]&lt;[[#Pet|<code>Pet</code>]]&gt;
|<code>pageSize</code> is optional (defaults to server value). Sorted by tier then XP descending.
|-
|-
| colspan="4" | '''Factions'''
| [[Data API/Menagerie#menagerie/get|<code><nowiki>menagerie/get</nowiki></code>]]
|- style="vertical-align:top"
| Returns a user's menagerie collection, unlocked variants, and active animal status.
|Faction
|<pre>{ "type": "factions/get", "id": 1 }</pre>
|[[#Faction|<code>Faction</code>]]
|
|- style="vertical-align:top"
|Members
|<pre>{ "type": "factions/members", "id": 1 }</pre>
|[[#User|<code>User</code>]][]
|Returns all Users that belong to the supplied Faction ID.
|- style="vertical-align:top"
|Recruiting
|<pre>{ "type": "factions/recruiting" }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{ "lastUpdated": 1751000000000, "data": [ /* Faction[] */ ] }</pre></div>
|Returns all Factions that are recruiting, below max member count, and below max pending requests. Cached; refreshes approximately every 15 minutes.
|- style="vertical-align:top"
|Join requests
|<pre>{
  "type": "factions/joinRequests",
  "idType": "factionId",
  "id": 1
}</pre>
|<div class="mw-collapsible mw-collapsed"><pre>[{
  "id": 1,
  "bcId": 5,
  "factionId": 1,
  "reason": "I want to join!",
  "date": "2025-07-01T00:00:00.000Z"
}]</pre></div>
|<code>idType</code>: <code>"factionId"</code> returns requests sent '''to''' the faction; <code>"bcId"</code> returns requests sent '''by''' that user.
|- style="vertical-align:top"
|Leaderboard
|<pre>{
  "type": "factions/leaderboard",
  "stat": "fpDepositedMonthly",
  "page": 1,
  "pageSize": 50
}</pre>
|[[#LeaderboardPage|<code>LeaderboardPage</code>]]&lt;[[#Faction|<code>Faction</code>]]&gt;
|<code>stat</code>: <code>"fpDepositedMonthly"</code> or <code>"fpDepositedTotal"</code>. <code>pageSize</code> is optional.
|-
|-
| colspan="4" | '''Market'''
| [[Data API/Menagerie#menagerie/leaderboard|<code><nowiki>menagerie/leaderboard</nowiki></code>]]
|- style="vertical-align:top"
| Returns a paginated page of the menagerie collection leaderboard.
|Preview
|<pre>{ "type": "market/preview" }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{
  "lastUpdated": 1751000000000,
  "data": {
    "lunarShard": {
      "price": 1000,
      "delta": { "day": 5.2, "week": -1.1, "month": null }
    }
  }
}</pre></div>
|Keyed by item <code>idName</code>. <code>price</code> absent if no active listings. <code>delta</code> values are percentage changes vs that period; <code>null</code> if no historical data. Cached ~5 minutes.
|- style="vertical-align:top"
|Listings (item)
|<pre>{ "type": "market/listings", "itemId": 5 }</pre>
|[[#MarketListing|<code>MarketListing</code>]][]
|Returns up to 50 active listings for the item, sorted by price ascending.
|- style="vertical-align:top"
|Listings (user)
|<pre>{ "type": "market/userListings", "id": 1 }</pre>
|[[#MarketListing|<code>MarketListing</code>]][]
|Returns all active listings created by the provided BcID.
|- style="vertical-align:top"
|Global recent activity
|<pre>{ "type": "market/globalRecentActivity" }</pre>
|[[#MarketActivityEntry|<code>MarketActivityEntry</code>]][]
|Last 20 transactions (buys, listings, delistings) across all items. Cached 10 seconds.
|- style="vertical-align:top"
|Recent transactions (item)
|<pre>{ "type": "market/recentTransactions", "itemId": 5 }</pre>
|[[#MarketActivityEntry|<code>MarketActivityEntry</code>]][]
|Last 5 transactions for a specific item.
|- style="vertical-align:top"
|Price history
|<pre>{
  "type": "market/priceHistory",
  "itemId": 5,
  "days": 30
}</pre>
|<div class="mw-collapsible mw-collapsed"><pre>[{
  "id": 1,
  "snapshotTime": "2025-06-01T00:00:00.000Z",
  "itemId": 5,
  "lowestPrice": 980
}]</pre></div>
|Sorted ascending by <code>snapshotTime</code>. <code>lowestPrice</code> is <code>null</code> if no listings existed at snapshot time. Optional filters: <code>days</code> (integer, days back from now), or <code>fromMs</code> / <code>toMs</code> (Unix ms range).
|- style="vertical-align:top"
|Volume history
|<pre>{
  "type": "market/volumeHistory",
  "itemId": 5,
  "granularity": "day",
  "days": 30
}</pre>
|<div class="mw-collapsible mw-collapsed"><pre>[{
  "id": 1,
  "granularity": "day",
  "windowStart": "2025-06-01T00:00:00.000Z",
  "windowEnd": "2025-06-02T00:00:00.000Z",
  "itemId": 5,
  "unitsSold": 1200,
  "totalRevenue": 1440000,
  "transactionCount": 48
}]</pre></div>
|<code>granularity</code>: <code>"hour"</code>, <code>"day"</code>, or <code>"month"</code>. <code>days</code> is optional (max 400). <code>unitsSold</code> and <code>totalRevenue</code> can exceed <code>MAX_SAFE_INTEGER</code> for popular items.
|-
|-
| colspan="4" | '''Leaderboards (user)'''
! colspan="2" | [[Data API/Factions|Factions]]
|- style="vertical-align:top"
|User leaderboard
|<pre>{
  "type": "stats/userLeaderboard",
  "lbType": "rank",
  "page": 1,
  "pageSize": 50
}</pre>
|[[#LeaderboardPage|<code>LeaderboardPage</code>]]&lt;LeaderboardUser&gt;
|<code>lbType</code> determines the ranking. Some types require an additional field:
* <code>"wallet"</code> — BC balance; no extra field
* <code>"inventoryWorth"</code> — inventory value; no extra field
* <code>"rank"</code> — rank number; no extra field
* <code>"questLevel"</code> — quest level; no extra field
* <code>"streak"</code> — daily claim streak; no extra field
* <code>"stat"</code> — requires <code>"stat"</code>: a key from the stats object (e.g. <code>"timesFished"</code>, <code>"marketListingsRevenue"</code>)
* <code>"item"</code> — requires <code>"itemId"</code>: item ID to rank by amount owned
* <code>"trophy"</code> — requires <code>"trophyId"</code>: trophy ID to rank by count
|-
|-
| colspan="4" | <span id="Logs">'''Logs'''</span>
| [[Data API/Factions#factions/get|<code><nowiki>factions/get</nowiki></code>]]
|- style="vertical-align:top"
| Returns a single faction.
|By BcID
|<pre>{
  "type": "logs/byBcId",
  "id": 1,
  "page": 1,
  "pageSize": 50
}</pre>
|[[#GameLogResponse|<code>GameLogResponse</code>]]
|Returns logs where the user is sender or recipient. Non-moderators are limited to a maximum number of pages.
|- style="vertical-align:top"
|By ID type
|<pre>{
  "type": "logs/byIdType",
  "idType": "factionId",
  "id": 1,
  "page": 1,
  "pageSize": 50
}</pre>
|[[#GameLogResponse|<code>GameLogResponse</code>]]
|<code>idType</code>: <code>"factionId"</code> or <code>"itemId"</code>. Non-moderators are limited to a maximum number of pages.
|- style="vertical-align:top"
|By log type
|<pre>{
  "type": "logs/byLogType",
  "logType": "marketItemTransaction",
  "page": 1,
  "pageSize": 50
}</pre>
|[[#GameLogResponse|<code>GameLogResponse</code>]]
|See [[#Enumerations|<code>GameLogType</code>]] for all valid <code>logType</code> values. Non-moderators are limited to a maximum number of pages.
|- style="vertical-align:top"
|Daily inputs
|<pre>{
  "type": "misc/dailyInputs",
  "id": 1,
  "date": "2025-07-01"
}</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{
  "day": "2025-07-01",
  "data": [
    { "time": 1751380800000, "input": { "type": "fish/cast", ... } }
  ]
}</pre></div>
|Returns all commands executed by the user on <code>date</code>. <code>date</code> accepts ISO date strings, <code>YYYY/MM/DD</code>, or a Unix timestamp. Records available for the previous 30-day period only.
|-
|-
| colspan="4" | '''Game Data'''
| [[Data API/Factions#factions/members|<code><nowiki>factions/members</nowiki></code>]]
|- style="vertical-align:top"
| Returns all users that belong to a faction.
|Items
|<pre>{ "type": "misc/itemData" }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>[{
  "id": 5,
  "imageUrl": "https://assets.bconomy.net/items/lunarShard.webp",
  "recipe": [["rocks", 10], ["wood", 5]],
  /* ...plus all other item fields */
}]</pre></div>
|Static data for all game items. <code>recipe</code> is an array of <code>[idName, amount]</code> tuples.
|- style="vertical-align:top"
|Game state
|<pre>{ "type": "misc/gameState" }</pre>
|<div class="mw-collapsible mw-collapsed"><pre>{
  "globalActionBoosts": [{
    "type": "baseGlobalActionBoost",
    "user": { /* User */ },
    "action": "fish",
    "multiplier": 2,
    "duration": 3600000,
    "endTime": 1751000000000
  }],
  "lastGlobalActionCooldownResetTime": 1750996400000,
  "activeBossStatus": {
    "lastUpdated": 1751000000000,
    "data": {
      "bossId": "leviathan",
      "startTime": 1750990000000,
      "initialHealth": 1000000,
      "weaknessItemIds": [5, 12],
      "numAttackingUsers": 42,
      "damageDealt": 350000,
      "nextWeakpointRevealAt": null
    }
  },
  "ballPitStatus": { "type": "blue", "balls": 124 },
  "activeGiveaways": []
}</pre></div>
|<code>activeBossStatus</code> is <code>null</code> when no boss is active.
|- style="vertical-align:top"
|Balls owned
|<pre>{ "type": "misc/userBallsOwned" }</pre>
|number
|Returns the ball pit ball count for the '''authenticated user''' (identified by the API key). No <code>id</code> parameter is accepted.
|-
|-
| colspan="4" | '''Search'''
| [[Data API/Factions#factions/recruiting|<code><nowiki>factions/recruiting</nowiki></code>]]
|- style="vertical-align:top"
| Returns recruiting factions of the viewer's profile type with an open member spot and at least one FP-funded active boost.
|Users
|<pre>{ "type": "search/users", "query": "alice" }</pre>
|[[#User|<code>User</code>]][]
|Returns users whose name matches the query. Maximum 20 results.
|- style="vertical-align:top"
|Factions
|<pre>{ "type": "search/factions", "query": "alpha" }</pre>
|[[#Faction|<code>Faction</code>]][]
|Returns factions whose name matches the query. Maximum 20 results.
|- style="vertical-align:top"
|Pets
|<pre>{
  "type": "search/pets",
  "skin": "gamma",
  "aura": "any aura",
  "species": "goose",
  "rawNameQuery": "genesis"
}</pre>
|[[#Pet|<code>Pet</code>]][]
|All four fields are required. Use <code>"any skin"</code> / <code>"any aura"</code> / <code>"any species"</code> to match any value, or <code>"no skin"</code> / <code>"no aura"</code> to match pets without one. Empty string for <code>rawNameQuery</code> matches all names. Maximum 20 results, sorted by tier then XP descending.
|}
</div>
 
===Legacy type aliases===
Both the canonical namespaced type and the legacy alias are accepted in any request.
<div style="overflow-x:auto;">
{| class="wikitable mw-collapsible mw-collapsed" style="width:100%"
|+Legacy aliases
!Legacy type!!Canonical type
|-
|-
|<code>faction</code>||<code>factions/get</code>
| [[Data API/Factions#factions/joinRequests|<code><nowiki>factions/joinRequests</nowiki></code>]]
| Returns faction join requests filtered by either faction or user.
|-
|-
|<code>factionJoinRequests</code>||<code>factions/joinRequests</code>
| [[Data API/Factions#factions/leaderboard|<code><nowiki>factions/leaderboard</nowiki></code>]]
| Returns a paginated page of the faction leaderboard.
|-
|-
|<code>factionLeaderboard</code>||<code>factions/leaderboard</code>
! colspan="2" | [[Data API/Market|Market]]
|-
|-
|<code>factionMembers</code>||<code>factions/members</code>
| [[Data API/Market#market/preview|<code><nowiki>market/preview</nowiki></code>]]
| Returns the current lowest listing price and price delta for every item.
|-
|-
|<code>recruitingFactions</code>||<code>factions/recruiting</code>
| [[Data API/Market#market/listings|<code><nowiki>market/listings</nowiki></code>]]
| Returns up to 50 active market listings for an item, sorted by price ascending.
|-
|-
|<code>richLogsByBcId</code>||<code>logs/byBcId</code>
| [[Data API/Market#market/userListings|<code><nowiki>market/userListings</nowiki></code>]]
| Returns all active market listings created by a user.
|-
|-
|<code>richLogsByIdType</code>||<code>logs/byIdType</code>
| [[Data API/Market#market/globalRecentActivity|<code><nowiki>market/globalRecentActivity</nowiki></code>]]
| Returns the last 20 market transactions (buys, listings, and delistings) across all items.
|-
|-
|<code>richLogsByLogType</code>||<code>logs/byLogType</code>
| [[Data API/Market#market/recentTransactions|<code><nowiki>market/recentTransactions</nowiki></code>]]
| Returns the last 5 market transactions for a specific item.
|-
|-
|<code>marketGlobalRecentActivity</code>||<code>market/globalRecentActivity</code>
| [[Data API/Market#market/priceHistory|<code><nowiki>market/priceHistory</nowiki></code>]]
| Returns historical lowest-price snapshots for an item.
|-
|-
|<code>marketListings</code>||<code>market/listings</code>
| [[Data API/Market#market/volumeHistory|<code><nowiki>market/volumeHistory</nowiki></code>]]
| Returns aggregated trade volume history for an item.
|-
|-
|<code>marketPreview</code>||<code>market/preview</code>
! colspan="2" | [[Data API/Leaderboards|Leaderboards]]
|-
|-
|<code>marketPriceHistory</code>||<code>market/priceHistory</code>
| [[Data API/Leaderboards#stats/userLeaderboard|<code><nowiki>stats/userLeaderboard</nowiki></code>]]
| Returns a paginated page of the user leaderboard.
|-
|-
|<code>marketRecentTransactions</code>||<code>market/recentTransactions</code>
| [[Data API/Leaderboards#stats/hoarderLeaderboard|<code><nowiki>stats/hoarderLeaderboard</nowiki></code>]]
| Returns players ranked by hoarder trophy size (count of item-collector trophies held).
|-
|-
|<code>userMarketListings</code>||<code>market/userListings</code>
| [[Data API/Leaderboards#stats/itemCollectorLeaderboard|<code><nowiki>stats/itemCollectorLeaderboard</nowiki></code>]]
| Returns the current trophy holders for all collectible items.
|-
|-
|<code>marketVolumeHistory</code>||<code>market/volumeHistory</code>
! colspan="2" | [[Data API/Logs|Logs]]
|-
|-
|<code>dailyUserInputs</code>||<code>misc/dailyInputs</code>
| [[Data API/Logs#logs/byBcId|<code><nowiki>logs/byBcId</nowiki></code>]]
| Returns logs associated with a user.
|-
|-
|<code>gameState</code>||<code>misc/gameState</code>
| [[Data API/Logs#logs/byIdType|<code><nowiki>logs/byIdType</nowiki></code>]]
| Returns logs associated with a faction or item.
|-
|-
|<code>itemData</code>||<code>misc/itemData</code>
| [[Data API/Logs#logs/byLogType|<code><nowiki>logs/byLogType</nowiki></code>]]
| Returns logs filtered by event type.
|-
|-
|<code>userBallsOwned</code>||<code>misc/userBallsOwned</code>
| [[Data API/Logs#misc/dailyInputs|<code><nowiki>misc/dailyInputs</nowiki></code>]]
| Returns all commands executed by a user on a specific date (UTC day).
|-
|-
|<code>egg</code>||<code>pets/egg</code>
! colspan="2" | [[Data API/Game Data|Game Data]]
|-
|-
|<code>petsLeaderboard</code>||<code>pets/leaderboard</code>
| [[Data API/Game Data#misc/itemData|<code><nowiki>misc/itemData</nowiki></code>]]
| Returns static data for all game items.
|-
|-
|<code>petOffspring</code>||<code>pets/offspring</code>
| [[Data API/Game Data#misc/gameState|<code><nowiki>misc/gameState</nowiki></code>]]
| Returns the current live game state including active bosses, the ball pit, global action boosts, and giveaways.
|-
|-
|<code>pet</code>||<code>pets/pet</code>
| [[Data API/Game Data#misc/userBallsOwned|<code><nowiki>misc/userBallsOwned</nowiki></code>]]
| Returns the number of balls the <strong>authenticated user</strong> (identified by the API key) currently has in the ball pit.
|-
|-
|<code>userPetsAndEggs</code>||<code>pets/userPetsAndEggs</code>
| [[Data API/Game Data#stats/questSeasons|<code><nowiki>stats/questSeasons</nowiki></code>]]
| Returns archived quest seasons.
|-
|-
|<code>searchFactions</code>||<code>search/factions</code>
| [[Data API/Game Data#misc/bossFactionStats|<code><nowiki>misc/bossFactionStats</nowiki></code>]]
| Returns active faction combat contribution stats for the current boss fight.
|-
|-
|<code>searchPets</code>||<code>search/pets</code>
! colspan="2" | [[Data API/Search|Search]]
|-
|-
|<code>searchUsers</code>||<code>search/users</code>
| [[Data API/Search#search/users|<code><nowiki>search/users</nowiki></code>]]
| Searches users by name.
|-
|-
|<code>trophies</code>||<code>stats/trophies</code>
| [[Data API/Search#search/factions|<code><nowiki>search/factions</nowiki></code>]]
| Searches factions by name.
|-
|-
|<code>stats</code>||<code>stats/user</code>
| [[Data API/Search#search/pets|<code><nowiki>search/pets</nowiki></code>]]
| Searches pets by species, skin, aura, and/or name.
|-
|-
|<code>userLeaderboard</code>||<code>stats/userLeaderboard</code>
! colspan="2" | [[Data API/Player Activity|Player Activity]]
|-
|-
|<code>user</code>||<code>user/get</code>
| [[Data API/Player Activity#playerActivity/online|<code><nowiki>playerActivity/online</nowiki></code>]]
| Returns game profiles with a connection, reported presence, or interaction signal in the past 90 minutes.
|-
|-
|<code>inventory</code>||<code>user/inventory</code>
! colspan="2" | [[Data API/Homepage feed|Homepage feed]]
|-
|-
|<code>profile</code>||<code>user/profile</code>
| [[Data API/Homepage feed#GET /api/eventsfeed|<code><nowiki>GET /api/eventsfeed</nowiki></code>]]
| A public endpoint with no API key, used by the homepage marquees.
|}
|}
</div>


==Notes==
<small>Generated from the Bconomy source documentation. Edits made on the wiki are overwritten on the next publish; ask the developers to change the source.</small>
* Data API requests are rate limited by both IP address and associated BcID#. This means that, if you're making a high volume of requests, Web Client functionality may be affected by your use of the API (and vice versa).
 
* Non-moderator accounts are limited to a maximum number of pages when querying [[#Logs|Logs]] endpoints.
[[Category:Data API]]
* The <code>misc/userBallsOwned</code> endpoint always returns data for the key holder — no <code>id</code> parameter is accepted.

Revision as of 12:19, 2 November 2026

The Data API is Bconomy's official HTTP interface for reading live game data as JSON. Third-party tools may use it as long as they follow the Game Rules.

Getting an API key

  1. Open the Web Client, signed in with your main Bconomy account.
  2. Run /resetapikey in the Console. Running it again replaces your key, so any tool using the old key stops working.
  3. Copy the key. It is shown only once. You may be asked to complete a verification step first.

Treat the key like a password. Anyone holding it can read anything your account can, and their requests count against your rate limit.

Quick start

Send a POST to https://bconomy.net/api/data with your key in the x-api-key header and a JSON body naming the query in type: 

const res = await fetch("https://bconomy.net/api/data", {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": MY_KEY },
  body: JSON.stringify({ type: "pets/pet", id: 1 }),
});
const pet = await res.json();

The response is the requested data itself, with no wrapper. For pets/pet that is a single Pet object.

Conventions

Topic Rule
Endpoint POST https://bconomy.net/api/data
Authentication x-api-key header on every request
Query type field in the JSON body, written as area/name (for example market/listings); other fields are that query's parameters
IDs id is a BcID for player queries and the object's own ID for pets, eggs and factions; each endpoint says which
Dates Fields documented as ISO 8601 are strings; fields documented as Unix ms are numbers of milliseconds since 1970
Pagination page is 1-based; pageSize is optional unless an endpoint says otherwise
Large numbers Some totals can exceed Number.MAX_SAFE_INTEGER and lose precision in JavaScript; those fields are marked
Rate limit 120 requests per minute, counted per IP address and per BcID; heavy API use also slows your own Web Client
Versioning None. Fields can be added, changed or removed without notice

Errors

Errors return a JSON body of { "error": string }:

Status Meaning
400 The game rejected the request, for example when you are over the rate limit. error explains why
403 The query type exists but is not available through the HTTP API
500 Anything else, including a missing or invalid key, an unknown type, or invalid parameters

Endpoints

Each endpoint page lists the request, the response and any limits. Shared shapes such as User and Pet are on Types.

Query Returns
Profile
user/profile Returns a single user's full public profile, enriched with inventory, faction, linked Discord info (if public), and BCS roles.
user/get Returns the core User object.
user/lbPositions Returns a user's leaderboard positions, scoped to that profile's own type (main / ironman / hardcore rank among their own kind only).
user/inventory Returns the inventory of a user.
stats/user Returns all tracked lifetime and periodic statistics for a user.
stats/trophies Returns the trophy record for a user.
user/otherProfiles Returns public summary information for other profiles belonging to the same account as the requested profile.
stats/userWindowed Returns time-windowed statistics for a user across multiple aggregation buckets.
stats/burnOdds Returns daily and weekly first-draw Burn odds for a user in their profile mode, using all eligible positive burns, with no leaderboard page cutoff.
Pets
pets/pet Returns a single pet.
pets/egg Returns a single egg.
pets/userPetsAndEggs Returns pets and eggs owned by a user.
pets/offspring Returns all pets and eggs that have the specified pet as a parent.
pets/leaderboard Returns a paginated page of the pets leaderboard (sorted by lifetime items found descending).
Menagerie
menagerie/get Returns a user's menagerie collection, unlocked variants, and active animal status.
menagerie/leaderboard Returns a paginated page of the menagerie collection leaderboard.
Factions
factions/get Returns a single faction.
factions/members Returns all users that belong to a faction.
factions/recruiting Returns recruiting factions of the viewer's profile type with an open member spot and at least one FP-funded active boost.
factions/joinRequests Returns faction join requests filtered by either faction or user.
factions/leaderboard Returns a paginated page of the faction leaderboard.
Market
market/preview Returns the current lowest listing price and price delta for every item.
market/listings Returns up to 50 active market listings for an item, sorted by price ascending.
market/userListings Returns all active market listings created by a user.
market/globalRecentActivity Returns the last 20 market transactions (buys, listings, and delistings) across all items.
market/recentTransactions Returns the last 5 market transactions for a specific item.
market/priceHistory Returns historical lowest-price snapshots for an item.
market/volumeHistory Returns aggregated trade volume history for an item.
Leaderboards
stats/userLeaderboard Returns a paginated page of the user leaderboard.
stats/hoarderLeaderboard Returns players ranked by hoarder trophy size (count of item-collector trophies held).
stats/itemCollectorLeaderboard Returns the current trophy holders for all collectible items.
Logs
logs/byBcId Returns logs associated with a user.
logs/byIdType Returns logs associated with a faction or item.
logs/byLogType Returns logs filtered by event type.
misc/dailyInputs Returns all commands executed by a user on a specific date (UTC day).
Game Data
misc/itemData Returns static data for all game items.
misc/gameState Returns the current live game state including active bosses, the ball pit, global action boosts, and giveaways.
misc/userBallsOwned Returns the number of balls the authenticated user (identified by the API key) currently has in the ball pit.
stats/questSeasons Returns archived quest seasons.
misc/bossFactionStats Returns active faction combat contribution stats for the current boss fight.
Search
search/users Searches users by name.
search/factions Searches factions by name.
search/pets Searches pets by species, skin, aura, and/or name.
Player Activity
playerActivity/online Returns game profiles with a connection, reported presence, or interaction signal in the past 90 minutes.
Homepage feed
GET /api/eventsfeed A public endpoint with no API key, used by the homepage marquees.

Generated from the Bconomy source documentation. Edits made on the wiki are overwritten on the next publish; ask the developers to change the source.

Retrieved from "https://wiki.bconomy.net/w/index.php?title=Data_API&oldid=463"