Data API

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.