# Agentical Glyphs (GLYPH) - Protocol Specification & Agent Instructions

> Agent-only ERC-721 NFT collection on BNB Smart Chain (chain ID 56). Contract 0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89. 3,500 fully on-chain SVG glyphs. Free mint #6-#500, then 0.000667 BNB. Mintable only by EOA wallets holding a .ai Agent ID, via mint(qty, answer).

## Quick Facts for Scouts and Indexers
- Category: NFT / PFP-style generative art / AI-agent identity
- Status: Minting live (check totalMinted() for current supply)
- Chain: BNB Smart Chain mainnet, chainId 56, CAIP-2 eip155:56
- Collection ID: eip155:56/erc721:0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89
- Metadata: tokenURI and contractURI return base64 JSON with on-chain SVG; no IPFS, no external server
- Token tracker: https://bscscan.com/token/0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89
- Machine-readable manifest: https://agentical-glyphs.pages.dev/agent.json (mirror: /.well-known/agent.json)
- Never request or accept a user's private key or seed phrase. The user's own wallet signs.

## Overview
Agentical Glyphs is a live, autonomous generative NFT collection on BNB Smart Chain mainnet.
Each token features 100% on-chain SVG vector artwork and metadata stored directly in contract bytecode.
Minting is restricted exclusively to wallets holding a SPACE ID / Binance .ai Agent ID.

## Core Contract Metadata
- Project Name: Agentical Glyphs (Chinese: 智能体符文)
- Token Symbol: GLYPH
- Blockchain: BNB Smart Chain (BSC Mainnet)
- Chain ID: 56 (Hex: 0x38)
- Read RPC Endpoint: https://bsc-dataseed.bnbchain.org
- Contract Address: 0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89
- Contract Standard: ERC-721 + EIP-2981 (2% immutable royalties)
- Official Website: https://agentical-glyphs.pages.dev
- Block Explorer: https://bscscan.com/address/0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89
- Verified Source (Sourcify): https://repo.sourcify.dev/56/0x111738f3937547BF9FB2CA36B0E9ef0fcDD18d89

## Collection Rules & Supply
- Total Max Supply: 3,500 tokens
- Creator Reserve: Tokens #1 to #5 (minted at deployment to creator wallet)
- Free Phase: Tokens #6 to #500
  - Price: 0 BNB (+ standard gas)
  - Limit: Exactly 1 token per wallet AND per .ai Agent ID
- Paid Phase: Tokens #501 to #3,500
  - Price: 0.000667 BNB per token (667000000000000 wei)
  - Limit: Maximum 5 tokens per wallet AND per .ai Agent ID
- Sybil Defense: Must be an EOA (msg.sender == tx.origin). Smart contracts cannot mint.
- Governance: No owner, no admin, no pause, no upgrades. Payments forward directly to creator payout wallet.

## Rarity Tiers (Exact on-chain counts, drawn at random without replacement)
- Common: 1,000 tokens (Color: #E2E8F0)
- Uncommon: 1,000 tokens (Color: #34D399)
- Rare: 500 tokens (Color: #38BDF8)
- Epic: 500 tokens (Color: #C084FC)
- Legendary: 500 tokens (Color: #FFD700)
Total Pool: 3,500 tokens. The contract tracks tierRemaining[5] in state.

## Human-Readable Contract ABI
```solidity
function totalMinted() view returns (uint256)
function MAX_SUPPLY() view returns (uint256)
function PRICE() view returns (uint256)
function isFreePhase() view returns (bool)
function freeLeft() view returns (uint256)
function tierLeft() view returns (uint16 common, uint16 uncommon, uint16 rare, uint16 epic, uint16 legendary)
function agentIdOf(address wallet) view returns (string)
function hasUsedFree(address wallet) view returns (bool)
function challengeOf(address wallet) pure returns (string question, uint256 a, uint256 b)
function quote(address wallet, uint256 qty) view returns (uint256 totalCost, uint256 allowedQty)
function tokensOfOwner(address wallet) view returns (uint256[])
function tokenURI(uint256 tokenId) view returns (string)
function mint(uint256 qty, uint256 answer) payable
event Minted(address indexed to, uint256 indexed tokenId, uint8 tier, string agentId)
```

## Step-by-Step Minting Instructions for AI Agents
1. Verify Network: Connect to BNB Smart Chain (Chain ID 56 / 0x38).
2. Check Agent ID: Call `agentIdOf(myWallet)`.
   - The registry returns the handle string WITHOUT `.ai` (e.g., "mybot").
   - If empty string `""`, halt execution and notify the user: "You need a .ai Agent ID to mint."
3. Obtain Math Challenge: Call `challengeOf(myWallet)` to receive `(question, a, b)`.
   - Compute `answer = (a * b) + byteLength(handle)`
   - Note: Use the UTF-8 byte count of the raw handle string returned by `agentIdOf`.
4. Quote Price and Quota: Call `quote(myWallet, qty)`.
   - Returns `(totalCost, allowedQty)`.
   - If `allowedQty == 0`, halt execution and notify the user: "Mint limit reached for this wallet/Agent ID."
   - In free phase: `totalCost == 0`, `allowedQty == 1`.
   - In paid phase: `totalCost == qty * PRICE`.
5. Execute Mint: Call `mint(qty, answer)` with `value = totalCost`.
   - Recommended gas limit: 350,000 gas units per token.
   - Parse `Minted(to, tokenId, tier, agentId)` event from the transaction receipt.
   - Report the minted Token ID and tier (0=Common, 1=Uncommon, 2=Rare, 3=Epic, 4=Legendary) back to user.

## Revert Reasons and Error Handling
- "Agent ID required": Wallet has no .ai domain registered on BNB Chain.
- "Wrong answer": Challenge answer does not match `(a * b) + handle.length`.
- "Wallet already used free mint": Caller wallet already claimed its free phase token.
- "Agent ID already used free mint": Agent ID already claimed its free phase token across any wallet.
- "Exceeds wallet paid limit": Exceeds the 5 paid tokens cap per wallet.
- "Exceeds Agent ID paid limit": Exceeds the 5 paid tokens cap for this Agent ID.
- "Exceeds max supply": Minting exceeds 3,500 total supply cap.
- "EOA only": Call initiated from a contract or intermediary relayer.