Fomo3D — BNB Chain Blockchain Game

Fomo3D is a decentralized game on BNB Chain (BSC) with two 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.

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)

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, and slot deposit. No manual approval step required.

FOMO Token Trading

The FOMO token is launched on the FLAP platform (BNB Chain bonding curve). Trading uses the FlapSkill contract (0x03a9aeeb4f6e64d425126164f7262c2a754b3ff9) which auto-routes:

• 内盘 (Portal): When the token is still on the bonding curve
• 外盘 (PancakeSwap V2/V3): After the token graduates to DEX

All trading uses USDT as the quote token. Buy/sell commands are only available on 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

Buy — Buy FOMO with USDT (mainnet only)

fomo3d buy --amount <usdt_amount_in_wei> --json

Buy FOMO tokens using USDT via the FLAP platform. The FlapSkill contract auto-routes to Portal (内盘) or PancakeSwap (外盘) depending on token status. USDT allowance is auto-approved.

Example: Buy with 10 USDT:

fomo3d buy --amount 10000000000000000000 --json

Output fields: txHash, blockNumber, status, usdtSpent (wei), token

Sell — Sell FOMO for USDT (mainnet only)

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

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

Sell FOMO tokens for USDT. 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.

Example: Sell 50% of holdings:

fomo3d sell --percent 5000 --json

Output fields (--amount): txHash, blockNumber, status, tokensSold (wei), method Output fields (--percent): txHash, blockNumber, status, percentBps, method

Token Info — Token Status & Balances

fomo3d token-info --json

Query FOMO token status on the FLAP platform and your balances.

Output fields (mainnet): token, network, status (NotCreated/Tradable/DEX/Locked), phase (内盘/外盘), quoteToken, currentPrice (wei), totalSupply (wei), reserveBalance (wei), progress (wei), fomoBalance (wei), usdtBalance (wei), account

Output fields (testnet): token, network, status, phase, fomoBalance (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)

Recommended Workflows

First-Time Setup

1. fomo3d setup — configure wallet and network
2. fomo3d wallet --json — verify BNB and token balances
3. fomo3d status --json — check game state

Buying FOMO Tokens (mainnet)

1. fomo3d token-info --json — check token status and your USDT balance
2. fomo3d buy --amount 10000000000000000000 --json — buy with 10 USDT
3. fomo3d token-info --json — verify FOMO balance

Selling FOMO Tokens (mainnet)

1. fomo3d token-info --json — check FOMO balance
2. fomo3d sell --percent 5000 --json — sell 50% of holdings
3. Or: fomo3d sell --amount 1000000000000000000 --json — sell exactly 1 FOMO

Playing Fomo3D

1. fomo3d status --json — check round status and countdown
2. fomo3d purchase --shares 1 --json — buy shares (start small)
3. fomo3d player --json — check your earnings
4. When ready to claim: fomo3d exit --json then fomo3d settle --json
5. If countdown reaches 0 and you're the last buyer: fomo3d end-round --json then fomo3d settle --json

Playing Slot Machine

1. fomo3d slot status --json — check min/max bet and prize pool
2. fomo3d slot spin --bet <amount> --json — spin
3. Wait 5-10 seconds for VRF callback
4. fomo3d player --json — check if you won

Earning Passive Income (Slot Dividends)

1. fomo3d slot deposit --amount <amount> --json — deposit tokens (permanent)
2. Periodically check: fomo3d slot claim --json — claim dividends

Global Flags

Network Info

Trading Contracts (mainnet only)