> For the complete documentation index, see [llms.txt](https://docs.trover.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trover.tech/engineering/claims-fees-and-operations.md). # Claims, fees, and internal operations ## Internal panel The panel is available at `/internal` and is intentionally absent from public navigation. Set a long, random `ADMIN_API_KEY`; this is the code an operator enters. The browser keeps it in memory for the current tab only. Every admin API request is checked server-side with a constant-time comparison. Unlocking the panel does not authorize fund movement. An operator separately connects the wallet authorized by the production multisig. A claim snapshot reads the current holder list from Robinhood Chain Blockscout, verifies both ERC-20 contracts over RPC, applies the minimum raw balance, excludes burn/scam/contract addresses by default, and saves an immutable manifest plus a proof for each wallet. Every proof commits to the chain, distributor, tranche, index, wallet, stock token, and raw amount. The operator signs four explicit stages: stock-token authorization, tranche creation, distributor funding, and activation. There is no per-recipient push loop and no “sign all” action. The API publishes a tranche only after its onchain root, manifest hash, token, allocation, and active state match. `AIRDROP_MAX_RECIPIENTS` is a hard snapshot limit. The API fails closed if the holder list is larger, rather than silently distributing to a partial list. The detailed invariants and deployment gates are in [claim-system-design.md](/engineering/claim-system-design.md). ## Rescue and monitoring Every ETH-holding contract in the stack (ETH distributor, league vault, revenue router, fee executor, X claim escrow) has a pause and a recovery path, and every path is exercised by `packages/contracts/test/TroverRescuePaths.test.ts` and the testnet rehearsal. An operator never calls them by hand: the Safe transaction is built on any machine, signed on each owner's machine and executed with any funded key through `packages/contracts/scripts/safe-rescue.mjs` (`build`, `sign`, `exec`); each `build` prints the on-chain value it will change. The situation-to-command table and the mainnet checklist are in [contracts-runbook.md](/engineering/contracts-runbook.md). The worker's `contract-balance-watch` job (every 10 minutes, `apps/worker/src/contract-watch.ts`) reads each configured address: balance, `router.totalOwed`, `league.totalAttributed`, `eth.reservedByToken`, paused state; it exports `trover_contract_balance_eth{contract}` and logs a warning naming the runbook when anything is owed, unattributed above `CONTRACT_BALANCE_ALERT_ETH`, or paused. It is a no-op until the stack addresses are set in the server `.env` after the mainnet run. ## User portfolios The account and Claim pages combine exact confirmed historical distribution receipts and `Claimed` events. They display only active allowlisted Robinhood stock tokens with a positive current balance. Logos come from the official Robinhood asset registry, and USD values are only shown from fresh, unpaused price feeds. ## Platform fee `PLATFORM_FEE_BPS=50` is the configured 0.5% bot-trade fee. The current generic Uniswap routes do not expose a verified atomic app-fee field, so they submit the full requested swap and do not charge a standalone follow-up fee transaction. The setting becomes collectible only on a route that can include the fee in the same authorized transaction. Failed swaps are never charged. Confirmed fees are recorded in `trade_fees` and reconciled before entering the treasury ledger. Set: ```dotenv PLATFORM_FEE_BPS=50 PLATFORM_FEE_WALLET=0x4b14412a1cb6f30622f25A6706Ff26ec953Ec486 ``` ## Holder revenue-share cycle Trover's holder revenue-share is a stock-token claim program, not a promise of yield and not an automatic payment from the claim contract. The worker and the distributor have separate roles: 1. Confirmed bot fees are recorded in the treasury ledger. 2. The optional Trover token-fee receiver watches newly received `USDG` and native `ETH`. It retains the configured gas reserve and sweeps only the configured percentage of newly observed receipts to the treasury wallet. 3. Bot fees and Trover token-fee receipts each maintain an independent `$2,000` threshold counter. Completing either source's threshold opens one immutable treasury-buyback batch. The default batch allocation is 20% (`$400`) and the remaining amount remains in the treasury. Revenue from the two sources is never combined to cross a threshold. 4. The worker chooses five random eligible Robinhood stock tokens, buys them using the treasury wallet, and records every quote, transaction, receipt, and final allocation. 5. Once approved stock-token balances are funded, the operator/automation produces a holder snapshot and Merkle manifest. Holders with at least **0.008% of the then-current Trover token supply** are eligible. Every purchased stock token is then allocated pro-rata by each eligible wallet's share of the total TROVER held by all eligible wallets in that snapshot. A funded `TroverStockDistributor` tranche makes those exact wallet-specific amounts claimable. 6. Each holder claims directly from the distributor with their own wallet. The website may submit that user-owned claim, but it never controls the holder's private key or marks an entitlement paid before the onchain `Claimed` event. The claim contract does not buy stocks, convert ETH, select recipients, or hold an operator private key. It enforces only the activated tranche's Merkle root, token allocation, and one-time claim state. This keeps purchase routing and treasury operations auditable offchain, while keeping eligibility and payout finality onchain. Snapshot construction is automated backend work: Blockscout supplies one complete holder-page snapshot and RPC supplies total supply plus a contemporaneous block marker for its audit record. These are read-only requests and consume no onchain gas. The contract never takes or fetches a snapshot. Gas is required only when the automation manager creates/activates a tranche and when the treasury funds the distributor with the purchased stock token. Those signer wallets must hold enough native ETH; the distributor contract itself does not need an ETH balance for snapshotting. The worker preflights signer gas and waits when the treasury gas reserve is below the configured floor; it does not silently move user funds or auto-top-up a signer. Official, on-chain-verified, policy-allowed Robinhood stock tokens are supported without requiring optional Blockscout, market-data, or route-provider evidence. Treasury selection additionally requires a healthy price or a verified live quote. `GOOG`, `GOOGL`, `PLTR`, and `NVDA` are excluded from treasury baskets by default. A route, token, quote, simulation, confirmation, or receipt failure stops that batch; it does not silently substitute an asset. ## Automated treasury buying The treasury buyer runs only when `TREASURY_BUY_ENABLED=true`. For every full `TREASURY_BUY_THRESHOLD_USDG` tranche of confirmed, unspent USDG-denominated fees, it allocates `TREASURY_BUYBACK_PERCENT` to a randomized set of active, canonical, policy-allowed, price-healthy stock tokens. Denied, paused, stale, or delisted tokens cannot be selected. Recommended signing configuration: ```dotenv TREASURY_WALLET_ADDRESS=0x4b14412a1cb6f30622f25A6706Ff26ec953Ec486 TREASURY_PRIVY_WALLET_ID= TREASURY_BUY_ENABLED=true TREASURY_BUY_THRESHOLD_USDG=2000 TREASURY_BUYBACK_PERCENT=20 TREASURY_BUYBACK_TARGET_COUNT=5 ``` If a self-custody environment signer is required, the exact variable name is: ```dotenv FEE_ACCUMULATOR_PRIVATE_KEY=0x<64 hex characters> ``` It is read by the worker only. Never prefix it with `NEXT_PUBLIC_`, place it in frontend hosting variables, log it, or commit it. The worker verifies that the derived address matches `TREASURY_WALLET_ADDRESS` before signing. A managed signer or secret vault is still preferred in production. The token-fee receiver is distinct from the platform-fee treasury. Configure it only when the private key corresponds exactly to the receiver address: ```dotenv TOKEN_FEE_ACCUMULATOR_WALLET_ADDRESS= TOKEN_FEE_ACCUMULATOR_PRIVATE_KEY=0x<64 hex characters> TOKEN_FEE_ALLOWED_ASSETS=USDG,ETH TOKEN_FEE_BUY_ENABLED=true TOKEN_FEE_BUYBACK_PERCENT=20 TOKEN_FEE_GAS_RESERVE_ETH=0.001 TREASURY_BUY_ENABLED=true TREASURY_BUY_THRESHOLD_USDG=2000 TREASURY_BUYBACK_PERCENT=20 TREASURY_BUYBACK_TARGET_COUNT=5 TREASURY_DENIED_STOCK_SYMBOLS=GOOG,GOOGL,PLTR,NVDA ``` This receiver is only for the final Trover token's configured fee stream. It does not inspect or sweep the individual fee wallets of tokens launched by X users; those creator fees remain with each deployer's connected wallet. Keep both `TOKEN_FEE_BUY_ENABLED` and `TREASURY_BUY_ENABLED` false until the treasury wallet, stock registry, deployed distributor, Trover token address, and claim configuration have been independently verified. These settings do not bypass distributor pause/withdrawal authority or a Safe/multisig proposal where the deployment requires one. The worker is deliberately armed-but-idle before launch: it will not sweep, buy, or create stock tranches unless all of the following are present: ```dotenv TREASURY_WALLET_ADDRESS= TREASURY_PRIVY_WALLET_ID= # or FEE_ACCUMULATOR_PRIVATE_KEY CLAIM_DISTRIBUTOR_ADDRESS= CLAIM_AUTOMATION_MANAGER_ADDRESS= CLAIM_AUTOMATION_PRIVATE_KEY= AUTO_STOCK_CLAIMS_ENABLED=true TREASURY_BUY_ENABLED=true ``` After the protected admin endpoint saves the final Trover token address and its `0.008` minimum-holder percentage, the next scheduled run can process a complete $2,000 USD threshold: select five permitted stocks, submit purchases, build pro-rata snapshot entitlements, use the configured gas-funded signers to fund the distributor, and activate the Merkle tranches. ## X credit protection The default configuration makes no scheduled X REST calls: ```dotenv ENABLE_POLLING_FALLBACK=false ENABLE_MARKET_RADAR=false ENABLE_X_SEARCH_BACKFILL=false ENABLE_X_THREAD_BACKFILL=false ``` The bot account is `@troveragent` (`BOT_X_USERNAME`, `PROJECT_X_USERNAME`; setup in [x-agent-setup.md](/engineering/x-agent-setup.md)). Mention processing is event-driven and non-mention Posts are ignored before analysis. The internal panel calls X's Usage endpoint only when an operator presses “check usage now.” X Account Activity's `/all` subscription cannot be narrowed to mentions at the subscription level; X may still deliver and bill other account events even though Trover ignores them. For a strict mention-only X bill, replace Account Activity with an X filtered-stream rule for the bot handle or remove the Account Activity subscription. Review the exact remaining credit balance and non-Post charges in the X Developer Console. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.trover.tech/engineering/claims-fees-and-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.