Wewert: Created page with "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 yo..."

2026-11-01T21:14:08Z

Created page with "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 yo..."

New page

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 [[Getting started#Follow the game rules|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:

# Access the [https://bconomy.net/play Web Client], making sure you are logged in with your primary Bconomy account.
# Open your Console and run command <code>/resetapikey</code> to generate a new API key.
## '''NOTE: If you have an existing API key, running this command will invalidate it!'''
## 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.

==Specification==
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.

===Example===
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",
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);
</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==
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.

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.

===Common types===
These types are referenced throughout the table below.

====User====
The full <code>User</code> object returned by several endpoints. Key fields:
<pre>
{
"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
}
</pre>

====Pet====
<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====
<pre>
{
"id": 1,
"ownerBcId": 1, // null for abandoned eggs
"parentAId": 12,
"parentBId": 34,
"parentAHeldItemId": null,
"parentBHeldItemId": 5
}
</pre>

====Faction====
<pre>
{
"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
}
</pre>

====Inventory====
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>
|-
|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>
|-
|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>
|-
|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>
|-
|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>
|-
|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>
|}
</div>

===Query reference===
<div style="overflow-x:auto;">
{| class="wikitable" style="width:100%"
!Query
!Request body
!Response
!Notes
|-
| colspan="4" | '''Profile'''
|- style="vertical-align:top"
|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'''
|- 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>]]<[[#Pet|<code>Pet</code>]]>
|<code>pageSize</code> is optional (defaults to server value). Sorted by tier then XP descending.
|-
| colspan="4" | '''Factions'''
|- style="vertical-align:top"
|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>]]<[[#Faction|<code>Faction</code>]]>
|<code>stat</code>: <code>"fpDepositedMonthly"</code> or <code>"fpDepositedTotal"</code>. <code>pageSize</code> is optional.
|-
| colspan="4" | '''Market'''
|- style="vertical-align:top"
|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)'''
|- style="vertical-align:top"
|User leaderboard
|<pre>{
"type": "stats/userLeaderboard",
"lbType": "rank",
"page": 1,
"pageSize": 50
}</pre>
|[[#LeaderboardPage|<code>LeaderboardPage</code>]]<LeaderboardUser>
|<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>
|- style="vertical-align:top"
|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'''
|- style="vertical-align:top"
|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'''
|- style="vertical-align:top"
|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>
|-
|<code>factionJoinRequests</code>||<code>factions/joinRequests</code>
|-
|<code>factionLeaderboard</code>||<code>factions/leaderboard</code>
|-
|<code>factionMembers</code>||<code>factions/members</code>
|-
|<code>recruitingFactions</code>||<code>factions/recruiting</code>
|-
|<code>richLogsByBcId</code>||<code>logs/byBcId</code>
|-
|<code>richLogsByIdType</code>||<code>logs/byIdType</code>
|-
|<code>richLogsByLogType</code>||<code>logs/byLogType</code>
|-
|<code>marketGlobalRecentActivity</code>||<code>market/globalRecentActivity</code>
|-
|<code>marketListings</code>||<code>market/listings</code>
|-
|<code>marketPreview</code>||<code>market/preview</code>
|-
|<code>marketPriceHistory</code>||<code>market/priceHistory</code>
|-
|<code>marketRecentTransactions</code>||<code>market/recentTransactions</code>
|-
|<code>userMarketListings</code>||<code>market/userListings</code>
|-
|<code>marketVolumeHistory</code>||<code>market/volumeHistory</code>
|-
|<code>dailyUserInputs</code>||<code>misc/dailyInputs</code>
|-
|<code>gameState</code>||<code>misc/gameState</code>
|-
|<code>itemData</code>||<code>misc/itemData</code>
|-
|<code>userBallsOwned</code>||<code>misc/userBallsOwned</code>
|-
|<code>egg</code>||<code>pets/egg</code>
|-
|<code>petsLeaderboard</code>||<code>pets/leaderboard</code>
|-
|<code>petOffspring</code>||<code>pets/offspring</code>
|-
|<code>pet</code>||<code>pets/pet</code>
|-
|<code>userPetsAndEggs</code>||<code>pets/userPetsAndEggs</code>
|-
|<code>searchFactions</code>||<code>search/factions</code>
|-
|<code>searchPets</code>||<code>search/pets</code>
|-
|<code>searchUsers</code>||<code>search/users</code>
|-
|<code>trophies</code>||<code>stats/trophies</code>
|-
|<code>stats</code>||<code>stats/user</code>
|-
|<code>userLeaderboard</code>||<code>stats/userLeaderboard</code>
|-
|<code>user</code>||<code>user/get</code>
|-
|<code>inventory</code>||<code>user/inventory</code>
|-
|<code>profile</code>||<code>user/profile</code>
|}
</div>

==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|Logs]] endpoints.
* The <code>misc/userBallsOwned</code> endpoint always returns data for the key holder — no <code>id</code> parameter is accepted.

← Older revision		Revision as of 21:42, 3 November 2026
Line 4:		Line 4:

	== Getting an API key ==		== Getting an API key ==

			Public static reference data is also available without a key through <code><nowiki>GET /api/reference</nowiki></code>. Other Data API queries below require a key.

	# Open the [https://bconomy.net/play Web Client], signed in with your main Bconomy account.		# Open the [https://bconomy.net/play Web Client], signed in with your main Bconomy account.
Line 207:		Line 209:
	\|-		\|-
	! colspan="2" \| [[Data API/Game Data\|Game Data]]		! colspan="2" \| [[Data API/Game Data\|Game Data]]
			\|-
			\| [[Data API/Game Data#GET /api/reference\|<code><nowiki>GET /api/reference</nowiki></code>]]
			\| Public, read-only reference definitions from the running server.
	\|-		\|-
	\| [[Data API/Game Data#misc/itemData\|<code><nowiki>misc/itemData</nowiki></code>]]		\| [[Data API/Game Data#misc/itemData\|<code><nowiki>misc/itemData</nowiki></code>]]

← Older revision		Revision as of 21:49, 1 November 2026
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 [[Getting ~~started~~#Follow the game rules\|Game Rules]].		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]].

	==API key==		==API key==

Data API - Revision history

GameReferenceSync: Publish from docs/data-api.md

TheCarriedOne: Publish from docs/data-api.md

Wewert at 21:49, 1 November 2026