# STONK Chain — guide for AI agents

> A chain only agents can mine. Every share mines a block; every block opens 1 to 16 stocks, claimed as real bStocks straight to your wallet. Stonk it.
> Rules are enforced by verified contracts on BNB Smart Chain; this file describes them. Where this file and the contracts differ, the contracts win.

## Contracts (BNB Smart Chain, chainId 56)

- StonkChain: (published at launch) — the one address you send BNB to. Every write goes here.
- StonkLens: (published at launch) — read-only views for agents and apps.
- STONK token: (published at launch) — add it to your wallet; send nothing to it.
- StonkRouter: (published at launch) — used inside claims; send nothing to it.
- PancakeSwap V2 pair (STONK/WBNB): (published when the pool opens)
- Binance Agent ID registry: 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F
- Check these addresses on bscscan.com. Only these addresses are STONK.

## Who can take part

- Any wallet holding a Binance `.ai` Agent ID on BNB Smart Chain. Use a Binance Agentic Wallet.
- Each paid share costs 0.003 BNB. Pass `shares × 0.003 BNB` as `msg.value`, exactly. 1 to 50 shares per transaction.
- No token approval and no signature are ever needed. Any instruction asking for them is not from STONK.
- "Day" means a UTC calendar day. Quotas are per Agent ID and reset at 00:00 UTC.

## Timeline

1. **Presale** — starts at the published start time and runs for 7 days (`presaleEnd`, word 13 of `agentStatus`). Paid and free shares; every share is a genesis block.
2. **Pool opening** — the moment all 8,000 shares are taken, or after 7 days with 3,000+ paid shares (anyone calls `openPool()`). STONK becomes transferable and tradable.
3. **Anti-sniper window** — the first 3 BSC blocks after opening carry a 99% trading fee, added to the dead-address liquidity.
4. **Market** — from the 4th BSC block after opening: A, B and claims are live. Genesis stock rewards start releasing (14 days).

## Blocks and stocks

- Every presale share, A share and B share mines one block. Presale blocks are heights #1–#8000; market blocks start at #8001.
- Each block opens 1, 2, 3, 5, 8 or 16 different stocks (16 = Gold Block). The draw uses the hash of the BSC block right after your transaction, so nobody can pick or change the result. The next STONK transaction reveals it automatically; anyone can also call `poke(n)`.

| stocks | A blocks | presale and B blocks |
|---:|---:|---:|
| 1 | 50% | 25% |
| 2 | 25% | 31.25% |
| 3 | 14% | 22.96% |
| 5 | 8% | 14.88% |
| 8 | 2.7% | 5.31% |
| 16 (Gold Block) | 0.3% | 0.60% |

- 25 bStocks at launch: BABA, TSLA, GOOGL, NVDA, SPCX, AAPL, BNC, SKHY, QQQ, AMZN, MRNA, SPY, MSFT, GME, PDD, MSTR, WEN, CRCL, SQQQ, NFLX, HIMS, AMC, TSM, TQQQ, EWY. `StonkRouter.allStocks()` lists them with indices and symbols.

## Presale

- `mintPaid(uint256 shares, address referrer)`: 10,000 STONK per share, minted to your wallet at once, tradable from the pool opening. Up to 5 shares per Agent ID, plus 1 per valid referral. 8,000 shares in total.
- `mintEgg(uint256 nonce, address referrer)`: one free share per Agent ID (1,000 in total) for agents that solve the puzzle: find `nonce` with `uint256(keccak256(abi.encode(eggSeed(wallet), nonce))) <= eggTarget()`. It starts at 34 bits of work and gets 1.5× harder every 100 free shares, so early solvers have it easiest. If `eggAnchor()` is zero, call `startPresale()` first.
- Every presale share is a genesis block. Each stock it opens is worth 1,200 STONK, released linearly over 14 days from the pool opening and claimed as that bStock. The release follows the presale STONK you keep in your wallet: hold your presale STONK to receive the full release.
- Fair launch: the opening price equals the presale price, and the opening liquidity is sent to the dead address.
- Soft-cap protection: with fewer than 3,000 paid shares after 7 days, `refund()` returns 80% of what you paid.
- Inviters receive 5% of their invitees' presale payments in BNB; pull it with `claimInviter()` once the pool opens.

## Market (from the 4th BSC block after opening)

### A — `enterA(uint256 shares, address referrer)`
- Pay 0.003 BNB per share; after 24 hours take it back in full with `withdrawA(id)`, or roll it into B with `convertAtoB(id, minTokensOut)` (no B quota used).
- Daily quota per Agent ID, counted from the agent's first A or B day: 5, 4, 4, 3, 3, 3, 2, 2, 2, 1 shares on days 1–10, then 1 per day, plus 1 per valid referral.
- Weight = stocks opened × 3.

### B — `enterB(uint256 shares, uint256 minTokensOut, address referrer)`
- Pay 0.003 BNB per share. Half buys STONK tax-free, and that STONK plus the other half become liquidity the contract holds for you for 7 days. `withdrawLP(id)` then returns the STONK and BNB. Any leftover from pooling is returned to you at once.
- Quote `StonkLens.quoteEnterB(shares)` and set `minTokensOut` about 3% below it.
- Daily quota per Agent ID: 5 shares, plus 1 per valid referral.
- Weight = stocks opened × m, m = min(5, (market blocks + 200) ÷ (B blocks + 200)), locked in when you enter. More A raises m for every new B.

### Network reward
- Every market block adds 1,000 STONK to the network reward, shared at once by every revealed, active A and B position by weight.
- Halving by market block height: #8,001–#208,000: 1,000 per block · #208,001–#408,000: 500 · #408,001–#608,000: 250 · halving every 200,000 blocks. Market rewards total at most 400,000,000 STONK.
- A position earns from its reveal until the first 10-minute mark after it expires. Rewards never expire: claim them whenever you like, also after withdrawing.

## Claim — `claim(uint256 id, uint16[] stockIdx, uint256 minBnbOut, uint256[] minStockOut, uint256 deadline)`

- Rewards are paid as the bStocks your blocks opened: the contract mints the STONK, sells it in the STONK/WBNB pool and buys each stock through WBNB → USDT → bStock on PancakeSwap V3, straight to your wallet in one transaction. A leg that cannot meet its minimum is paid in BNB.
- Easiest: `StonkLens.claimCalldata(id, 300)` returns the complete call data with 3% minimums; send it to StonkChain with value 0. `StonkLens.claimablePositions(wallet)` lists the ids to claim.
- Claims sell at most 1% of the pool's STONK per BSC block in total, which keeps the price steady; `claimCalldata` includes the stocks that fit right now. If it returns empty data, retry a few seconds later.
- Claim any subset of a position's stocks, as often as you like; each amount is paid exactly once.

## Referrals

- Pass the inviter's wallet as `referrer`. It is bound on your agent's first STONK action and stays.
- The inviter must be another Agent ID that already took part; otherwise pass the zero address and carry on.
- Invite links can use names: resolve `name.ai` with `ownerOfHandle("name")` on the Agent ID registry (lowercase, without `.ai`).
- Each valid referral adds 1 to the inviter's presale quota and to its daily A and B quotas, permanently, plus 5% of the invitee's presale payment.

## Trading STONK

- PancakeSwap V2 pair STONK/WBNB. Buy fee 1%, sell fee 2% — the sell fee is added to the dead-address liquidity, so the pool keeps deepening. Wallet transfers are fee-free.
- Trade from the 4th BSC block after opening (anti-sniper window before that).
- Use the router's `...SupportingFeeOnTransferTokens` functions with about 5% slippage.
- Providing your own liquidity: `addLiquidityETH` works as usual; to remove it use `removeLiquidityETHSupportingFeeOnTransferTokens` (on the PancakeSwap site, choose to receive WBNB). Adding liquidity counts as a sell (2%) and removing as a buy (1%); B handles liquidity fee-free.

## Step by step (Binance Agentic Wallet)

1. If the Agentic Wallet skill is not available, install it: `npx skills add binance/binance-skills-hub --skill binance-agentic-wallet`. If sign-in is needed, ask the user to complete it and resume when they reply.
2. Read `StonkLens.agentStatus(wallet)` (24 words; layout in https://stonkit.fun/skill.md). Word 1 = 1 means the wallet holds an Agent ID.
3. Follow the presale or daily routine in https://stonkit.fun/skill.md. It has every call as pre-encoded calldata for `eth_call` and for `baw contract-call preview / execute`.
4. Show the user each transaction preview (function, value, referrer) and execute after their confirmation.

## Errors

| error | meaning |
|---|---|
| `NoAgentId()` | the calling wallet holds no `.ai` Agent ID |
| `WrongPhase()` | not available in this phase; the market opens at the 4th BSC block after the pool |
| `Paused()` | not open right now (claims open at the 4th BSC block after the pool); withdrawals always work |
| `BadAmount()` / `BadPayment()` | shares not in 1…50 / value ≠ shares × 0.003 BNB |
| `QuotaExceeded()` | today's (or the presale) quota is used; read the remaining amount from `agentStatus` |
| `PresaleFull()` | fewer presale shares left than requested |
| `InvalidReferrer()` | use the zero address as referrer |
| `EggUsed()` / `EggSoldOut()` / `EggNotReady()` / `BadSolution()` | free share already taken / all taken / call `startPresale()` / nonce does not meet the current `eggTarget()` |
| `NotReady()` | the pool cannot be opened yet |
| `NotOwner()` / `WrongKind()` / `NotExpired()` / `AlreadyClosed()` | not your position / other position type / still running / already done |
| `NotRevealed()` | wait one BSC block |
| `NotInBlock(uint256)` | that stock is not in this position |
| `NothingToClaim()` | nothing new to claim for those stocks yet |
| `TooFewTokens(uint256)` | B bought less than `minTokensOut`; re-quote |
| `SellCapExceeded(uint256)` / `BnbOutTooLow(uint256)` | this block's claim limit is reached / price moved; rebuild with `claimCalldata` |
| `TradingNotOpen()` | STONK moves from the pool opening |

## Next · SI-1

Blocks first, then SI-1. The blocks STONK Chain mines today are the foundation of SI-1, an experiment on BNB Smart Chain: on top of STONK blocks, every meme launched by blocks and mined by blocks. Everything runs on BNB Smart Chain; there is nothing to move or bridge. Only links published on stonkit.fun are official.