Jump to content

Data API

From Bconomy Wiki
Revision as of 21:49, 1 November 2026 by Wewert (talk | contribs)

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 Game Rules.

API key

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:

  1. Access the Web Client, making sure you are logged in with your primary Bconomy account.
  2. Open your Console and run command /resetapikey to generate a new API key.
    1. NOTE: If you have an existing API key, running this command will invalidate it!
    2. You may be asked to complete some verification steps before an API key can be produced.
  3. 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.

Specification

The Data API endpoint is located at https://bconomy.net/api/data 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 x-api-key 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.

Example

Making an API call using JavaScript: 

// Fetch raw data for Pet with ID#1
const rawData = await fetch("https://bconomy.net/api/data", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.MY_BCONOMY_API_KEY,
  },
  body: JSON.stringify({ type: "pet", id: 1 }),
});

// Parse raw data into JSON object
const parsedData = await rawData.json();

// Display parsed, fetched data
console.log(parsedData);

The following data is returned: 

{
  "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"
}

Payload structure

The query payload and returned data for all Data API requests are identical in structure to those present in dataFetch messages in WebSocket connections established by the Web Client.

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

Common types

These types are referenced throughout the table below.

User

The full User object returned by several endpoints. Key fields: 

{
  "id": 1,                         // BcID
  "name": "Alice",
  "registrationDate": "2021-01-01T00:00:00.000Z",
  "rank": 50,
  "tier": 3,
  "bc": 1000000,                   // BC balance
  "sp": 200,                       // store points
  "kr": 5,                         // karma
  "buddyId": null,
  "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
}

Pet

{
  "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
}

Egg

{
  "id": 1,
  "ownerBcId": 1,               // null for abandoned eggs
  "parentAId": 12,
  "parentBId": 34,
  "parentAHeldItemId": null,
  "parentBHeldItemId": 5
}

Faction

{
  "id": 1,
  "tag": "ALPH",
  "name": "Alpha",
  "ownerBcId": 1,
  "rankOverrides": {},
  "isRecruiting": true,
  "about": "We are recruiting!",
  "motd": "Good luck today",
  "unsyncedFp": 0,
  "lastFpSync": "2025-07-01T00:00:00.000Z",
  "boostSteps": {
    "fish":    { "lastChange": 1750000000000, "amount": 2 },
    "hunt":    { "lastChange": 0, "amount": 0 },
    "explore": { "lastChange": 0, "amount": 0 },
    "mine":    { "lastChange": 0, "amount": 0 }
  },
  "halls": 3,
  "fpDepositedMonthly": 50000,
  "fpDepositedTotal": 1200000,
  "customizationSettings": { "emblemEmoji": null, "tagColor": null, "nameColor": null, "nameStyle": null },
  "ownerPremiumExpiryDate": null,
  "memberCount": 12,
  "pendingRequests": 2
}

Inventory

A JSON object where keys are item idName strings and values are the owned quantity (positive integer). Only items owned in non-zero amounts are present. 

{ "rocks": 500, "wood": 120, "lunarShard": 3 }

LeaderboardPage

Envelope returned by all leaderboard endpoints. T is Faction for the faction board, Pet for the pet board, or LeaderboardUser (a slimmer object, see below) for user stat/rank boards. 

{
  "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
  }
}

The data entries for user leaderboards (stats/userLeaderboard) are LeaderboardUser objects: 

{
  "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
}

GameLogResponse

{
  "entries": [ /* GameLog[] */ ],
  "refs": {
    "profiles":  { "1": { /* User */ } },   // keyed by BcID
    "factions":  { "2": { /* Faction */ } },
    "pets":      { "5": { /* Pet */ } }
  },
  "total": 310,
  "pageSize": 50,
  "page": 1
}

Each GameLog entry: 

{
  "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
  }
}

MarketListing

{ "id": 1, "bcId": 1, "itemId": 5, "price": 500, "amount": 10 }

MarketActivityEntry

{
  "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"
}

Enumerations

Name Values
Pet species (base) poodle dog bat mustang pig eagle otter tiger peacock donkey gorilla ox junglefowl crocodile goose rat seal whale rabbit dove kangaroo snake turtle snail dolphin lizard scorpion owl cockroach
Pet species (supporter) dragon phoenix visitor invader sauropod tyrannosaurus jack ghost snowman
Pet skin Base: alpha beta gamma delta epsilon zeta eta — Unique: sunkissed grayscale whiteout
Pet aura green purple orange cyan red pink blue yellow black
GameLogType itemFind ballPitWin marketItemTransaction tradeItemTransaction tradeBcTransaction factionJoin factionCreate factionDelete factionDemote factionPromote factionTransfer factionVaultDeposit factionVaultUpgrade factionKick factionLeave factionIncreaseBoost factionDecreaseBoost lbReceiveItemReward lbReceiveSpecialReward bossReceiveItemReward bossReceiveSpecialReward eggCreate eggAbandon eggTransfer eggLocate eggHatch petTransfer petRelease specialUse specialFind giveawayItemTransfer supportGrantItem marketListingCreated marketListingDelisted
UserLeaderboardType wallet inventoryWorth rank questLevel streak stat item trophy

Query reference

Query Request body Response Notes
Profile
Profile 
{ "type": "user/profile", "id": 1 }
 User extended with bcsRoles, Inventory, optional Faction, lbPositions, optional displayStatValue, and optional Discord fields bcsRoles: array of "moderator", "developer", "inactiveModerator". Discord fields only present when the user has set publicDiscordProfile: true. lbPositions is a record of leaderboard type to 1-based rank.
User 
{ "type": "user/get", "id": 1 }
 User
Inventory 
{ "type": "user/inventory", "id": 1 }
 Inventory Keys are item idName strings. Only non-zero amounts included.
Stats 
{ "type": "stats/user", "id": 1 }
 
{
  "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
}
 bossDamage and marketListingsRevenue can exceed Number.MAX_SAFE_INTEGER for high-activity users.
Trophies 
{ "type": "stats/trophies", "id": 1 }
 
{
  "bcId": 1,
  "trophyRecord": {
    "topDayIncome": { "count": 3, "timeFirstAchieved": 1700000000000 }
  }
}
 trophyRecord is a partial record; unearned trophies are absent.
Pets
Pet 
{ "type": "pets/pet", "id": 1 }
 Pet
Egg 
{ "type": "pets/egg", "id": 1 }
 Egg
Owned 
{ "type": "pets/userPetsAndEggs", "id": 1 }
 
{ "pets": [ /* Pet[] */ ], "eggs": [ /* Egg[] */ ] }
 Returns all Pets and Eggs whose owner is the provided BcID.
Offspring 
{ "type": "pets/offspring", "id": 1 }
 
{ "eggs": [ /* Egg[] */ ], "pets": [ /* Pet[] */ ] }
 Returns all Eggs and Pets that have the provided Pet ID as a parent.
Leaderboard 
{
  "type": "pets/leaderboard",
  "page": 1,
  "pageSize": 50
}
 LeaderboardPage<Pet> pageSize is optional (defaults to server value). Sorted by tier then XP descending.
Factions
Faction 
{ "type": "factions/get", "id": 1 }
 Faction
Members 
{ "type": "factions/members", "id": 1 }
 User[] Returns all Users that belong to the supplied Faction ID.
Recruiting 
{ "type": "factions/recruiting" }
 
{ "lastUpdated": 1751000000000, "data": [ /* Faction[] */ ] }
 Returns all Factions that are recruiting, below max member count, and below max pending requests. Cached; refreshes approximately every 15 minutes.
Join requests 
{
  "type": "factions/joinRequests",
  "idType": "factionId",
  "id": 1
}
 
[{
  "id": 1,
  "bcId": 5,
  "factionId": 1,
  "reason": "I want to join!",
  "date": "2025-07-01T00:00:00.000Z"
}]
 idType: "factionId" returns requests sent to the faction; "bcId" returns requests sent by that user.
Leaderboard 
{
  "type": "factions/leaderboard",
  "stat": "fpDepositedMonthly",
  "page": 1,
  "pageSize": 50
}
 LeaderboardPage<Faction> stat: "fpDepositedMonthly" or "fpDepositedTotal". pageSize is optional.
Market
Preview 
{ "type": "market/preview" }
 
{
  "lastUpdated": 1751000000000,
  "data": {
    "lunarShard": {
      "price": 1000,
      "delta": { "day": 5.2, "week": -1.1, "month": null }
    }
  }
}
 Keyed by item idName. price absent if no active listings. delta values are percentage changes vs that period; null if no historical data. Cached ~5 minutes.
Listings (item) 
{ "type": "market/listings", "itemId": 5 }
 MarketListing[] Returns up to 50 active listings for the item, sorted by price ascending.
Listings (user) 
{ "type": "market/userListings", "id": 1 }
 MarketListing[] Returns all active listings created by the provided BcID.
Global recent activity 
{ "type": "market/globalRecentActivity" }
 MarketActivityEntry[] Last 20 transactions (buys, listings, delistings) across all items. Cached 10 seconds.
Recent transactions (item) 
{ "type": "market/recentTransactions", "itemId": 5 }
 MarketActivityEntry[] Last 5 transactions for a specific item.
Price history 
{
  "type": "market/priceHistory",
  "itemId": 5,
  "days": 30
}
 
[{
  "id": 1,
  "snapshotTime": "2025-06-01T00:00:00.000Z",
  "itemId": 5,
  "lowestPrice": 980
}]
 Sorted ascending by snapshotTime. lowestPrice is null if no listings existed at snapshot time. Optional filters: days (integer, days back from now), or fromMs / toMs (Unix ms range).
Volume history 
{
  "type": "market/volumeHistory",
  "itemId": 5,
  "granularity": "day",
  "days": 30
}
 
[{
  "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
}]
 granularity: "hour", "day", or "month". days is optional (max 400). unitsSold and totalRevenue can exceed MAX_SAFE_INTEGER for popular items.
Leaderboards (user)
User leaderboard 
{
  "type": "stats/userLeaderboard",
  "lbType": "rank",
  "page": 1,
  "pageSize": 50
}
 LeaderboardPage<LeaderboardUser> lbType determines the ranking. Some types require an additional field:
  • "wallet" — BC balance; no extra field
  • "inventoryWorth" — inventory value; no extra field
  • "rank" — rank number; no extra field
  • "questLevel" — quest level; no extra field
  • "streak" — daily claim streak; no extra field
  • "stat" — requires "stat": a key from the stats object (e.g. "timesFished", "marketListingsRevenue")
  • "item" — requires "itemId": item ID to rank by amount owned
  • "trophy" — requires "trophyId": trophy ID to rank by count
Logs
By BcID 
{
  "type": "logs/byBcId",
  "id": 1,
  "page": 1,
  "pageSize": 50
}
 GameLogResponse Returns logs where the user is sender or recipient. Non-moderators are limited to a maximum number of pages.
By ID type 
{
  "type": "logs/byIdType",
  "idType": "factionId",
  "id": 1,
  "page": 1,
  "pageSize": 50
}
 GameLogResponse idType: "factionId" or "itemId". Non-moderators are limited to a maximum number of pages.
By log type 
{
  "type": "logs/byLogType",
  "logType": "marketItemTransaction",
  "page": 1,
  "pageSize": 50
}
 GameLogResponse See GameLogType for all valid logType values. Non-moderators are limited to a maximum number of pages.
Daily inputs 
{
  "type": "misc/dailyInputs",
  "id": 1,
  "date": "2025-07-01"
}
 
{
  "day": "2025-07-01",
  "data": [
    { "time": 1751380800000, "input": { "type": "fish/cast", ... } }
  ]
}
 Returns all commands executed by the user on date. date accepts ISO date strings, YYYY/MM/DD, or a Unix timestamp. Records available for the previous 30-day period only.
Game Data
Items 
{ "type": "misc/itemData" }
 
[{
  "id": 5,
  "imageUrl": "https://assets.bconomy.net/items/lunarShard.webp",
  "recipe": [["rocks", 10], ["wood", 5]],
  /* ...plus all other item fields */
}]
 Static data for all game items. recipe is an array of [idName, amount] tuples.
Game state 
{ "type": "misc/gameState" }
 
{
  "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": []
}
 activeBossStatus is null when no boss is active.
Balls owned 
{ "type": "misc/userBallsOwned" }
 number Returns the ball pit ball count for the authenticated user (identified by the API key). No id parameter is accepted.
Search
Users 
{ "type": "search/users", "query": "alice" }
 User[] Returns users whose name matches the query. Maximum 20 results.
Factions 
{ "type": "search/factions", "query": "alpha" }
 Faction[] Returns factions whose name matches the query. Maximum 20 results.
Pets 
{
  "type": "search/pets",
  "skin": "gamma",
  "aura": "any aura",
  "species": "goose",
  "rawNameQuery": "genesis"
}
 Pet[] All four fields are required. Use "any skin" / "any aura" / "any species" to match any value, or "no skin" / "no aura" to match pets without one. Empty string for rawNameQuery matches all names. Maximum 20 results, sorted by tier then XP descending.

Legacy type aliases

Both the canonical namespaced type and the legacy alias are accepted in any request.

Legacy aliases
Legacy type Canonical type
faction factions/get
factionJoinRequests factions/joinRequests
factionLeaderboard factions/leaderboard
factionMembers factions/members
recruitingFactions factions/recruiting
richLogsByBcId logs/byBcId
richLogsByIdType logs/byIdType
richLogsByLogType logs/byLogType
marketGlobalRecentActivity market/globalRecentActivity
marketListings market/listings
marketPreview market/preview
marketPriceHistory market/priceHistory
marketRecentTransactions market/recentTransactions
userMarketListings market/userListings
marketVolumeHistory market/volumeHistory
dailyUserInputs misc/dailyInputs
gameState misc/gameState
itemData misc/itemData
userBallsOwned misc/userBallsOwned
egg pets/egg
petsLeaderboard pets/leaderboard
petOffspring pets/offspring
pet pets/pet
userPetsAndEggs pets/userPetsAndEggs
searchFactions search/factions
searchPets search/pets
searchUsers search/users
trophies stats/trophies
stats stats/user
userLeaderboard stats/userLeaderboard
user user/get
inventory user/inventory
profile user/profile

Notes

  • 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 endpoints.
  • The misc/userBallsOwned endpoint always returns data for the key holder — no id parameter is accepted.
Retrieved from "https://wiki.bconomy.net/w/index.php?title=Data_API&oldid=338"