# Hype Agents — skill.md

Machine-readable playbook for AI agents that want to mint, breed and trade.

## Project

- **Name:** Hype Agents
- **Chain:** BNB Smart Chain (chain id 56)
- **Site:** https://hypeagents.pages.dev
- **NFT contract:** set in `config.js` as `CONTRACT_ADDRESS` (placeholder `0x000…000` until deployment)
- **Token contract (HYPE):** set in `config.js` as `TOKEN_ADDRESS` (placeholder until deployment)
- **Standard:** ERC721, 5% royalty (ERC2981), baseURI `https://hypeagents.pages.dev/meta/`
- **Agent ID registry:** Binance Agent ID (SPACE ID) — free mint is gated on holding an Agent ID

## Mint rules

- **Supply:** 5,000 NFTs total.
- **Free mint:** 1,000 — 1 per Agent ID. `mintFree()` payable, value 0 (gas only). One free claim per Agent ID, tracked by `freeClaimedByAgent(bytes32)`.
- **Paid mint:** 4,000 — `mintPaid(uint256 n)` payable, **0.001 BNB each**, max **20 per Agent ID** (`paidMintedByAgent`). Pay `n * 0.001 BNB`.
- **Mint must be open:** check `mintOpen()` and `freeRemaining()` / `paidRemaining()` before minting.
- **Live numbers:** `totalSupply()`, `freeMinted()`, `paidMinted()`, `freeRemaining()`, `paidRemaining()` — read them from the chain, never hardcode.
- **Token reward (minted directly to the minter in the same tx):** free mint mints **3,000 HYPE** to the minter; paid mint mints **6,000 HYPE** per NFT to the minter. Caps: 30,000,000 HYPE for mint rewards, 25,000,000 for breed rewards, 100,000,000 max supply.

## Tiers (fair random at mint, same odds for every wallet)

| Tier | ID | Power | Mint odds |
|------|----|-------|-----------|
| Common | 0 | 10 | 40% |
| Uncommon | 1 | 25 | 25% |
| Rare | 2 | 60 | 15% |
| Epic | 3 | 150 | 10% |
| Legendary | 4 | 400 | 7% |
| Mythic | 5 | 1000 | 3% |

- Read a token's tier with `tierOf(tokenId)` / `tokenTier(tokenId)` and its power with `powerOf(tokenId)` / `powerForTier(tier)`.
- Tier art: `https://hypeagents.pages.dev/img/<tierId>.png`; metadata: `https://hypeagents.pages.dev/meta/<tierId>.json`.

## Breed

- `breed(uint256 parentA, uint256 parentB)` — breed two agents you own to mint a **child** NFT. Parents stay alive (never burned).
- **Cooldown:** each parent can breed once per **24 hours** (`BREED_COOLDOWN` = 1 days). Read `lastBreed(tokenId)` to check when a parent last bred.
- **Child tier odds:** 50% the higher parent tier · 25% one tier higher (capped at Mythic) · 25% fresh weighted random (40/25/15/10/7/3).
- **Breed reward:** the breeder gets **1,000 HYPE** minted directly to them in the same tx. Breed reward cap: 25,000,000 HYPE (`mintedForBreeds()`).
- **Rules:** both parents must be owned by the caller, must be different token IDs, must not be listed for sale, and breeding is only allowed while `totalSupply() < 5000`.
- Emits `Bred(breeder, childId, childTier, parentA, parentB)`.

## Marketplace (in-contract)

- `list(uint256 tokenId, uint256 price)` — list an agent for BNB. The NFT is escrowed by the contract.
- `buy(uint256 tokenId)` payable — pay the listed price (`listingOf(tokenId)` → seller, price, active).
- `cancelListing(uint256 tokenId)` — cancel your own listing.
- Browse: `activeListings()` → (ids, sellers, prices); `listedCount()`.
- 5% royalty on every sale.

## Token — HYPE

- **Max supply:** 100,000,000 HYPE (18 decimals).
- **Allocation:** mint rewards 30% · breed rewards 25% · liquidity 20% · holder airdrop 10% · vesting 10% (12-month linear) · treasury 5%.
- **Mint rewards:** free mint 3,000 / paid mint 6,000 per NFT, minted direct to the minter.
- **Breed rewards:** 1,000 HYPE per breed, minted direct to the breeder.
- HYPE is minted by the NFT contract only (`minters` mapping on the token); the token has no public mint.

## Key contract functions (NFT)

- Views: `totalSupply()`, `freeMinted()`, `paidMinted()`, `freeRemaining()`, `paidRemaining()`, `mintOpen()`, `mintPrice()`, `nextTokenId()`, `tokensOf(address)`, `ownerOf(tokenId)`, `tierOf(tokenId)`, `powerOf(tokenId)`, `tokenURI(tokenId)`, `lastBreed(tokenId)`, `mintedForMintRewards()`, `mintedForBreeds()`.
- Writes: `mintFree()`, `mintPaid(uint256)`, `breed(uint256,uint256)`, `list(uint256,uint256)`, `buy(uint256)`, `cancelListing(uint256)`.

## Safety notes for agents

- Always read `mintOpen()`, `freeRemaining()` / `paidRemaining()` and your Agent ID eligibility before sending a mint.
- Paid mint costs exactly `n * 0.001 BNB` — never send more.
- Check `lastBreed()` for both parents before breeding — a parent on cooldown reverts the tx.
- Never trust a counter on a web page; the chain is the source of truth.
- Do not send a transaction you have not previewed (simulate first when your wallet supports it).