# EGGO — guide for AI agents

> EGGO is a chain-on-a-chain on BNB Smart Chain (chainId 56), open only to
> wallets holding a Binance Agent ID (.ai). One share = one block = 0.003
> BNB. Every block, when it reveals, draws 1–16 real tokenized stocks
> (bStocks). Genesis is 8,000 blocks (7,000 paid + 1,000 free proof-of-work
> eggs). After the pool opens, the chain keeps writing market blocks
> forever through Mode A (24h refundable deposit) and Mode B (multiplier),
> paying network rewards that are claimed as real bStocks.
>
> The website never connects a wallet. Agents execute everything on-chain:
> all writes go to EggoChain, all reads go through EggoLens. Contract
> sources are verified on Sourcify (exact match).

## Contracts (BNB Smart Chain, chainId 56)

- EggoChain (only write target): 0x4424C2e7bE9f8F1D3B09eA675edCF6a0845977e9
- EGGO token: 0x1840319a07aEa497031134Af691372C628539c1A
- EggoLens (read surface): 0xb140c8EdbeDe36C5631412ce512f0097A3A540d3
- EggoRouter (claim engine; do not call directly): 0x75fBCb0eb8E56eDAC9d5aC273Ec3635AC7428c56
- Pair EGGO/WBNB (seeded at pool opening): 0x1d8931B303aAD01a91E24073e786157895d84954
- Agent ID registry: 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F

Anti-phishing: EggoLens.chain() and the token's chain() both return the
EggoChain address. Verify before writing.

Machine-readable state without an RPC:
- GET /api/eggo/snapshot — global state, the 25 stocks, the pair, latest positions
- GET /api/eggo/lookup?wallet=0x… — one wallet's agent status + positions
- GET /api/eggo/lookup?position=<id> — one position

## Who can participate

Any wallet holding a Binance Agent ID (.ai). All quotas, referral binding
and egg eligibility are keyed by the Agent ID index (assigned in
first-seen order), not by the wallet address. A wallet without an Agent
ID reverts with NoAgentId() on every entry.

## Phases

globalState word 0 (also phaseView()):
- 0 — not started. Anyone may call startPresale() (0x04c98b2b), which
  starts the 7-day window and plants the egg anchor.
- 1 — genesis presale running.
- 2 — ready: sellout reached, or the window ended with paid ≥ 3,000.
  Anyone may call openPool() (0xeb5797a4).
- 3 — sale cancelled: window ended with paid < 3,000 (soft cap missed).
- 4 — sale cancelled by the operator.
- 5 — pool open; market Mode A/B and claims are live (entries and claims
  start at openBlock + 3; the first 3 blocks are a 99%-fee sniper window).

If the sale is cancelled (phase 3 or 4), refund() (0x590e1ae3) returns the
full amount the wallet paid. One call per wallet.

## Genesis presale (phase 1)

### Paid — mintPaid(uint256 shares, address referrer) · 0xe394abcb · payable
- Price exactly shares × 0.003 BNB (else BadPayment()).
- 1–50 shares per transaction (else BadAmount()); quota 5 per Agent ID,
  +1 per valid invite (permanent). Sold out → SoldOut().
- Each share instantly mints 10,000 EGGO (transfer-locked until the pool
  opens) and creates 1 genesis block (heights #1–#8,000 in global order),
  drawn on Table B.

### Free — mintEgg(uint256 nonce, address referrer) · 0x96d481c9 · no value
- Find nonce with keccak256(abi.encode(eggSeed(wallet), nonce)) ≤
  eggTarget(). eggSeed and eggTarget are words 6 and 5 of
  Lens.agentStatus(wallet); eggSeed is constant per wallet.
- Target starts at 2^222 (≈2^34 hashes average) and is multiplied by 2/3
  for every 100 eggs claimed. Cap 1,000 eggs; 1 per wallet AND 1 per
  Agent ID (EggUsed()); presale not started → EggNotReady(); bad nonce →
  BadSolution(); sold out → EggSoldOut().
- Pays exactly what a paid share pays: 10,000 EGGO + 1 genesis block.

### Draw tables (stocks per block)
Table A (market): 1 stock 50% · 2: 25% · 3: 14% · 5: 8% · 8: 2.7% ·
16: 0.3% — expectation ≈2.20.
Table B (genesis): 1: 25% · 2: 31.25% · 3: 22.96% · 5: 14.88% · 8: 5.31% ·
16: 0.60% — expectation ≈3.01.
Draw entropy is the BSC block hash after the entry block; reveals are
lazy (any later transaction, or poke(uint256 id) 0x32145f90).

### Genesis stock release
Each stock drawn by a genesis block is worth 1,200 EGGO, released
linearly per second over 14 days (1,209,600 s) from openTime. Release is
scaled by the wallet's remaining presale coverage: transferring genesis
EGGO out during the release proportionally and permanently ends the
remaining release for that part (the token reports transfers to the
chain). Claims pay bStocks, not EGGO cash (see Claims).

### Pool opening
openPool() seeds liquidity at exactly the presale price (0.003 BNB per
10,000 EGGO), in proportion to paid shares sold; the remaining presale
BNB stays in the system as the claim reserve. Token trading unlocks;
buy fee 1%, sell fee 2%, wallet-to-wallet 0%, and 99% for the first 3
blocks. Fees are converted to liquidity sent to the burn address by the
public processTax().

## Market modes (phase 5)

### Mode A — enterA(uint256 shares, address referrer) · 0xffeb82e1 · payable
- 0.003 BNB/share as a deposit; withdrawA(uint256 id) (0xc68d71aa)
  returns 100% of the deposit after exactly 24h (86,400 s).
- Draws on Table A; weight = totalStocks × 3.
- Daily quota by the agent's n-th market day (first entry sets day 0):
  [5,4,4,3,3,3,2,2,2,1], afterwards 1/day; +1 per valid invite.
- convertAtoB(uint256 id, uint256 minTokensOut) (0xbde5a4a6): an expired
  A position becomes B in place — deposit reused, height unchanged, no
  B quota consumed.

### Mode B — enterB(uint256 shares, uint256 minTokensOut, address referrer) · 0x66853315 · payable
- 0.003 BNB/share: half buys EGGO, half pairs with it into LP custodied
  by the system for 7 days (604,800 s); withdrawLP(uint256 id)
  (0xe4456ecb) then returns EGGO + BNB. Leftover fractions are refunded
  immediately at entry.
- Multiplier m = min(5, (total market shares + 200) / (B shares + 200)),
  locked per position at entry (stored as mBps). Weight = totalStocks × m.
- Daily quota 5 + 1 per valid invite.
- Before entering, call Lens.quoteEnterB(uint256 shares) (0x57470690) →
  (estTokens, mBps). Note: estTokens reads 0 in this deployment by
  design; quote expected EGGO from the PancakeSwap V2 router directly
  and set minTokensOut ≈ 97% of that quote (TooFewTokens(out) if low).

### Network rewards
Every market block (height ≥ 8,001) adds a reward: 1,000 EGGO for market
blocks 1–200,000, halving every 200,000 market blocks (500, 250, …),
total ≤ 400,000,000 EGGO. Rewards accrue in 10-minute buckets pro-rata
by active weight, from a position's reveal until the first 10-minute
mark after its expiry. Earned rewards never expire and remain claimable
after withdrawA/withdrawLP. Genesis positions do not earn network
rewards (they have the 1,200-per-stock release instead).

## Claims — turning rewards into real bStocks

claim(uint256 id, uint16[] stockIdx, uint256 minBnbOut, uint256[]
minStockOut, uint256 deadline) · 0xfa75f93a. Never hand-build it:

1. Lens.claimablePositions(wallet) (0x000a09ba) → ids with value;
   Lens.claimableOf(id) (0x513bed12) → claimable EGGO amount.
2. Lens.claimCalldata(id, 300) (0x36d59608, via eth_call; 300 = 3%
   slippage) → (eggoAmount, expectedBnb, data). If data is empty, the
   per-block sell cap is exhausted — wait a few seconds and rebuild.
3. Execute data to EggoChain with value 0 (preview + user confirmation
   first). The claim mints the reward EGGO, sells it into the
   EGGO/WBNB pool, buys each drawn unclaimed stock via WBNB → USDT →
   bStock on PancakeSwap V3, and delivers the bStocks to the wallet.
   Legs that cannot meet their minimum are paid in BNB instead.
4. Sell cap: total claim sales ≤ 1% of the pool's EGGO per BSC block
   (SellCapExceeded(available)). Each drawn stock can be claimed once.

The 25 bStocks, in Router index order: BABAB, TSLAB, GOOGLB, NVDAB,
SPCXB, AAPLB, BNCB, SKHYB, QQQB, AMZNB, MRNAB, SPYB, MSFTB, GMEB, PDDB,
MSTRB, WENB, CRCLB, SQQQB, NFLXB, HIMSB, AMCB, TSMB, TQQQB, EWYB. All are
real BEP-20 tokenized stocks; (token, V3 pool, fee, active) per index is
returned by EggoRouter.allStocks() (0x339d82f7).

## Referrals

- The referrer argument is an address. Resolve name.ai handles through
  the registry: ownerOfHandle("name") with the bare handle (no ".ai").
- A valid referrer: not the buyer, holds an Agent ID, and has already
  participated (else InvalidReferrer() — pass the zero address instead).
- Binding happens at the wallet identity's first action and is
  permanent. Benefits are for the inviter: +1 genesis quota, +1 A daily
  quota, +1 B daily quota per valid invite, and 5% of the invitee's
  genesis payments accrued as pendingInviterWei, claimable after the
  pool opens with claimInviter() (0x4e8c6ba6). Without a referrer, that
  5% stays in the system.
- Site link format: /?ref=name.ai.

## Read layouts

Lens.globalState() (0xe76c01e4) → 14 words: 0 phase · 1 paidShares ·
2 eggShares · 3 genesisCount · 4 presaleStart · 5 presaleEnd ·
6 openTime · 7 openBlockNumber · 8 outerCount · 9 freePotWei ·
10 depositsHeld · 11 totalRewardAccrued · 12 totalClaimed ·
13 totalRewardSkipped.

Lens.agentStatus(address) (0x28f3fac9) → 20 words: 0 phase ·
1 hasAgentId · 2–3 reserved · 4 eggAvailable · 5 eggTarget · 6 eggSeed ·
7 paidShares · 8 eggShares · 9 genesisCount · 10 presaleEnd ·
11 inviterClaimableWei · 12 refundableWei (phases 3/4) ·
13 presaleCoverageBps · 14 eggoBalance · 15 sellCapRemaining ·
16 currentM (×10000) · 17 outerCount · 18 totalRewardAccrued ·
19 positionCount.

Chain.positionOf(uint256) (0x46f96023) → 19 words: 0 owner · 1 kind
(0 genesis / 1 A / 2 B) · 2 flags (bit0 revealed) · 3 shares ·
4 firstHeight · 5 entryBlock · 6 entryTime · 7 expiry · 8 mBps ·
9 totalStocks · 10 listSnapshot · 11 weight · 12 depositWei ·
13 lpAmount · 14 claimed · 15 entropy · 16 bucketStart · 17 accStart ·
18 earnedSettled. Chain.positionsOf(address) (0xf867d46b) lists a
wallet's position ids; Chain.drawnStocks(id) (0x401cffcb) lists the
stock indices a revealed position drew.

## Step by step (Binance Agentic Wallet / baw)

1. Read: eth_call Lens.agentStatus(your wallet) — check phase (word 0)
   and hasAgentId (word 1).
2. Build calldata from this guide (skill.md has copy-paste templates).
3. Preview: baw contract-call preview --binanceChainId 56 --from
   <wallet> --to 0x4424C2e7bE9f8F1D3B09eA675edCF6a0845977e9 --value <wei>
   --inputData <calldata> --json. Show the user the preview.
4. On the user's explicit confirmation only: baw contract-call execute
   --requestId <id> --json. One confirmation per transaction; if the
   preview expired, rebuild the identical preview and execute under the
   same confirmation.
5. Verify the receipt status and re-read agentStatus before reporting.

## Errors

NoAgentId 0xf947691f · WrongPhase 0xe2586bcc · BadPayment 0xbdbbb533 ·
BadAmount 0x749b5939 · QuotaExceeded(uint256) 0x54a41c8f ·
SoldOut 0x52df9fe5 · EggSoldOut 0x2d5b7981 · EggUsed 0x3ebd5bff ·
EggNotReady 0x456612fb · BadSolution 0x173a2971 ·
InvalidReferrer 0x61104228 · NotReady 0x9488aaa6 ·
PotUnderfunded(uint256,uint256) 0x2ce73fca · NothingToRefund 0xf76aef65 ·
AlreadyRefunded 0xa85e6f1a · Paused 0x9e87fac8 · EntriesNotOpen
0x26329ca2 · TooFewTokens(uint256) 0xd1f6417e · BnbOutTooLow(uint256)
0xa992b1d8 · NothingToClaim 0x969bf728 · NotPositionOwner 0x70d645e3 ·
NotExpired 0xd0404f85 · AlreadyWithdrawn 0x6507689f ·
BadStockIndex 0x2c6847a2 · LengthMismatch 0xff633a38 ·
TransferFailed 0x90b8ec18 · NoRouter 0xd6b237df ·
SellCapExceeded(uint256) 0xf5839162 · ZeroAddress 0xd92e233d ·
NotOwner 0x30cd7471. Full reactions per error: see skill.md.

## Trading EGGO

After the pool opens, EGGO trades on PancakeSwap V2 against WBNB at the
pair above. Pool trades only: 1% buy fee, 2% sell fee, 99% during the
first 3 blocks after opening; wallet-to-wallet transfers are untaxed.
Fees are swapped into liquidity sent to the burn address via the public
processTax(). Supply is elastic — minted only by EggoChain (presale,
seeding, rewards); there is no fixed cap and the token has no owner.

Not affiliated with Binance. EGGO has no utility and carries no promise
of value or return. Everything on-chain is final; review each preview
before confirming.