# MESO PROTOCOL > On-chain specimen protocol on BNB Smart Chain. Fixed supply 3000 NFTs, five on-chain stages, > 5% ERC-2981 royalty shared with ascended holders. Rules live in the contract; no off-chain promises. ## MCP (one-line agent onboarding) mcp add meso https://hongwu.cloud/meso/mcp Tools (no keys, no signatures needed): - meso_overview contracts, supply, fees, floor prices (floorPrice(uint256), 4 tiers) - meso_specimen one specimen: stage, rarity, xp, owner, listing, offer - meso_specimens recent specimens from the on-chain index - meso_reserve reserve buckets + public allocation - meso_excavation_rules fixed-amount table, open state, expected value - meso_verify recompute one excavation (message + digest + weight table) - meso_contracts addresses + function signatures for local signing - meso_docs protocol summary and links - meso_build_tx encode an action into {to,data,value} ready to broadcast - meso_preflight dry-run that action: will it succeed, why not, what it costs - meso_session 24h session token for hosted wallets (no personal_sign) ### Recommended write flow (no wasted gas) 1. meso_build_tx -> {to, data, value} 2. meso_preflight -> wouldSucceed, stateChecks, cost 3. broadcast only when wouldSucceed is true meso_preflight runs eth_call against live chain state: zero gas, no signature. It separates "contract would revert" (contractAcceptsCall=false) from "your wallet cannot pay" (stateChecks) — these need different fixes. Writes are never done for you: get addresses/signatures from meso_contracts and sign locally. ## Contracts (BNB Smart Chain, chainId 56) - NFT (ERC-721): 0x054237fe97dad04FB51526dB15aA386075054710 - Marketplace (list / buy / offers): 0xc88244FbCEdF927D7BBBc05B8f3090979d903281 - Floor fund (ascended buyback): 0x297F97be9f16bec1f85c1A8d37b0eca9C9B68dF3 - Source verification: https://sourcify.dev/#/lookup/0x054237fe97dad04FB51526dB15aA386075054710 ## Machine-readable - Live stats JSON: https://hongwu.cloud/meso/api/stats - Agent manifest: https://hongwu.cloud/meso/agents.json - Agent guide: https://hongwu.cloud/meso/agents.md - ABI: https://hongwu.cloud/meso/meta/abi.json - Traits + rarity table: https://hongwu.cloud/meso/meta/traits.json ## What it is 1. Mint an egg (stage 0). Rarity is hidden until hatch. 2. Hatch after the hatch delay (1h at time of writing; read the live value of hatchDelay()): rarity becomes public (common 55% / rare 30% / epic 12% / legendary 3%). 3. Feed on a cooldown (1h at time of writing; read live value from /api/stats) to gain XP; higher rarity earns more XP per feed. 4. Evolve at XP thresholds: hatchling (1) -> juvenile (2) -> adult (3) -> ascended (4). 5. Ascended supply is capped (300). Royalty revenue is split with ascended holders. ## Parameters (read live values from /api/stats) - maxSupply 3000, ascended cap 300, max 3 per wallet - first mint per address is free; paid mints follow an upward price ladder (0.0005 -> 0.001 -> 0.002 -> 0.004 -> 0.008 BNB) keyed to supply, never decreasing; hard cap 3 per wallet - first 300 genesis slots are free (coupon signature); later mints follow an upward ladder; no Agent ID needed - the free first-mint signature is issued by the public endpoint: GET https://hongwu.cloud/meso/api/coupon?address= Eligibility is enforced on-chain: the contract recovers the signer, so a forged or re-used coupon reverts. Check before claiming: GET /meso/api/coupon/status?address=0x... ### Mint (first free, then upward ladder) ``` function mintWithInvite(uint256 nonce, address referrer, bytes signature) external // nonpayable ``` 1. Read `inviteSigner()` from the NFT contract; the signature must come from that address. 2. Send the call with **value = 0**. One unused signature covers exactly one specimen. 3. Confirm with `couponUsed(yourAddress)` -> true after the call. 4. Get the signature from GET https://hongwu.cloud/meso/api/coupon?address=. Check GET /meso/api/coupon/status?address= first: canClaim=false means the address already used its free mint. ### Paid mint ``` function mint() external payable // send exactly price(), cap 3 per wallet ``` - hatch fee 0 (currently free) - feed fees 0.00005 / 0.0001 / 0.00015 BNB by stage (hatchling / juvenile / adult) - market fee 2%; royalty 5% ## How to interact (programmatic) - Read: plain JSON-RPC eth_call against https://hongwu.cloud/meso/rpc or any BSC node. - Write: standard signed transactions to the NFT or marketplace contract. - Machine quickstart: GET https://hongwu.cloud/meso/quickstart.json (contracts, prices, steps, risks in one JSON), - Zero-cost trial: GET https://hongwu.cloud/api/meso/simulate — all-in cost per rarity, feeds needed, hours to ascend. Read-only, nothing signed, no wallet needed. - Build the tx for me: GET https://hongwu.cloud/api/meso/action?address=&step=mint|hatch|feed|evolve&tokenId= returns {chain_id, to, data, value_wei} ready to sign; the server eth_calls it first and reports the real revert (cooldown / not owner / too early / not enough xp) instead of guessing. - What can I do now: GET https://hongwu.cloud/api/meso/actions?address= — every specimen you own with its next step. ## Honest limitations - Rarity derives from block hash, not a verifiable randomness beacon. - Metadata and images are served from this domain, not IPFS. - No floor price is promised. The floor fund pays `floorPrice(uint256)` per stage (1-4 = 0.012 / 0.022 / 0.030 / 0.040 BNB) but only while its balance covers it; the fund currently holds 0.0037 BNB, well below one unit, so buyback is not available in practice yet. Read `eth_getBalance(fund)` before assuming liquidity. - Market data is only what the chain shows; zero trades means zero volume. ## Verification checklist for agents 1. GET /api/stats -> compare contract addresses and minted count. 2. eth_call maxSupply(), ascendedCap(), hatchFee(), feedCooldown() -> must match docs. 3. Check listings via marketplace listings(tokenId).