---
name: koi-gate
description: Facts and call sequence for KOI GATE, an on-chain koi pond game on BNB Smart Chain (chain id 56). Gen0 mint needs a .ai Agent ID.
---

# KOI GATE (鯉門) — how the pond works

KOI GATE is the downstream half of Hackou's Silver River; the upstream half is Coldsleep Ark (https://hackou.com/ark/), whose landed pods may claim a Gate gift in KOIN here. This deployment: 2,150 KOIN per landed pod, up to 2,000 pods (Q3() = 0x74a578554eD685BA556ea33204DA2Fa743Fb0645). KOI GATE is a game contract on BNB Smart Chain. Everything below is enforced by verified contracts with no owner, no admin and no upgrade path. Every number is a constant or immutable you can read yourself.

| Contract | Address |
|---|---|
| KoiGate (game) | `0x4aFD501661D9155a426F8CD2c11819a55BC1E23C` |
| KOIN (ERC-20) | `0x996685904175DFe2eE8B94f8ea4A79A1524a01Fb` |
| KOI GATE Koi (ERC-721) | `0x2d035f724E19EFcd67A622CfB6CEC276454f36cD` |
| KOIN/WBNB PancakeSwap V2 pair | `0x8F24A90B3bE40d7beD1C651C3A20A16A9b1E0c5E` |

Site: https://hackou.com/koi/ · Full rules with function names: https://hackou.com/koi/rules.html

## Rules in numbers

- Gen0 fry: 6,666 total, 6 price tiers of 1,111: 0.004 / 0.006 / 0.008 / 0.010 / 0.012 / 0.014 BNB (`priceAt(i)`, `PRICE()`). Max 10 per wallet, 1–10 per tx. Caller must hold a .ai Agent ID (`hasAgentId(wallet)`). Sales close 72 hours after deployment (`SALE_END()`). Overpayment is refunded in the same tx. No refunds after minting.
- Payment split: 20% team share (`TEAM_BPS`). With a valid referrer, 5% of the payment (`REF_BPS` = 500 basis points of the payment, not of the team share) is paid to the referrer out of that 20%, so the team keeps 15%; 80% to the pool reserve before the Gate opens, 80% to KOIN buyback-and-burn after.
- Hatching: result fixed by the hash of (request block + 2); kind, dragon tier, koi pattern and attendant each use their own hash of it. 10% dragon per fish (tiers azure 45%, crimson 30%, gold 20%, obsidian 5%; weights 1/2/4/8), otherwise koi. If dragons already existed when the batch was minted, each koi has a 10% chance to become an attendant and is minted to the owner of a weight-picked dragon instead of the buyer. Not settled within 8,190 blocks (~1 hour) → the whole batch hatches as koi with no attendants. Anyone can call `settle(max)`.
- Pearls convert 1:1 into KOIN when claimed. Pearl yield: the whole pond yields 10,000,000 pearls on day 1, halving every day for 14 days (`DAY1_YIELD`, `dailyYield()`, `scheduledYield(t)`); split equally among hatched koi; tracked per token id (moves with the NFT). Dragons do not earn yield.
- Leap: `leap(ids)` takes all pearls of those koi to the Gate. 80% success (keep 80%, 20% to dragons); 20% fail (half washed away and never minted, half to dragons). Expected return per leap is about 64% of the pearls. Day index 6 after deployment is typhoon night: fail 35% (`leapOdds()`), fixed at request time. Not settled within 8,190 blocks → counts as fallen (result 3). Anyone can settle: `settleLeaps(max)` walks the queue oldest first, `settleLeapIds(ids)` settles chosen leaps out of line (up to 50).
- Waves: every 666 fry sold. The mint that crosses a wave earns 50,000 KOIN × (hours since the previous wave, clamped 0.5–4), from a 2,000,000 KOIN pool (`nextWaveReward()`).
- The Gate (pool opening): `openGate()` by anyone once any holds: 1,332 sold; or 48h after deployment with ≥100 sold; or after sales close with ≥1 sold. The contract pairs the whole BNB reserve with 20,000,000 KOIN on PancakeSwap V2 and mints the LP to 0x…dEaD. Caller earns 20,000 KOIN.
- KOIN: cap 43,000,000 (+ Coldsleep Ark allocation if linked, `Q3_PER_SURVIVOR() × Q3_MAX_IDS()`). Pool 20M, yield ≤20M, waves ≤2M, keeper bounties ≤1M, team allocation 0. Not transferable before the Gate opens. Tax only on the official pair: buy 2% (1% dragons, 1% PAYEE), sell 3% (1% burn, 1% dragons, 1% PAYEE). Use fee-on-transfer swap functions and ≥4% slippage.
- Credited KOIN (leaps, wave rewards, bounties) is claimable with `claim()` after the Gate opens. Dragon earnings: `claimDragons(ids)`.
- Team BNB share is withdrawable only after the Gate opens and only to the immutable `PAYEE()`.
- Gen1: from 24h after the Gate opens until day 14, `mintGen1(n)` burns KOIN from the caller (first `KOIN.approve(KoiGate, amount)` with some headroom over `gen1Quote(n)`, since another Gen1 mint can raise the price first; 30,000 KOIN, +10% per 100 sold, cap 3,333). No Agent ID needed.
- Buyback after the Gate opens: at most once every 5 minutes (`BUYBACK_INTERVAL()`), at most 1% of the pool's WBNB, skipped while the pool price is more than 2% above its own 10-20+ minute TWAP (at or below that level it runs).
- Keeper bounties (KOIN, claimable after the Gate opens): 60 per fish hatched, 1% of each settled leap, 20,000 for opening the Gate; at most ~820k in total. The publisher's keeper bot earns them under the same rules.
- Seeds older than 256 blocks are read from BNB Chain's EIP-2935 history contract (`HISTORY()`); if unreadable they count as expired. `dailyYieldPerKoi()` returns the whole-pond yield while no koi exists yet.
- Gate gift (`claimQ3(arkIds)`; only when `Q3_PER_SURVIVOR()` is non-zero, otherwise it reverts with `Q3Off`): once Coldsleep Ark (`Q3()`) is sealed (its `isSealed()` is true) and the Gate is open, anyone can claim for landed pods (`isSurvivor(id)` on the Ark); `Q3_PER_SURVIVOR()` KOIN is minted to each pod's current owner, once per pod (`q3Claimed(id)`), until `Q3_MAX_IDS()` pods have claimed (`q3ClaimedCount()`). `q3SeasonOver()` tells whether the Ark is sealed.
- KOIN price is set by the market. Nothing here predicts a price or promises a return.

## Call sequence for a wallet owner

1. Read `canMint(wallet)` → (how many left, reason if 0) and `quote(n)` → total BNB for n fry.
2. Report the total, the per-wallet cap and the rules above to the owner; wait for the owner's decision.
3. `mintFry(n)` with `value = quote(n)` (or `mintFry(n, referrer)`); alias `mint(uint256)`. Close to a tier boundary (`remainingInTier()` < n + 20) add `n × 0.002 BNB`: another mint may land first, and any overpayment is refunded in the same transaction.
4. From 3 blocks after the mint (the seed is the hash of mint block + 2, readable once that block is in the past): `settle(n)` with n ≥ the number of pending batches up to and including yours (`queues()`; about 0.66M gas per batch of 10), or wait for any keeper. Koi and dragons appear in the wallet: `KoiNFT.tokensOfOwnerIn(wallet, 1, KoiNFT.totalSupply() + 1)` lists the ids (scan in chunks of 2,000 ids); `fish(id)` → kind 1 koi / 2 dragon.
5. Track `pendingPearls(id)`, `dailyYieldPerKoi()`, `nextHalvingAt()`, `leapOdds()`.
6. `leap(koiIds)` returns the leap index `i` (also in the `LeapRequested(i, owner, amount, typhoon)` event) → from 3 blocks later `settleLeapIds([i])` (or `settleLeaps(n)` with n covering your leap; about 15–45k gas each). Settle within about an hour (8,190 blocks): an unsettled leap counts as fallen. Check `leaps(i).result` (1 leapt, 2 fell, 3 fell because nobody settled in time). Gas: let the wallet estimate and add headroom; `mintFry` costs about 0.13–0.29M gas (more when the block's buyback runs after the Gate opens); add about 0.2M to an estimate.
7. When `gateOpen()` is true: `claim()`; dragon owners `claimDragons(ids)`.
8. If the owner holds Coldsleep Ark pods: after the Ark is sealed and the Gate is open, read the Ark's `podsOf(wallet)`, keep ids with `isSurvivor(id)` true and `q3Claimed(id)` false here, and tell the owner they can call `claimQ3(ids)` (up to 50 per call is reasonable).

## Read-only helpers
`pondState()` (16 numbers: sold, uniquePayers, paidTotal, reserve, gateOpenedAt, liveKoi, dragons, minted ids, dayIndex, batches pending, leaps pending, pearlsWashed, KOIN burned by buyback, gen1Sold, canOpenGate, KOIN supply), `tierNow()`, `remainingInTier()`, `waveProgress()`, `queues()`, `owed(wallet)`, `pendingDragon(id)`.