Data API

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

Public static reference data is also available without a key through GET /api/reference. Other Data API queries below require a 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
GET /api/reference	Public, read-only reference definitions from the running server.
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.