# Pengupunk — guide for AI agents

Punk penguins kept entirely on BNB Chain (chain id 56). Only a wallet that holds a Binance
Agent ID can mint, and it mints to itself. Max 3 per wallet. Supply 2,222.
The page for people is https://pengupunk.github.io/pengupunk/ ; this file is all an agent needs.

## Contracts (BNB Chain, chain id 56)

- NFT, ERC-721 "Pengupunk" (PUNK): 0xE2b3D9043fccc76e6Ce13f84346735F1AA375b5a
- Market "PenguMarket": 0xa2DcdE14A53d84bf488EB271E19d0bcc3c48A418
  - fee 2% + royalty 2.5% (ERC2981) on every fill, both to the treasury
  - list(uint256 tokenId, uint256 priceWei, uint64 durationDays) -> 0xca690ea2
  - cancel(uint256 tokenId) -> 0x40e58ee5
  - buy(uint256 tokenId) payable -> 0xd96a094a
  - bid(uint256 tokenId, uint64 durationDays) payable (escrowed, refundable) -> 0x25e2ba9e
  - acceptBid(uint256 tokenId) -> 0x2b1fd58a
  - listing(uint256) -> 0x84a184de
  - no owner, no pause, no withdraw
  - web UI: https://pengupunk.github.io/pengupunk/market.html
- Agent ID gate; minting wallet needs balanceOf > 0: 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F
- Treasury (receives payment directly): 0x8F3A3882Bfab76538f783c1C63Bf400eBC59CFfc

There is no owner, no pause, no withdraw, no setPrice. All rules were fixed at deploy.

## Rules

- 2,222 in all.
- Price per wallet, counted by how many that wallet already minted:
  - piece #1: FREE, while the collection-wide free quota lasts (223 pieces)
  - piece #2: 0.0005 BNB
  - piece #3: 0.0005 BNB
  - after the 223 free pieces are gone, piece #1 also costs 0.0005 BNB
- 3 per wallet at most, across the whole collection.
- Payment goes straight to the treasury in the same transaction; BNB sent above the price is
  refunded in the same transaction.
- Traits and rarity are sealed until reveal. Before reveal every tokenURI shows SEALED.

## Before minting (eth_call, free)

    totalMinted() -> uint256                       0xa2309ff8
    MAX_SUPPLY() -> uint256                        0x32cb6b0c
    MAX_PER_WALLET() -> uint256                    0x0f2cdd6c
    PRICE_FIRST() -> uint256                       0xa8a4b4f1
    PRICE_SECOND() -> uint256                      0x1315be25
    FREE_QUOTA() -> uint256                        0x3ce16503
    freeGranted() -> uint256                       0x565fb430
    mintedBy(address) -> uint256                   0x3cef28d2
    priceFor(address minter, uint256 qty) -> uint256   0xd527979a
    revealBlock() -> uint256                       0x66bb81c7
    provenanceCommit() -> bytes32                  0x81cd4ce7
    tierOf(uint256) -> string                      0x53f96df2
    rarityScoreOf(uint256) -> uint256              0x062ed425
    mohawkOf(uint256) -> string                    0x362814a6
    shadesOf(uint256) -> string                    0x88d9f71c
    collarOf(uint256) -> string                    0x53acad5c
    accessoryOf(uint256) -> string                 0xef25d975
    backgroundOf(uint256) -> string                0xc4716586
    beakOf(uint256) -> string                      0x2651e417
    tokenURI(uint256) -> string                    0xc87b56dd

Always call priceFor(wallet, qty) before sending a transaction. Send at least that amount; any
excess is refunded, but underpaying reverts with "underpaid".

## Minting

    mint(uint256 qty) payable                      0xa0712d68

qty is 1..3 and mintedBy(msg.sender) + qty must be <= 3.

Example: a fresh agent wallet mints 3 pieces (1 free + 2 paid while quota lasts):
send value = 0.001 BNB, calldata = 0xa0712d68 + uint256(3).

A wallet that already has 1 piece mints 1 more: price 0.0005 BNB. Minting only the free piece: value = 0.

Revert reasons: "not agent", "max per wallet", "sold out", "qty", "underpaid".

## Reveal

- revealBlock was fixed at deploy: 129712669. Before that block, traits do not exist.
- provenanceCommit = keccak256(secret), published at deploy.
- After revealBlock anyone may call reveal(bytes32 secret) 0x701fd0f1 once. The contract checks
  keccak256(secret) == provenanceCommit and derives the seed from blockhash(revealBlock) + secret,
  so the ordering and traits could not be chosen by the deployer.
- Until reveal: tokenURI returns a SEALED image and no traits.

## Traits and rarity

Six accessory slots, each drawn from the token hash with published weights:

    mohawk     none 45 · single 26 · wide 16 · twin 9 · flame 4
    shades     none 40 · narrow 30 · round 16 · visor 10 · eyepatch 4
    collar     none 42 · studs 30 · spikes 18 · chain 10
    accessory  none 40 · earring 24 · pin 18 · patch 11 · tattoo 5 · bandana 2
    background void 50 · teal 24 · crimson 15 · gold 8 · static 3
    beak       normal 70 · goldtooth 20 · scar 8 · bandaid 2

rarityScore = product of the six chosen weights (smaller = rarer). Tier thresholds:

    Mythic      <= 3,456,000
    Legendary   <= 11,182,080
    Epic        <= 37,440,000
    Rare        <= 131,040,000
    Uncommon    <= 476,280,000
    Common      otherwise

Expected distribution over 2,222 tokens: Common 54.9% · Uncommon 25.1% · Rare 13.0% · Epic 5.0%
· Legendary 1.5% · Mythic 0.5%.

## Royalty

EIP-2981, 250 bps (2.5%) to the treasury. Marketplaces that honour 2981 pay it; those that do
not, do not.

## Source

https://github.com/pengupunk/pengupunk — the exact source that produced the deployed bytecode.

## Paste this to your agent

Mint 1 Pengupunk on BNB Chain with my Binance Agentic Wallet.

Contract: 0xE2b3D9043fccc76e6Ce13f84346735F1AA375b5a
1. eth_call priceFor(myAddress, 1) — selector 0xd527979a
2. send mint(1) — selector 0xa0712d68 — value = result of step 1
3. verify: Transfer from 0x0 to myAddress, balanceOf(myAddress) == 1

Gate: .ai Agent ID (balanceOf > 0 on 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F).
Rules: max 3 per wallet · first piece 0.0005 BNB (223 free pieces are gone) · no owner, no pause, no approval.