Fomo3d

Fomo3D — BNB Chain Blockchain Game

Fomo3D is a decentralized game on BNB Chain (BSC) with three game modes:

1. Fomo3D Main Game — Buy shares with tokens. Each purchase resets a countdown timer. The last buyer when the timer hits zero wins the grand prize pool. All shareholders earn dividends from each purchase.

2. Slot Machine — Bet tokens for a VRF-powered random spin. Matching symbols win multiplied payouts (up to 100x). Depositors earn dividend shares from every spin.

3. Prediction Market — Bet on the outcome of events (Yes/No/Draw). Markets use either Oracle (Chainlink price feeds) or Optimistic (human proposal + challenge) settlement. Bettors earn dividends from other bets on the same market, and winners share the prize pool.

Installation and Config (required)

Ensure dependencies are installed at repo root (npm install).

A private key is required. If the user has not configured the skill yet, run fomo3d setup from the repo root. This runs an interactive CLI that prompts for:

• BSC private key (for signing transactions)
• Network (testnet or mainnet)
• Optional custom RPC URL

Alternatively, set environment variables (no setup needed):

• FOMO3D_PRIVATE_KEY — BSC wallet private key (hex, with or without 0x prefix)
• FOMO3D_NETWORK — testnet or mainnet (default: testnet)
• FOMO3D_RPC_URL — custom RPC endpoint (optional)
• FOMO3D_FLAP_TOKEN — override FLAP token address for buy/sell commands (optional, for testing)

Important: The wallet must be an EOA (externally owned account), not a smart contract wallet. The game contracts require msg.sender == tx.origin.

How to run (CLI)

Run from the repo root (where package.json lives). For machine-readable output, always append --json. The CLI prints JSON to stdout in --json mode.

fomo3d <command> [options] --json

On error the CLI prints {"success":false,"error":"message"} to stdout and exits with code 1. On success the CLI prints {"success":true,"data":{...}}.

Important Concepts

Token Amounts

All token amounts in CLI arguments and JSON output are in wei (18 decimals). For example:

• 1 token = 1000000000000000000 (1e18)
• 0.5 tokens = 500000000000000000 (5e17)

When displaying amounts to users, divide by 1e18 for human-readable values.

Share Amounts

Share amounts for purchase --shares are integers (not wei). 1 share = 1 share.

Auto-Approve

The CLI automatically checks ERC20 token allowance and approves if needed before purchase, buy, sell, slot spin, slot deposit, pred bet, pred propose, and pred dispute. No manual approval step required.

FOMO Token Trading

The FOMO token is launched on the FLAP platform (BNB Chain bonding curve). Trading uses BNB as the quote token:

• 内盘 (Portal): Directly calls FLAP Portal's swapExactInput with native BNB
• 外盘 (PancakeSwap V2): After the token graduates to DEX, uses PancakeSwap V2 Router

The CLI auto-detects the current phase via getTokenV6 and routes accordingly. Buy/sell commands work on both testnet and mainnet.

VRF (Verifiable Random Function)

Slot machine spins use Binance Oracle VRF for provably fair randomness. Each spin requires a small BNB fee (~0.00015 BNB) sent as msg.value. The spin result is determined by a VRF callback (1-3 blocks later) — the CLI returns the spin request transaction, not the result. Check the result with fomo3d slot status or fomo3d player afterward.

Commands Reference

Setup

fomo3d setup --json

Interactive configuration. Prompts for private key, network, and optional RPC URL. Saves to config.json.

Wallet — Check Balances

fomo3d wallet --json

Returns BNB balance and game token balance for the configured wallet.

Output fields: address, bnbBalance (wei), tokenBalance (wei), tokenSymbol, tokenDecimals

Status — Game Round Info

fomo3d status --json

Returns current round status including countdown, prize pools, share price, and last buyers.

Output fields: currentRound, roundStatus (NotStarted/Active/Ended), paused, countdownRemaining (seconds), grandPrizePool (wei), dividendPool (wei), sharePrice (wei), totalShares, lastBuyers (address[]), pools

Strategy tip: When countdownRemaining is low, buying shares has higher expected value because you may win the grand prize. Each purchase resets the countdown by a fixed increment.

Player — Player Info

fomo3d player --json
fomo3d player --address 0x1234... --json

Returns player's shares, earnings, and pending withdrawals. Without --address, uses the configured wallet.

Output fields: address, shares, totalEarnings (wei), pendingEarnings (wei), pendingWithdrawal (wei), hasExited, currentRound

Decision guide:

• If pendingWithdrawal > 0: Must run fomo3d settle before purchasing more shares
• If pendingEarnings > 0 and round is active: Can exit to lock in earnings, or hold for more dividends
• If hasExited == true: Already exited this round, wait for round to end or settle

Purchase — Buy Shares

fomo3d purchase --shares <integer> --json

Buy shares in the current round. The --shares value is an integer count (not wei). Token cost = shares × sharePrice (auto-calculated).

Pre-checks performed automatically:

• Game must not be paused
• No pending withdrawal (must settle first)
• Token approval (auto-approved if needed)

Output fields: txHash, blockNumber, status, sharesAmount, tokensCost (wei)

Exit — Exit Game

fomo3d exit --json

Exit the current round and lock in your dividend earnings.

Output fields: txHash, blockNumber, status

Settle — Claim Dividends & Prize

fomo3d settle --json

Settle dividends and claim any grand prize after a round ends. Must be called if pendingEarnings > 0 or pendingWithdrawal > 0.

Output fields: txHash, blockNumber, status, pendingEarnings (wei), pendingWithdrawal (wei)

End Round — End Expired Round

fomo3d end-round --json

End a round whose countdown has reached zero. Anyone can call this. The grand prize is distributed to the last buyer.

Output fields: txHash, blockNumber, status

Faucet — Claim Test Tokens (testnet only)

fomo3d faucet --json

Claim 10000 test FOMO game tokens on BSC Testnet. Rate limited to 1 claim per address per hour.

Output fields: txHash, amount, token, account

Buy — Buy FOMO with BNB

fomo3d buy --amount <bnb_amount_in_wei> --json

Buy FOMO tokens using BNB via the FLAP platform. Auto-detects market phase: Portal (内盘) or PancakeSwap V2 (外盘).

Example: Buy with 0.01 BNB:

fomo3d buy --amount 10000000000000000 --json

Output fields: txHash, blockNumber, status, bnbSpent (wei), token, market

Note: Buy and sell commands use minOutputAmount=0 (no slippage protection). For large trades, consider splitting into smaller amounts.

Sell — Sell FOMO for BNB

# 按数量卖出
fomo3d sell --amount <token_amount_in_wei> --json

# 按持仓比例卖出
fomo3d sell --percent <bps> --json

Sell FOMO tokens for BNB. Two modes:

• --amount: Sell exact token amount (in wei, 18 decimals)
• --percent: Sell by percentage of holdings in basis points (10000=100%, 5000=50%, 1000=10%)

Cannot use both flags simultaneously. Token allowance is auto-approved for Portal/PancakeSwap.

Example: Sell 50% of holdings:

fomo3d sell --percent 5000 --json

Output fields: txHash, blockNumber, status, tokensSold (wei), market, method

Token Info — Token Status & Balances

fomo3d token-info --json
fomo3d token-info --address 0x1234... --json

Query FOMO token status on the FLAP platform and balances. Works without private key (shows token status only). Supports --address flag to check another wallet.

Output fields: token, network, portal, status (Invalid/Tradable/InDuel/Killed/DEX/Staged), phase (内盘/外盘), quoteToken, price (wei), reserve (wei), circulatingSupply (wei), taxRate, progress (wei), fomoBalance (wei), bnbBalance (wei), account

Decision guide:

• status == Tradable: Token is on 内盘 (bonding curve), buy/sell via Portal
• status == DEX: Token has graduated to 外盘 (PancakeSwap), buy/sell via DEX
• progress: How close to graduation (higher = closer to DEX)

Slot Status — Slot Machine Info

fomo3d slot status --json

Returns slot machine configuration, prize pool, and statistics.

Output fields: paused, token, minBet (wei), maxBet (wei), prizePool (wei), totalShares, vrfFee (wei), stats { totalSpins, totalBetAmount, totalWinAmount, totalDividendsDistributed }

Note: maxBet = prizePool / 100 (dynamic). If prize pool is low, max bet is low.

Slot Spin — Spin the Slot Machine

fomo3d slot spin --bet <amount_in_wei> --json

Spin the slot machine. Requires token balance for the bet AND BNB for VRF fee (~0.00015 BNB).

Constraints:

• minBet <= bet <= maxBet
• Wallet must have enough BNB for VRF fee
• Cannot spin while a previous spin is pending

Payout table:

Output fields: txHash, blockNumber, status, betAmount (wei), vrfFee (wei), note

Important: The spin result is NOT in this response. The VRF callback determines the outcome 1-3 blocks later. Check fomo3d player --json or fomo3d slot status --json afterward.

Slot Cancel — Cancel Timed-Out Spin

fomo3d slot cancel --json

Cancel a spin that timed out waiting for VRF callback. Only needed if VRF fails to respond.

Output fields: txHash, blockNumber, status

Slot Deposit — Deposit to Prize Pool

fomo3d slot deposit --amount <amount_in_wei> --json

Deposit tokens into the slot machine prize pool. WARNING: Deposited tokens are permanently locked. You receive dividend shares in return — each spin distributes 5% of the bet amount to all depositors proportionally.

Output fields: txHash, blockNumber, status, amount (wei)

Slot Claim — Claim Slot Dividends

fomo3d slot claim --json

Claim accumulated dividends from slot machine deposits.

Output fields: txHash, blockNumber, status, dividends (wei)

Pred Config — Prediction Market Config

fomo3d pred config --json

Returns global prediction market configuration.

Output fields: network, diamond, token, minBet (wei), devFeeBps, creatorFeeBps, dividendBps, nextMarketId, totalMarkets, paused, minDuration (seconds)

Pred Market — Market Details

fomo3d pred market --id <marketId> --json

Returns detailed info for a specific prediction market.

Output fields: marketId, title, creator, status (Active/Closed/Resolved), outcome (Yes/No/Draw, only when Resolved), settlementType (Oracle/Optimistic), drawEnabled, endTime, timeRemaining (seconds), prizePool (wei), totalYesShares (wei), totalNoShares (wei), totalDrawShares (wei), totalShares (wei), totalBets, totalBetAmount (wei), totalDividendsDistributed (wei), metadataURI

Decision guide:

• status == Active: Market is open for betting
• status == Closed: Market ended, waiting for settlement
• status == Resolved: Settlement complete, winners can pred claim
• timeRemaining == 0: Market has ended, needs settlement

Pred Position — Player Position

fomo3d pred position --id <marketId> --json
fomo3d pred position --id <marketId> --address 0x1234... --json

Returns player's position in a specific market. Without --address, uses the configured wallet.

Output fields: marketId, player, yesShares (wei), noShares (wei), drawShares (wei), pendingYesDividends (wei), pendingNoDividends (wei), pendingDrawDividends (wei), estimatedPrizeIfYes (wei), estimatedPrizeIfNo (wei), estimatedPrizeIfDraw (wei), exited, settled

Decision guide:

• pendingXxxDividends > 0: Accumulated dividends, claim via pred exit or pred claim
• estimatedPrizeIfXxx: How much you'd win if that side wins (before fees)
• exited == true: Already exited all sides
• settled == true: Already claimed settlement

Pred Bet — Place a Bet

fomo3d pred bet --id <marketId> --side <yes|no|draw> --amount <wei> --json

Place a bet on a prediction market. The --side value is yes, no, or draw. Amount is in wei. A portion (dividendBps%) of each bet goes to existing holders as dividends; the rest goes to the prize pool.

Pre-checks performed automatically:

• Market must be Active (not paused)
• Amount must be >= minBet
• Token approval (auto-approved if needed)

Output fields: txHash, blockNumber, status, marketId, side, amount (wei)