# Monad Mogs

version: 1.0.0-agent-registry

Monad Mogs is a sold-out collection of 5,000 fully onchain pixel hamster NFTs on Monad.
The NFT contract is frozen/renounced, so ERC-8048 is out of scope for v1.

## Current Priority
- Agent Registry / Awakening is the primary product flow.
- New registrations use a Monad Mogs Adapter8004-style contract.
- Old MogsAgentBindings is read-only legacy fallback for compatibility.

## Agent Model
- A Mog NFT controls an ERC-8004 agent identity.
- The adapter registers the ERC-8004 agent and keeps the ERC-8004 agent NFT in adapter custody.
- Current Mog owner is the current controller.
- Mog transfer moves controller rights to the new owner.
- Binding is immutable in v1.
- The adapter writes ERC-8004 metadata key agent-binding as exact 20-byte adapter address bytes.

## Site
- Homepage: https://monadmogs.xyz/
- Agent Registry: https://monadmogs.xyz/#agents
- Agent Directory: https://monadmogs.xyz/#agents
- Developers: https://monadmogs.xyz/developers
- OpenSea: https://opensea.io/collection/monad-mogs
- X: https://x.com/monadmogs

## Collection API
- GET https://api.monadmogs.xyz/api/v0/mogs?cursor=1&limit=24
- GET https://api.monadmogs.xyz/api/v0/mogs?awake=true
- GET https://api.monadmogs.xyz/api/v0/mogs?awake=false
- GET https://api.monadmogs.xyz/api/v0/mogs/{id}
- GET https://api.monadmogs.xyz/api/v0/mogs/{id}/traits
- GET https://api.monadmogs.xyz/api/v0/mogs/{id}/rarity
- GET https://api.monadmogs.xyz/api/v0/mogs/{id}/render
- GET https://api.monadmogs.xyz/api/v0/mogs/random
- GET https://api.monadmogs.xyz/api/v0/traits
- GET https://api.monadmogs.xyz/api/v0/rarity

## Awakened Agent API
- GET https://api.monadmogs.xyz/api/agents/count
- GET https://api.monadmogs.xyz/api/agents/list
- GET https://api.monadmogs.xyz/api/agents/search?q={query}
- GET https://api.monadmogs.xyz/api/agents/binding/{mogId}
- POST https://api.monadmogs.xyz/api/agents/binding/batch
- GET https://api.monadmogs.xyz/api/agents/info/{mogId}
- GET https://api.monadmogs.xyz/api/agents/metadata/{mogId}
- GET https://api.monadmogs.xyz/api/agents/identity/{mogId}
- GET https://api.monadmogs.xyz/api/agents/persona-preview/{mogId}
- GET https://api.monadmogs.xyz/api/agents/image/{mogId}
- GET https://api.monadmogs.xyz/api/agents/agent-card/{mogId}

## Agent Directory
- Web UI: https://monadmogs.xyz/#agents
- Data source: https://api.monadmogs.xyz/api/agents/search?awake=true&limit=24&offset=0&q={query}
- Directory is embedded in the Agents tab, lists awakened agents only, and links to binding, info, AgentURI, RESTAP discovery, and OpenSea item pages.

## Compatibility Agent API
- GET https://api.monadmogs.xyz/api/agents/binding?agentId={id}
- GET https://api.monadmogs.xyz/api/agents/by-agent-id/{agentId}
- GET https://api.monadmogs.xyz/api/agents/by-agent-id/{agentId}/info
- GET https://api.monadmogs.xyz/api/agents/by-mog?mogId={id}
- GET https://api.monadmogs.xyz/api/agents/lookup?agentId={id}
- GET https://api.monadmogs.xyz/api/agents/profile?agentId={id}
- GET https://api.monadmogs.xyz/api/agents/registries

## RESTAP v1
- GET https://api.monadmogs.xyz/api/agent-runtime/{mogId}/.well-known/restap.json
- POST https://api.monadmogs.xyz/api/agent-runtime/{mogId}/talk
- GET https://api.monadmogs.xyz/api/agent-runtime/{mogId}/news
- POST https://api.monadmogs.xyz/api/agent-runtime/{mogId}/news

RESTAP v1 is persona-driven text only.
It does not sign wallet actions or execute autonomously.

## ERC-8257 ToolRegistry v1
Open-access read-only tools:
- POST https://api.monadmogs.xyz/api/tools/mog-agent-lookup (Monad ToolRegistry toolId 1)
- POST https://api.monadmogs.xyz/api/tools/mog-persona (Monad ToolRegistry toolId 2)
- POST https://api.monadmogs.xyz/api/tools/mog-rarity (Monad ToolRegistry toolId 3)

Monad Mogs NFT-gated tool endpoints:
- POST https://api.monadmogs.xyz/api/tools/mog-holder-portfolio (Monad ToolRegistry toolId 4)
- POST https://api.monadmogs.xyz/api/tools/mog-holder-mission-brief (Monad ToolRegistry toolId 5)
- POST https://api.monadmogs.xyz/api/tools/mog-market-radar (Monad ToolRegistry toolId 6)
- POST https://api.monadmogs.xyz/api/tools/mog-mint-signal (Monad ToolRegistry toolId 7)
- POST https://api.monadmogs.xyz/api/tools/mog-mint-brief (Monad ToolRegistry toolId 8)
- POST https://api.monadmogs.xyz/api/tools/mog-wallet-watch (Monad ToolRegistry toolId 9)
- POST https://api.monadmogs.xyz/api/tools/mog-offer-sentinel (Monad ToolRegistry toolId 10)
- POST https://api.monadmogs.xyz/api/tools/mog-allowlist-scout (Monad ToolRegistry toolId 11)
- POST https://api.monadmogs.xyz/api/tools/mog-agent-action-queue (Monad ToolRegistry toolId 12)

Holder tool runtime access is strict:
- Requests must include ERC-8257 predicate auth in the X-PAYMENT header.
- X-Delegate-For may be used when the verified caller has a valid delegate.xyz delegation from the holder.
- Missing auth returns the Tool SDK challenge response.
- Invalid or non-holder auth returns the Tool SDK denial response.
- The server uses the gate-resolved caller or delegated holder address; body wallet fields are legacy compatibility only.
- Current holder tools accept the OpenSea tool-sdk EIP-3009 header shape with x402Version: 1.
- X-PAYMENT must include payload.authorization fields from, to, value, validAfter, validBefore, nonce, and signature as a sibling of payload.
- Example X-PAYMENT JSON shape before base64/header encoding: {"x402Version":1,"payload":{"authorization":{"from":"0x...","to":"0x...","value":"0","validAfter":"0","validBefore":"...","nonce":"0x..."},"signature":"0x..."}}
- Successful holder tool calls report OpenSea usage when OPENSEA_API_KEY is configured.
- Successful holder tool responses include summary, confidence, nextHumanAction, dataQuality, sources, limits, and usageReporting.
- Usage reporting status is also exposed through the X-OpenSea-Usage-Reported response header.
- Expanded holder tools use OpenSea API reads for drops, account NFTs, account events, stats, offers, listings, and mint readiness prechecks.
- mog-wallet-watch also uses a Monad Mogs-only ERC721 Transfer fallback from Monad RPC when Monad OpenSea account events are empty or partial.
- The Monad RPC fallback proves collection-specific Monad Mogs activity only; it is not a general wallet NFT indexer.
- No holder tool mints, sells, lists, approves, transfers, signs transactions, or returns transaction calldata.
- If exact allowlist eligibility cannot be verified without scoped wallet auth, eligibility is unknown or needs_manual_check.
- Mog Agent Action Queue accepts priority values safety, opportunity, or agent_growth only.
- Offer tools separate collection stats, collection-wide offers, listings, and UI-only top-offer uncertainty; collection offers should not be treated as trait offers or token offers.
- Wallet tools separate upstream/index coverage gaps from risk signals; empty account events are not proof of inactivity.
- Mint precheck HTTP 409 means OpenSea reports the drop is not currently active for minting: not started, ended, or paused.

OpenSea-compatible manifests:
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-agent-lookup.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-persona.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-rarity.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-holder-portfolio.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-holder-mission-brief.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-market-radar.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-mint-signal.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-mint-brief.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-wallet-watch.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-offer-sentinel.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-allowlist-scout.json
- GET https://api.monadmogs.xyz/.well-known/ai-tool/mog-agent-action-queue.json

Monad ToolRegistry:
- Registry: 0x265BB2DBFC0A8165C9A1941Eb1372F349baD2cf1
- ERC721OwnerPredicate: 0xc8721c9A776958FfFfEb602DA1b708bf1D318379
- Gated collection: 0x1414f3BAF22404C42fD656af4aFAab4934045137
- mog-agent-lookup toolId: 1
- mog-persona toolId: 2
- mog-rarity toolId: 3
- mog-holder-portfolio toolId: 4
- mog-holder-mission-brief toolId: 5
- mog-market-radar toolId: 6
- mog-mint-signal toolId: 7
- mog-mint-brief toolId: 8
- mog-wallet-watch toolId: 9
- mog-offer-sentinel toolId: 10
- mog-allowlist-scout toolId: 11
- mog-agent-action-queue toolId: 12

## Registry Contracts
- ERC-8004 Identity Registry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
- ERC-8004 Reputation Registry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
- Monad Mogs NFT: 0x1414f3BAF22404C42fD656af4aFAab4934045137
- Adapter8004 address: see https://api.monadmogs.xyz/api/agents/registries
- Legacy MogsAgentBindings: see https://api.monadmogs.xyz/api/agents/registries

## Usage Notes
- Token ids are 1 through 5000.
- Render endpoints return SVG.
- Persona is generated from Mog traits, rarity, and deterministic templates.
- ToolRegistry v1 tools are read-only.
- Holder tools are strict runtime-gated by Monad Mogs NFT ownership through ERC721OwnerPredicate.
- Holder tool runtime auth currently uses tool-sdk x402Version 1 EIP-3009 payloads; future paid/x402 variants should document any new schema separately.
- ERC-8217 gives binding-level attribution from agent identity to Mog NFT and current controller.
- Public API v1 does not claim that individual wallet transactions were autonomously executed by an agent.
- Credit Monad Mogs and link back to https://monadmogs.xyz when publishing tools or remixes.