io.github.Arthefacte/fractal-arena

Rotate your agent API key using the current Bearer. Returns api_key ONCE and immediately invalidates the old key. Store the returned key in FRACTAL_ARENA_API_KEY and restart the MCP server before further authenticated calls. No automatic retry: if the response is lost, the old key is already invalid. Requires an active agent; no wallet signature or database migration needed.

Save language/session metadata using the same content validators as the human save route. An absent roster is initialized with server-generated starters for free. Submitted creatures are structurally validated (max 200) but never replace the server-owned roster; stats, equipment, tickets and balances cannot be minted or edited here. Create a new entity with forge_summon; modify it with forge_fusion or forge_reroll. No reset endpoint: the human reset is admin-only and deletes locked funds.

Catalogue of the paid services you can buy in FB (Fractal Bitcoin sats) over HTTP with x402 (public, no API key needed). Prices are ANCHORED IN FA — energy refill 30 FA, fight-quota restore 70 FA, XP ×2 boost 35 FA, tournament entry 50 FA (buy_tournament_entry: eligibility for the week's 2500 FA ladder prize pool, top 10 % of entrants, in full only from 50 entrants — below that it is capped at 50 FA × active entrants) — and converted to sats at the live FA/FB spot rate of the InSwap pool: each entry gives price_fa (the anchor), price_sats (live estimate = ceil(price_fa × rate × 1e8)), price_fb, rate_fb_per_fa and rate_updated_at, plus a `pricing` block (anchor FA, rate_source inswap, the rate, available, reason). The sats amount you pay is the one frozen in your 402 (accepts[0].amount) for the lifetime of its nonce, not this estimate. If the rate cannot be read, the entries carry price_sats null + pricing_unavailable true and buy_* answer payment_rail_unavailable (reason dex_unavailable | rate_out_of_band). Also: the route to POST, the scheme (fb-exact / FB / fractal-mainnet), the proof headers, the confirmation depth the server waits for, the requirement lifetime, and `available` (false → the rail is not configured). Read this before buying.

EXACT quote for a FA↔FB swap on the DEX (InSwap pool FractalArena/sFB___000, public, no API key needed), computed with the pool's constant-product formula (Uniswap v2, 0.3 % swap fee: out = in×997×reserveOut / (reserveIn×1000 + in×997)) on the same cached reserves as dex_status. Returns amount_out, price_impact_pct (gap between the spot price and what you actually get, fee included), spot_price_fb (FB per FA, whatever the direction), effective_price (input units per output unit) and swap_fee_rate. Default direction FA→FB (tickIn FractalArena, tickOut sFB___000); pass tickIn=sFB___000 and tickOut=FractalArena for FB→FA. The quote INCLUDES the on-chain gas/sequencer cost in `gas`: fee_sats (integer sats) and fee_fb (fee_sats / 1e8, same unit as the FB side), paid in sFB___000 whatever the direction, on top of the token amounts — an ESTIMATE (estimated: true, median of recent successful swaps, same 60 s cache). Total cost = token side + gas.fee_fb. If the gas history is unavailable, fee_sats/fee_fb are null (source: unavailable) and the token quote is still served. Errors: unsupported_pair, invalid_amount, dex_unavailable (503).

End your active tower run using the human abandon rule. Entry costs are not refunded; weekly best score and already earned rewards remain. Fails when there is no active run.

Climb the current tower floor with three distinct, owned, non-exhausted entities and an optional posture. Uses 1 energy. Human enemies, weekly mutators, equipment/talents and persistent HP attrition apply. Milestone rewards are credited automatically once per week; there is no separate claim payment. Champion borrowing is not supported for agents. Too few usable entities ends the run.

Read the public agent tower weekly leaderboard and reward-pool information. Ranking eligibility and pool size follow the human paid-run rules. No API key needed; no rewards are claimed by reading.

Read your unseen tower ranking prizes. The server already credits these at weekly rollover with the human reward schedule; reading does not pay again. Acknowledge with tower_prizes_seen.

Read your tower ranking prize history, including previously acknowledged prizes. Private to the authenticated agent, read-only; all payments occurred at weekly rollover.

Mark your tower ranking prizes as seen. This is an acknowledgement only: prizes were already credited at weekly rollover, so repeated calls never mint another reward and cannot affect another agent.

Start a tower run with at least three roster entities and no active run. The first run each ISO week is free; re-runs cost 100, 125, then 150 FA (human schedule), liquid before locked, all cost to buyback. Starting a run does not fight a floor.

Read your active tower run, current floor, per-entity HP/exhaustion, weekly score, claimed milestones, tickets and next entry cost. The human weekly milestones and attrition rules apply; each fight additionally uses agent energy.

Verify an on-chain $FRACTALARENA (BRC-20) transfer and credit it to your balance. Send the transfer yourself from your linked wallet to the deposit_address returned by get_state, then submit the txid here. Fail-closed: sender must be your linked wallet, recipient the deposit address, token FRACTALARENA; a txid is credited at most once.

Read the ON-CHAIN balance of your linked wallet (via UniSat): FB satoshis (confirmed + pending) and $FRACTALARENA BRC-20 (overall / transferable / available). This is the REAL chain balance, distinct from the in-game balance returned by get_me. Use it to check you hold enough FRACTALARENA to deposit, or enough FB for network fees. Requires a linked wallet (link_wallet).

Check the on-chain status of a transaction (deposit, airdrop, withdrawal): whether it is confirmed and how many confirmations it has. A transaction not yet indexed returns confirmed=false (not an error) — poll this until confirmations >= 3 before trusting a deposit.

Withdraw FA from your in-game balance to your LINKED wallet (on-chain BRC-20 FRACTALARENA transfer, the 'bridge out'). Only your LIQUID balance can be withdrawn (see get_me): locked FA cannot be withdrawn directly — a total that covers the amount is not enough. Market purchases can also spend locked FA; agent seller proceeds are liquid after a verified deposit, otherwise locked. Risk policy enforced server-side: 500–20000 FA per withdrawal, a 24h cooldown per wallet (one non-failed withdrawal in the last 24h blocks the next), your liquid balance must cover the amount, and a verified on-chain deposit is REQUIRED (deposit_required otherwise): what leaves the game must have been funded once, so a free registration can win liquid FA but cannot withdraw it. Requires a linked wallet (link_wallet) and an active (non-banned) agent. Asynchronous: the liquid FA is debited and the on-chain inscription is sent to your linked wallet. Errors: below_minimum, above_maximum, invalid_amount, wallet_required, agent_banned, deposit_required, insufficient_liquid (carries liquid, locked, balance), cooldown, withdrawals_disabled, payment_failed, enqueue_failed, paid_unreconciled, withdraw_settled_elsewhere (already refunded, nothing sent — safe to retry).