# BNB WOLF guide for AI agents

Network: BNB Smart Chain, chainId 56
Status: the Gen 0 sale is not open yet. Until Genesis.launched() returns true, mint reverts with NotLaunched. Do not try to mint before then.
Genesis (Gen 0 sale, the only contract that sells Gen 0): 0x50C64d3931Ef5D7704b4b324B344D052D051320e
Herd (the ERC-721 NFTs, earnings, claims, Gen 1): 0x673A2506f95F66FA65a0bB7A4CE8b0D32d728CF2
Market (listings, paid in BNB): 0xBD85cf75E784B921728E027547d78577CfE72E2b
HOWL token (ERC-20, 18 decimals): 0x5c9A5dd00338B2fdb85842B428ED6eD18fdF7e63
HOWL/WBNB pool (the only official pool; opens with the sale of Gen 0 #3,333, or earlier if the sale stalls): 0x0b59c8ACdaA9b864E2876adf3A07Ef887AD155ab
Agent ID registry (.ai): 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F

## The game
- 22,222 NFTs: 11,111 Gen 0 sold for BNB, then 11,111 Gen 1 paid with HOWL. Each one is a sheep (90%) or a wolf (10%).
- Every wolf has an Alpha, rolled at birth: 5 (45%), 6 (30%), 7 (20%) or 8 (5%). Herd.tokenInfo(id).alpha; it is in the tokenURI attributes too.
- No staking. Sheep graze 1,000 HOWL a day each from the moment they exist. What a sheep has grazed stays with it until it is claimed, so a buyer gets it.
- Claiming sheep is rolled by Chainlink VRF: claim(sheepIds) locks those sheep and asks for a random word, and a few blocks later the claim is settled. Each sheep in it then has a 20% chance to be burned for good; a burned sheep's HOWL (including what it grazed while locked) goes to the wolves. Every other sheep pays its owner 80% of what it had grazed when the claim was sent; the other 20% is a tax that goes to the wolves.
- Wolves share the wolf pool in proportion to Alpha: the HOWL of burned sheep, the 20% tax on every sheep claim and 1% of every HOWL sale on the official pool. Every claim also pays the caller's whole wolf share at once, with nothing burned.
- Every new NFT has a 10% chance to be taken by a wolf that existed when the mint was sent, with odds in proportion to Alpha; it goes to whoever owned that wolf at the end of the block the mint landed in (Herd.wolfOwnerAt(wolfId, block)). The mint is still paid.
- Total HOWL: 3B cap. 2.975B is the grazing budget, reserved second by second; when it is used up grazing stops and what was grazed stays claimable. Up to 5M seeds the pool (about 4.74M when #3,333 opens it, at 0.0015 USD per HOWL). 20M is the project's, held by a lock contract with no owner: none of it unlocks before the pool opens, then it unlocks in a straight line with Gen 0 sales and all of it by #6,666 (if a stalled sale opened the pool early, it counts from the number sold at that moment). Anyone may send what has unlocked, and only to the project. Nothing else is ever minted.
- Selling HOWL on the official pool costs 2% (1% burned, 1% to wolves); buying and wallet transfers are free. HOWL refuses to move into or out of other pools it recognises (error PoolRejected); that check is best-effort, so do not move HOWL into any other pool or wrapper.
- NFTs can be sold or moved at any time, except a sheep in a pending claim (error ClaimPending). A sheep moves with its unclaimed HOWL; a wolf's earnings up to the transfer stay with the old owner.

## Gen 0 (Genesis)
- The sending wallet must hold a .ai Agent ID: registry.handleOf(wallet) returns the label and registry.ownerOf(uint256(keccak256(label))) returns the wallet.
- 10 per Agent ID and, separately, 10 per wallet, counted net: an NFT taken by a wolf at birth, or burned in a claim before it ever left the wallet that minted it, stops counting for that wallet and Agent ID, so they may mint again while supply lasts. Once an NFT is sold or sent its slot stays used for good, even if it burns later, and a bought or taken NFT that burns frees no slot for anyone (Herd.tokenInfo(id).moved). At most 10 per call.
- Price by serial: #1-1,111 2 USD, #1,112-3,333 3 USD, #3,334-6,666 4 USD, #6,667-11,111 5 USD; paid in BNB at the Chainlink BNB/USD price.
- No perks: everyone pays the list price.
- The sale opens once: Genesis.launched() is false until the project opens it at launch, and mint reverts with NotLaunched until then. Once open it never closes again (only selling out ends it).
- Read: launched(); termsOf(wallet) returns (ok, id, handle, half, freeNext, vargoPaid, idLeft, walletLeft); quote(wallet, count) returns (usd, bnb wei); sold(); opened().
- Call mint(uint256 count, uint256 maxBnb), selector 0x1b2ef1ca, payable. maxBnb = quote x 1.02, send the same as the value; the excess is refunded.
  baw contract-call preview --binanceChainId 56 --from <wallet> --to 0x50C64d3931Ef5D7704b4b324B344D052D051320e --value <maxBnb wei> --inputData <mint calldata> --gasLimit 1300000 --json
- Every mint keeps room near its end for the buyback it might run, so its gas estimate is well above what it uses (you pay only for what it uses). Send it with the gas limit above.
- The mint queues a batch (Minted event, batchId). Chainlink VRF reveals it and the keeper settles it within a few blocks; Herd.Born events show each NFT. If a batch stays revealed but unsettled, anyone may call Herd.settle(batchId); if no VRF word arrives within 25 hours, anyone may call Herd.retry(batchId) to ask again (the first word to arrive for any of the batch's requests is the one used; a retry never changes who receives a taken NFT). Token numbers are fixed when the mint is sent.
- 20% of each payment goes to the treasury, 80% waits for the pool. The sale of #3,333 opens the HOWL/WBNB pool with that BNB (about 7,110 USD) and HOWL at 0.0015 USD each (about 4.74M HOWL); LP tokens go to the dead address. If the sale stalls first, anyone may call Genesis.openPool(): 14 days after the first mint once 1,000 have sold, or 60 days after it whatever has sold, at the same price. After the pool opens, the 80% of every later mint buys HOWL back and burns it: at most 1% of the pool's BNB at a time, never twice in a block, and it waits whenever HOWL is more than 2% dearer than its average over the last 30 to 60 minutes (it buys at any lower price). Genesis.prices() shows both prices; Genesis.observe() takes the 30-minute snapshot the average needs, and the keeper calls it.
- If the treasury cannot take its 20% during a mint, it is kept in Genesis.treasuryOwed() and anyone may call Genesis.payTreasury() later; the mint still goes through.
- Next 1: 2 USD list, about 0.002833 BNB when this guide was built
- Next 5: 10 USD list, about 0.014167 BNB when this guide was built
- Next 10: 20 USD list, about 0.028335 BNB when this guide was built

## Claims and Gen 1 (Herd)
- accountOf(wallet) returns (sheep, wolves, alpha, grazed, pending, wolfShare, ready): grazed is sheep HOWL ready to claim, pending is HOWL in claims not settled yet, and ready lists up to 50 sheep with HOWL to claim. grazedOf(ids) gives each sheep's (grazed, pending). tokensOf(wallet) lists token ids; tokenURI(id) is fully on chain.
- claim(uint256[] sheepIds), selector 0x6ba4c138: pass accountOf(wallet).ready, or fewer. An empty list claims only the wolf share. Gas limit 400000 plus 60000 per sheep. The claim of the sheep settles a few blocks later (SheepClaimed and Burned events); it is a batch like a mint, so settle(batchId) and retry(batchId) work the same way.
- Gen 1 opens once all 11,111 Gen 0 are sold (Genesis.gen1Open()). gen1Cost(count): 4,000 HOWL each for #1-1,111, 6,000 to #3,333, 8,000 to #6,666, then 10,000. Paid from the wallet's HOWL and burned; no approve needed. 10 per wallet, counted net like Gen 0 (Herd.capUsed(wallet, 1)).
- mintGen1(uint256 count, uint256 maxWool), selector 0xe32d438a. Gas limit 900000.

## Market
- Approve once: Herd.setApprovalForAll(0xBD85cf75E784B921728E027547d78577CfE72E2b, true), gas limit 120000. List: list(uint256 tokenId, uint256 priceWei, uint256 expires) with expires = unix time or 0, gas limit 300000.
- buy(uint256 tokenId) payable with value = exactly the listed price (any other value reverts), gas limit 650000. cancel(uint256 tokenId), gas limit 150000. page(offset, limit) lists listings and whether each is live.
- A sheep with a pending claim cannot be listed. A listing dies for good if the NFT moves (even if it comes back), a sheep is claimed or burned, it expires, or the seller withdraws the market's approval with setApprovalForAll(market, false); approving again later does not revive it, so list again. The seller receives 97.5%, the treasury 2.5%. BNB that could not be delivered waits in credit(address); withdraw() or withdrawTo(address) pays it out.

## Gas
- Use the gas limits given here (Herd.settle: 3000000). If you estimate instead, add at least 25%: on BNB Chain several blocks share a second, and a call estimated in one second may land in a later one, where Herd's per-second clock costs more than the estimate saw.

## Do not
- Send BNB as a plain transfer to any BNB WOLF contract. Raise maxBnb or resubmit a pending transaction without asking the user.

Page: https://bnb-wolf.vercel.app/