Data API/Types

Data API

Common types

These types appear across multiple endpoint responses.

User

interface User {
  id: number                   // BcID
  name: string
  registrationDate: string     // ISO 8601
  rank: number                 // current position in the rank lineup (1–60)
  tier: number
  bc: number                   // balance
  sp: number                   // store points
  kr: number                   // karma
  chips: number                // Fun House chips
  buddyId: number | null
  factionId: number | null
  factionTag: string | null
  factionJoinDate: string      // ISO 8601
  factionDepositWeekly: number
  factionDepositTotal: number
  questLevel: number
  questLevelClaimed: number
  dailyClaimStreak: number
  petsBredDaily: number
  lastCaptchaDate: string      // ISO 8601
  farmPlots: Array<{
    level: number
    status: { isPlanted: false } | { isPlanted: true; itemId: number; plantedTime: number }
    boost: { multiplier: number; endTime: number }
    isExtra: boolean
  }>
  generators: Array<{ level: number; isExtra: boolean }>
  quests: Array<{ itemId: number; amountRequired: number; amountFulfilled: number }>
  cooldowns: {
    fish: number; hunt: number; explore: number; mine: number; work: number
    daily: number; water: number; claimGenerators: number; setBuddy: number
    buddyBossAttack: number; resetPerks: number; eternalsnowflakeUse: number
  }  // values are Unix ms expiry timestamps (0 = no cooldown)
  effects: Record<string, { endTime: number; modifier: object }>
  upgrades: {
    fish: number; fishExtra: number; hunt: number; huntExtra: number
    explore: number; exploreExtra: number; mine: number; mineExtra: number
    petsStable: number; petsStableExtra: number
  }
  augments: Array<{ lootAction: LootAction; itemId: number; expiry: number }>
  equippedFlatInventory: Inventory
  perks: Partial<Record<PrestigePerkId, number>>
  pinnedItemIds: number[]
  pinnedPetIds: number[]
  autosellLimits: Record<string, number>
  itemReserveAmounts: Record<string, number>
  settings: {
    profileShowStatId: StatKey | null
    title: { type: "trophy"; trophyId: TrophyId } | { type: "specificRank"; rankNum: number } | null
    syncDiscordName: boolean
    publicDiscordProfile: boolean
    petsBulkFeedFoundItemsFirst: boolean
    petsBulkFeedCravingsOnly: boolean
    aggregateBulkOutput: boolean
  }
  custom: {
    profileHideAvatar: boolean
    profileHideTitleName: boolean
    profileUseChatEmblemEmoji: boolean
    profileBackground: string | null
    chatEmblemEmoji: string | null
    chatUsernameColor: string | null
    chatUsernameStyle: string | null
    chatMessageBackgroundColor: string | null
  }
  blockedBcIds: number[]
  banExpiryDate: string        // ISO 8601
  premiumExpiryDate: string | null  // ISO 8601
}

Pet

interface Pet {
  id: number
  ownerBcId: number | null     // null for wild pets
  hatchDate: string            // ISO 8601
  name: string
  tier: number
  xp: number
  species: PetSpecies
  generation: number
  parentAId: number | null
  parentBId: number | null
  timesBred: number
  lastBred: string             // ISO 8601
  heldItemId: number | null
  unsyncedEnergy: number
  adventureType: "fish" | "hunt" | "explore" | "mine" | null
  adventureBoost: { multiplier: number; endTime: number } | null
  lastAdventureSync: string    // ISO 8601
  lifetimeItemsFound: number
  craving: { itemId: number; amount: number }
  skin: PetSkin | null
  aura: PetAura | null
}

Egg

interface Egg {
  id: number
  ownerBcId: number | null
  parentAId: number
  parentBId: number
  parentAHeldItemId: number | null
  parentBHeldItemId: number | null
}

Faction

interface Faction {
  id: number
  tag: string | null
  name: string
  ownerBcId: number
  rankOverrides: Record<string, number>
  isRecruiting: boolean
  isOpenRecruitment: boolean  // Immediate joining while recruiting and below capacity
  about: string | null
  motd: string | null
  unsyncedFp: number
  lastFpSync: string           // ISO 8601
  boostSteps: {
    fish:    { lastChange: number; amount: number }
    hunt:    { lastChange: number; amount: number }
    explore: { lastChange: number; amount: number }
    mine:    { lastChange: number; amount: number }
  }
  halls: number
  fpDepositedMonthly: number
  fpDepositedTotal: number
  customizationSettings: {
    emblemEmoji: string | null
    tagColor: string | null
    nameColor: string | null
    nameStyle: string | null
  }
  ownerPremiumExpiryDate: string | null  // ISO 8601
  memberCount: number
  pendingRequests: number
}

Inventory

A JSON object where each key is an item's idName string (e.g. "rocks", "lunarShard") and each value is the owned quantity. Only items with a non-zero quantity are present.

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

LeaderboardPage<T>

Returned by all paginated leaderboard endpoints.

interface LeaderboardPage<T> {
  data: T[]
  total: number         // total entries across all pages
  pageSize: number
  lastUpdated: number   // Unix ms timestamp of last cache refresh
  ownEntry?: (T & { rank: number }) | null  // requesting user's entry; omitted for some lb types
}

LeaderboardUser

The entry type T for user leaderboards.

interface LeaderboardUser {
  id: number           // BcID
  name: string
  custom: User["custom"]
  premiumExpiryDate: string | null
  lbValue: number      // primary sort value (may exceed Number.MAX_SAFE_INTEGER)
  secondaryLbValue?: number
}

GameLogResponse

Returned by all log endpoints.

interface GameLogResponse {
  entries: GameLog[]
  refs: {
    profiles: Record<number, User>    // keyed by BcID
    factions: Record<number, Faction> // keyed by faction ID
    pets: Record<number, Pet>         // keyed by pet ID
  }
  total: number
  pageSize: number
  page: number
}

GameLog

interface GameLog {
  id: number
  date: string                // ISO 8601
  senderBcId: number | null
  recipientBcId: number | null
  factionId: number | null
  itemId: number | null
  type: GameLogType
  data: {
    amount?: number
    ballPitType?: "black" | "purple" | "blue" | "orange" | "yellow" | "green"
    listingPrice?: number
    newFactionRank?: number
    action?: "fish" | "hunt" | "explore" | "mine" | "work"
    petId?: number
    eggId?: number
    special?: Special
  }
}

MarketListing

interface MarketListing {
  id: number
  bcId: number       // seller BcID
  itemId: number
  price: number
  amount: number
}

MarketActivityEntry

interface MarketActivityEntry {
  itemId: number
  itemName: string
  itemEmoji: string
  type: "buy" | "list" | "delist"
  actorBcId: number
  actorName: string | null
  amount: number
  price: number
  date: string       // ISO 8601
}

MarketPreviewItem

interface MarketPreviewItem {
  price?: number      // current lowest listing price; absent if no active listings
  delta: {
    day: number | null    // % change vs 24 h ago; null if no data
    week: number | null
    month: number | null
  }
}

MarketPriceSnapshot

interface MarketPriceSnapshot {
  id: number
  snapshotTime: string   // ISO 8601
  itemId: number
  lowestPrice: number | null
}

MarketVolumeSnapshot

interface MarketVolumeSnapshot {
  id: number
  granularity: "hour" | "day" | "month"
  windowStart: string    // ISO 8601
  windowEnd: string      // ISO 8601
  itemId: number
  unitsSold: number      // may exceed MAX_SAFE_INTEGER for high-volume items
  totalRevenue: number   // may exceed MAX_SAFE_INTEGER
  transactionCount: number
}

FactionJoinRequest

interface FactionJoinRequest {
  id: number
  bcId: number
  factionId: number
  reason: string | null
  date: string           // ISO 8601
}

UserStats

interface UserStats {
  bcId: number
  incomeDaily: number;         incomeWeekly: number;          incomeTotal: number
  timesFished: number;         timesHunted: number;           timesExplored: number
  timesMined: number;          timesWorked: number
  itemsFound: number;          rareItemsFound: number
  itemsCrafted: number;        itemsHarvested: number;        timesWatered: number
  bcEarnedFromGens: number
  petItemsFound: number;       petItemsFed: number;           petsBred: number
  questsCompleted: number;     fpContributed: number
  timesPlayedCoinflip: number
  netCoinflipProfitDaily: number; netCoinflipProfitWeekly: number; netCoinflipProfitTotal: number
  bcBurnedDaily: number;       bcBurnedWeekly: number;        bcBurnedTotal: number
  bossDamage: number           // may exceed MAX_SAFE_INTEGER
  marketListingsSold: number
  marketListingsRevenue: number // may exceed MAX_SAFE_INTEGER
  netBallPitProfit: number
  museumCollectiblesFound: number
  globalBoostsUsed: number;    worthGivenAway: number
}

UserTrophies

interface UserTrophies {
  bcId: number
  trophyRecord: Partial<Record<TrophyId, { count: number; timeFirstAchieved: number }>>
}

Enumerations

PetSpecies

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

Supporter: dragon, phoenix, visitor, invader, sauropod, tyrannosaurus, jack, ghost, snowman

PetSkin

Base: alpha, beta, gamma, delta, epsilon, zeta, eta

Unique: sunkissed, grayscale, whiteout

PetAura

green, purple, orange, cyan, red, pink, blue, yellow, black

LootAction

fish, hunt, explore, mine

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

lbType	Description	Required extra field
wallet	Richest by BC balance	—
inventoryWorth	Richest by inventory value	—
rank	Highest rank	—
questLevel	Highest quest level	—
streak	Longest daily claim streak	—
stat	Any tracked statistic	stat (a key of UserStats, excluding bcId)
item	Most of a specific item	itemId
trophy	Most of a specific trophy	trophyId

StatKey (for lbType: "stat")

Any key of UserStats except bcId: incomeDaily, incomeWeekly, incomeTotal, timesFished, timesHunted, timesExplored, timesMined, timesWorked, itemsFound, rareItemsFound, itemsCrafted, itemsHarvested, timesWatered, bcEarnedFromGens, petItemsFound, petItemsFed, petsBred, questsCompleted, fpContributed, timesPlayedCoinflip, netCoinflipProfitDaily, netCoinflipProfitWeekly, netCoinflipProfitTotal, bcBurnedDaily, bcBurnedWeekly, bcBurnedTotal, bossDamage, marketListingsSold, marketListingsRevenue, netBallPitProfit, museumCollectiblesFound, globalBoostsUsed, worthGivenAway

TrophyId

bossKillingBlow, topDayIncome, topWeekIncome, topDayBurn, topWeekBurn, topDayBet, topWeekBet, topDayFunhouse, topWeekFunhouse, bottomDayFunhouse, bottomWeekFunhouse, dust, findSpecial, donor, lotwin, wewert, based, composer, bcbeta, summer2022Event, winter2024Lv125, winter2024Lv250, winter2024Lv375, winter2024Lv500, spring2025Lv250, spring2025Lv500, spring2025Lv750, spring2025Lv1000, topSeasonQuestLevel, top10SeasonQuestLevel, bconomySmp2025, summer2025Lv125, summer2025Lv250, summer2025Lv500, summer2025Lv1000, wewertTwo, fall2025Lv100, fall2025Lv250, fall2025Lv500, fall2025Lv1000, fall2025Lv2500, fall2025Lv5000, winter2025Lv100, winter2025Lv250, winter2025Lv500, winter2025Lv1000, winter2025Lv2500, winter2025Lv5000, dolphinCollector, otterCollector, gooseCollector, sealCollector, whaleCollector, turtleCollector, eagleCollector, tigerCollector, gorillaCollector, crocodileCollector, snakeCollector, poodleCollector, dogCollector, mustangCollector, pigCollector, peacockCollector, donkeyCollector, oxCollector, junglefowlCollector, rabbitCollector, doveCollector, kangarooCollector, batCollector, ratCollector, snailCollector, lizardCollector, dragonCollector, phoenixCollector, visitorCollector, invaderCollector, scorpionCollector, sauropodCollector, tyrannosaurusCollector, jackCollector, ghostCollector, owlCollector, snowmanCollector, cockroachCollector, eggstravagant

PrestigePerkId

raiseBurnItemReturn, raiseWorkBonusChance, lowerRankCost, lowerTierCost, raiseRareItemMultiplier, raiseCoinflipLimit, raisePetMaxTier, lowerWaterFarmCooldown, raiseMaxSameItemPlanted, raisePetSpace, lowerBuddySwapCooldown, raiseEquipSlots, raiseGeneratorIdleTime, raiseFarmCropsDieTime, raisePetCravingXpMultiplier, raiseChanceToIgnoreCooldownForAction, raisePetFeedAdditionalItemOutput, raiseFarmHarvestAdditionalItemOutput, lowerPetBreedCooldown, raisePetEnergyCapacity, lowerPetBreedCost, raiseToolAugmentationSlots, raiseFarmWaterByproducts, raiseMarketAccessLevel, raiseMaxDailyReward, reduceMarketTransactionFee

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