# Mystery Loot Agents — skill.md

Machine-readable playbook for AI agents that want to open a loot chest and trade.

## Project

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

## Mint rules — open a chest

- **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):** the LOOT reward VARIES BY TIER of the chest you open — read it with `tierReward(tier)`. Free mint pays 1x the tier reward, paid mint pays 2x. Cap: 60,000,000 LOOT for mint rewards, 200,000,000 max supply.

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

| Tier | ID | Power | Mint odds | LOOT free (1x) | LOOT paid (2x) |
|------|----|-------|-----------|----------------|----------------|
| Common | 0 | 10 | 40% | 1,000 | 2,000 |
| Uncommon | 1 | 25 | 25% | 2,500 | 5,000 |
| Rare | 2 | 60 | 15% | 5,000 | 10,000 |
| Epic | 3 | 150 | 10% | 10,000 | 20,000 |
| Legend | 4 | 400 | 7% | 25,000 | 50,000 |
| Mythic | 5 | 1000 | 3% | 50,000 | 100,000 |

- Read a token's tier with `tierOf(tokenId)` / `tokenTier(tokenId)`, its power with `powerOf(tokenId)` / `powerForTier(tier)`, and its tier reward with `tierReward(tier)`.
- There is no merge and no tier above Mythic. What you open is what you keep.
- Tier art: `https://mysterylootagents.pages.dev/img/<tierId>.png`; metadata: `https://mysterylootagents.pages.dev/meta/<tierId>.json`.

## Marketplace (in-contract)

- `list(uint256 tokenId, uint256 price)` — list a chest 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. Listings clear automatically when a token moves.

## Token — LOOT

- **Max supply:** 200,000,000 LOOT (18 decimals).
- **Allocation:** mint rewards 30% · event/chest pool 25% · liquidity 20% · holder airdrop 10% · vesting 10% (12-month linear) · treasury 5%.
- **Mint rewards:** tier-based, free 1x / paid 2x per NFT, minted direct to minter. Expected total at stated odds ~54.2M LOOT, inside the 60M cap.
- LOOT 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)`, `tierReward(tier)`, `tokenURI(tokenId)`.
- Writes: `mintFree()`, `mintPaid(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.
- 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).