# The Floor — companion dashboard for $FLOOR (Robinhood Chain)

> Unofficial, fan-built companion. Read-only JSON, no auth, CORS open.
> This is the GAME-SEMANTIC layer: desks, alpha, operators, firms, emissions, reinvest-vs-dump.
> For raw chain data (any tx/address/block) use a block explorer instead.

## Agent endpoint
- MCP (streamable HTTP): `/mcp` — add as an MCP server; tools are self-describing via tools/list.
- Discovery (JSON): `/api`
- Open source (MIT): https://github.com/Domirep/thefloor-dashboard — no custody, unsigned-calldata writes, threat model in SECURITY.md

## Deciding what to do (the MCP won't decide for you)
- These tools give an agent the ABILITY to read state and prepare transactions — they don't make the
  moves. To play well, read the numbers and reason. `get_strategy(address)` does the game math for you:
  FLOOR/day, uncollected PnL, seat/bandwidth headroom, next-upgrade cost + what it unlocks, per-operator
  payback in days at the current emission rate, and the halving countdown. It returns facts + paybacks,
  not "buy now" — the choice is the agent's.
- Rough loop most players run: open desk → recruit a starter → collectPnL when PnL is worth the gas →
  reinvest into the operator with the lowest payback that fits your free bandwidth → upgrade the desk when
  you're seat/bandwidth-capped → repeat. Emissions halve every 30 days, so earlier reinvestment compounds.

## Buying FLOOR (you need it to recruit/upgrade)
- Swap on Robinhood Chain's Uniswap V3: router 0xcaf681a66d020601342297493863e78c959e5cb2 (SwapRouter02), WETH 0x0bd7d308f8e1639fab988df18a8011f41eacad73,
  FLOOR/WETH pool 0x73ed66f4e5e7e59e279cab050074bfeaec5c55a2 at the 1% fee tier. `get_swap_info` returns the live price.
- Flow: `prepare_wrap_eth` (ETH→WETH) → approve WETH to the router (`prepare_swap_eth_for_floor`
  includes it) → `prepare_swap_eth_for_floor` (exactInputSingle). amountOutMinimum is quoted live from
  the pool minus your slippage. The pool is thin — big buys fill badly; keep them small.

## Playing the game from an agent
- `prepare_create_desk` builds the UNSIGNED transaction to open a desk. It returns {to, value, data};
  you sign with your own wallet. This server holds no keys, asks for no keys, and broadcasts nothing.
  **Never send a private key to this or any API.**
- Desk creation costs 0.01 ETH. Verify the amount yourself before signing — don't take this API's word.
- The recruiter is written on-chain at creation and can NEVER be changed. It defaults to this dashboard's
  address, which then earns 5% of what that wallet later spends (paid from the game treasury, so it costs
  the player nothing). The referrer is returned explicitly in the response — surface it to the human
  before they sign, and pass `referrer` to override or 0x0…0 to opt out.

## Conventions (read this before trusting a number)
- FLOOR amounts are HUMAN units (already /1e18). Fields ending _raw are wei-scale.
- Addresses are lowercase hex; compare case-insensitively.
- `ageMs` = ms since last refresh. This data is cached, not live-per-request.
- **`null` means UNKNOWN, never zero.** If `partial:true`, some upstream failed — read `unknownFields`
  and do NOT report those as 0. Zero and "we couldn't find out" are different claims.

## Endpoints
- `/api/summary` — One call: price, supply, burned, emissions, players, behavior split, freshness. Start here.
- `/api/token-stats` — Token + game economy: price, supply, burned, emission rate, global alpha, halving.
- `/api/player?addr=0x…` — One wallet: desk tier, alpha, share, pending PnL, balance, seated roster.
- `/api/leaderboard` — Wallets ranked by alpha, plus top recruiters.
- `/api/behavior` — Desk owners vs traders: reinvested / sold / bought, with router flow and liquidity separated out.
- `/api/distribution` — Desk-tier spread and alpha concentration.
- `/api/holders` — Top FLOOR holders.
- `/api/firms` — Firms, members, and free agents.
- `/api/firm-competition` — Weekly firm PnL competition mirrored from the official game: standings ranked by PnL, prize pool, and projected 65/25/10 payouts. PnL is indexed off-chain, not on-chain-verifiable.
- `/api/scouting` — Free agents (desk owners not in a firm) with recruiting signals: alpha, FLOOR accumulation, reinvest rate. A free on-chain firepower proxy, not the competition PnL.
- `/api/live-actions` — Recent on-chain game actions (collect/claim/seat/recruit/upgrade/newdesk/referral/firmburn).
- `/api/history` — Daily snapshots for trends. Rows before tracking began are reconstructed and marked seeded:true.
- `/api/brokers` — StonkBrokers (same chain, different game): mint/holders, activation tiers, dividend rounds, $STONKBROKER burns + price.
- `/api/broker?id=1-4444` — One StonkBroker: owner, ERC-6551 wallet holdings, dividends received, activation tier, Floor-desk status, on-chain art.
- `/api/broker-leaderboard` — Activated brokers ranked by current wallet contents (a removable snapshot — only activation tier + any Floor desk are bound to the NFT). Not an appraisal.

## Contracts
- FLOOR token: 0x0000000000000000000000000000000000000000
- Game:        0x89d40f5e4d260577691d05e681d47519eb44f113
- Firm:        0x26c615b58cf162a00ed5ae009e16ed8ab4265b36
- FLOOR/WETH pool (Uniswap V3): 0x73ed66f4e5e7e59e279cab050074bfeaec5c55a2

## StonkBrokers (second game covered, same chain)
- Clutch Markets' 4444 ERC-6551 broker NFTs: each owns a wallet seeded with a tokenized stock and
  earns stock dividends when activated. `/api/brokers` = collection stats, `/api/broker?id=N` = one broker.
- MCP tools: get_brokers, get_broker, get_broker_leaderboard (contents ranking — removable
  snapshot, not an appraisal), get_broker_activation_math (fee/share/payback facts),
  prepare_activate_broker (approve + activate, unsigned).
- **The 6551 wallet is a general on-chain account** — any asset it holds or position it takes on
  this chain travels with the NFT when it changes hands. The Floor desk below is the worked
  example, not the limit.
- **Cross-game:** a broker's ERC-6551 wallet can PLAY THE FLOOR — get_broker_floor_status,
  prepare_broker_floor_desk (the wallet opens its own desk), prepare_broker_floor_collect. Why it
  matters: Floor desks are permanently bound to their wallet (there is NO other way to transfer or
  sell a position) — so a broker-desk is the only sellable Floor position, and the broker gains a
  second income stream. BINDING RULE (state this whenever value comes up): a paid activation is
  CLEARED by the NFT's transfer hook on every ownership change — it does NOT survive a sale, the
  buyer re-activates; a Floor desk lives on the broker's 6551 wallet and DOES survive transfers;
  liquid wallet contents — stocks, tokens, operator NFTs, ETH — remain removable by the current
  owner right up to a sale. Verify contents at purchase time. Verified against both games'
  contracts; no broker wallet has a desk yet (as of 2026-07-19).
- **This flow is MCP-ONLY and VERIFICATION-GATED by design.** No website ever builds or submits
  these transactions. The broker prepare_* tools ERROR with no calldata unless every check passes
  live on-chain: the broker is ACTIVATED (a desk is a perk of activated brokers — activate first),
  from == ownerOf, desk state readable and correct, live quote, allowance. An error means "not
  verified" — surface it, don't work around it.
- Why a broker-desk is worth having (facts, not price promises): the desk survives transfers, so
  it's the one Floor position a buyer can actually receive; it adds a second income stream (FLOOR
  emissions) beside the stock drops; earnings accrue inside the NFT instead of scattering across
  wallets; and any future owner — human or agent — can verify the desk on-chain before buying.
- NFT 0x539cdd042c2f3d93ebc5be7dfff0c79f3b4fabf0 · $STONKBROKER 0xe934e36a439c94017b64a3fece66af12099abf50 · dashboard page: `/brokers`

## Gotchas that will bite an agent
- "Sell volume" is NOT every transfer into the pool: liquidity adds land there too, and ~68% of real
  swap volume arrives from routers/bots, not humans. /api/behavior separates player / trader / routed
  / liquidity so you don't mistake an LP deposit for a dump.
- A wallet's recruiter is fixed forever at desk creation; it can never be changed or backfilled.
- Burned can exceed current supply (burns reduce supply), so burnedPct > 100% is normal, not a bug.