# TerraCore > Post-apocalyptic blockchain strategy game on the HIVE blockchain where players mine SCRAP, battle each other, explore planets, and collect NFT equipment. TerraCore is a play-to-earn strategy game built on HIVE. Players stake HIVE to start mining SCRAP tokens, upgrade stats, equip NFT items, battle other players, and complete quests. All game actions are HIVE `custom_json` operations processed by an on-chain Smart Contract. Game state is fully readable via a public REST API with no authentication required. ## Versioning API version: `2026.08.1` Version endpoint: `GET https://api.terracoregame.com/version` Version header: `X-TerraCore-API-Version` (present on every API response) Bots and integrations SHOULD poll `GET /version` on startup. Response fields: - `version` — current version string (calendar format: YYYY.MM.patch) - `released` — ISO 8601 release date - `notes` — link to the human-readable dev post for this release - `changelog` — full changelog URL - `llms` — canonical URL of this file A version change signals that costs, burn rates, endpoint behavior, or response shapes may have changed. Check `notes` and `changelog` before resuming normal operation. ## Docs - [Wiki](https://www.terracoregame.com/wiki/): Full player and developer documentation - [Wiki Sitemap](https://www.terracoregame.com/wiki/sitemap.xml): All wiki pages for crawler discovery - [Developer Overview](https://www.terracoregame.com/wiki/developers/): Architecture, custom_json operation reference, and token info - [REST API Endpoints](https://www.terracoregame.com/wiki/developers/api-endpoints): All public endpoints for reading game state - [NFT Marketplace API](https://www.terracoregame.com/wiki/developers/nft-marketplace): Marketplace listing, buying, and transfer operations - [Bot & Automation Guide](https://www.terracoregame.com/wiki/developers/bot-guide): Guide for building bots, scripts, and third-party tools on TerraCore - [Gameplay](https://www.terracoregame.com/wiki/gameplay/): Battles, quests, boss fights, and exploration mechanics - [Economy](https://www.terracoregame.com/wiki/economy/): SCRAP and FLUX tokenomics - [Player Stats](https://www.terracoregame.com/wiki/stats/): Engineering, Damage, Defense, Luck, Dodge, Crit, Favor, and more - [NFTs](https://www.terracoregame.com/wiki/nfts/): Items, crates, relics, salvaging ## REST API Base URL: `https://api.terracoregame.com` Interactive docs: `https://api.terracoregame.com/api-docs/` OpenAPI spec (JSON): `https://api.terracoregame.com/swagger.json` Rate limit: 60 requests per minute per IP (HTTP 429 on exceed) Authentication: none required Key endpoints: - `GET /version` — current API version, release date, and links to changelog and llms.txt - `GET /player/{username}` — full player object (stats, citizenship, last active). `minerate` field reflects engineering softcap (50% diminishing returns above eng 333) and gentle mine rate decay (10%/week after 14-day inactivity, floor 25%); decays if player has not done a qualifying sink action — quest start, boss fight, stat upgrade, or item forge — within 14 days. Battles and claims do not reset decay. - `GET /players` — all players; filter with `?usernames=alice,bob` - `GET /items/{username}` — NFT items owned by a player - `GET /quests/{username}` — active quest(s) for a player; returns array of `{ _id, username, template_id, quest_type, tier, name, flavor, image_url, primary_stat, required_item_type, scrap_paid, base_rolls, duration_hours, equipped_item_rarity, equipped_item_level, effective_primary_stat, started_at, completes_at, expires_at, collected, time_remaining_ms, board_date }`. Pair an active quest with its board slot on `template_id` — `quest_type`+`tier` is not unique, since a board may carry two slots of the same type and tier. Relic rewards are multiplied by a gear investment factor (0.30–1.0) keyed on `equipped_item_rarity`/`equipped_item_level` in the quest's slot at start: no/low gear yields 30%, ramping to 100% with rarer + higher-forge-level gear. Low tiers (T1/T2) also have their legendary/epic relic odds collapsed toward common/uncommon. - `GET /quest_board` — today's daily quest board, open to all players; returns `{ date, slots: [{template_id, quest_type, tier, name, duration_hours, base_rolls, scrap_cost}], generated_at, multiplier, scrap_usd }`. The `?username=` parameter is accepted but ignored (quest beta ended 2026-06). - `GET /quest_logs/{username}` — quest action history (start, complete) - `GET /planets_new/{username}` — planet exploration state and Favor balance - `GET /battle?limit=100&offset=1&maxDefense=50` — potential battle targets - `GET /leaderboard?limit=200&offset=1` — ranked player list - `GET /stats` — aggregate game statistics - `GET /daily_stats` — time-series statistics by day - `GET /crate_price` — oracle-adjusted crate prices; returns `price` (common SCRAP cost), `scrap_usd`, `uncommon_crate_usd`, `rare_crate_usd`, `epic_crate_usd` (USD targets); client computes non-common costs as `Math.ceil(usd_target / scrap_usd)` - `GET /marketplace/listings/{type}` — active listings (`items`, `crates`, `relics`, `consumables`) - `GET /battle_logs/{username}` — battle history - `GET /claim_logs/{username}` — SCRAP claim history - `GET /boss_logs/{username}` — boss fight results ## Blockchain Network: HIVE L1 + Hive Engine sidechain Main game account: `@terracore` Marketplace account: `@terracore.market` Tokens: SCRAP (mine/earn token), FLUX (premium action token) — both on Hive Engine Block time: ~3 seconds Transaction fees: zero (HIVE resource credits) All player actions are broadcast as `custom_json` operations to HIVE. The Smart Contract processes them in the same block cycle. ### Key Authority Levels - **Posting key** — low-risk actions: claim, battle, equip, unequip, open crate, use consumable, quest collect - **Active key** — token transfers and irreversible actions: salvage, combine, marketplace list/unlist/transfer, buy from marketplace, upgrades, boss fights, quest start ### Direct custom_json Operation IDs - `terracore_claim` — claim accumulated SCRAP - `terracore_battle` — attack a target player - `terracore_equip` / `terracore_unequip` — equip or remove NFT items - `terracore_open_crate` — open a crate NFT - `terracore_salvage` — destroy an item for SCRAP - `terracore_combine` — combine 100 relics into a crate - `terracore_use_consumable` — use a consumable item - `terracore_quest_collect` — collect a completed quest (posting key); json payload: `{ "quest_id": "" }` - `tm_create` — list an NFT on the marketplace - `tm_cancel` — remove a listing - `tm_transfer` — transfer an NFT to another player ### Hive Engine Token Operations (id: `ssc-mainnet-hive`) These encode the action in the `memo` field of a token transfer: - SCRAP → `null`: stat upgrades (`terracore_engineering-`, `terracore_damage-`, `terracore_defense-`), favor contributions, crate purchases (`tm_buy_crate--` where rarity is `common`, `uncommon`, `rare`, or `epic`; legendary is not purchasable), quest starts (`terracore_quest_start---` where quest_type is `combat`, `salvage`, `stealth`, `fortune`, or `defense` and tier is `1`–`5`; SCRAP amount must match oracle-adjusted cost within 1% tolerance). Quest base costs (before oracle): T1=20, T2=100, T3=235, T4=985, T5=4010 SCRAP. An underpaid start is rejected and the SCRAP is not refunded — read `scrap_cost` from `/quest_board` rather than computing it, and only start a quest whose `template_id` is on the board returned by `/quest_board` for the current UTC date. Base draws per quest: T1=2, T2=3, T3=4, T4=6, T5=10. - FLUX → `null`: boss fights (memo is a JSON object with `hash` and `planet`) - FLUX → `@terracore`: item forge/upgrade. Memo is a plain string `terracore_forge-` identifying the item to upgrade; appending the item's current level (`terracore_forge--`) is recommended for a unique, self-describing memo but is not required. Replay-dedup is keyed server-side on the Hive Engine transaction id, so each transfer is processed exactly once regardless of memo content. - HIVE → `@terracore.market`: buy marketplace listing (memo is a JSON string with action, item details, buyer, seller) Full operation payloads: https://www.terracoregame.com/wiki/developers/