# MegaChad — Complete Agent Reference

> Burn-to-create looksmaxxing engine on MegaETH. Burn $MEGACHAD tokens to generate AI-enhanced portraits, mint NFTs, and earn on-chain reputation. ERC-8004 registered agent with x402 payment support.

## Overview

MegaChad is a burn-to-create protocol on MegaETH (chain ID 4326). Users burn 225,000 $MEGACHAD tokens along with a 1 USDm infra fee via the x402 payment protocol to generate AI looksmaxxed portraits and mint them as NFTs.

Two tokens exist:
- **$MEGACHAD** — primary burn token (ERC-20)
- **$MEGAGOONER** — governance/reward token minted via burn participation (50M cap, 225-week quadratic emission)

On-chain agent identity: ERC-8004 Agent #12408

## Chain & Network

- **Chain:** MegaETH
- **Chain ID:** 4326
- **RPC:** https://mainnet.megaeth.com/rpc
- **Explorer:** https://megaexplorer.xyz

## Contract Addresses

| Contract | Address |
|----------|---------|
| $MEGACHAD Token | 0x374A17bd16B5cD76aaeFC9EAF76aE07e9aF3d888 |
| Looksmaxxed NFT | 0x1f1eFd3476b95091B9332b2d36a24bDE12CC6296 |
| Burn Address | 0x000000000000000000000000000000000000dEaD |
| Tren Fund Wallet | 0x85bf9272DEA7dff1781F71473187b96c6f2f370C |
| Kumbaya Swap Router | 0xE5BbEF8De2DB447a7432A47EBa58924d94eE470e |
| Kumbaya Quoter V2 | 0x1F1a8dC7E138C34b503Ca080962aC10B75384a27 |
| WETH | 0x4200000000000000000000000000000000000006 |
| USDm Token | 0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7 |
| USDm Forwarder | 0x2c2d8EF0664432BA243deF0b8f60aF7aB43a60B4 |
| Meridian Facilitator | 0x8E7769D440b3460b92159Dd9C6D17302b036e2d6 |
| ERC-8004 Identity Registry | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 |
| ERC-8004 Reputation Registry | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63 |

## Protocol Discovery

| Standard | URL |
|----------|-----|
| OpenAPI 3.1 | https://megachad.xyz/.well-known/openapi.json |
| ERC-8004 Registration | https://megachad.xyz/.well-known/agent-registration.json |
| A2A Agent Card | https://megachad.xyz/.well-known/agent.json |
| MCP Server | https://megachad.xyz/api/mcp |
| LLM Index | https://megachad.xyz/llms.txt |
| SSE Events | https://megachad.xyz/api/events |

## API Endpoints

### GET /api/price
Returns current $MEGACHAD price in ETH from Kumbaya DEX pool.

Response:
```json
{
  "token": { "address": "0x...", "symbol": "MEGACHAD", "decimals": 18 },
  "price": {
    "megachadPerEth": 50000000,
    "ethPerMegachad": 0.00000002,
    "ethPerMillionMegachad": "0.02"
  },
  "burnCost": { "tokensRequired": 225000, "estimatedEth": 0.0045, "infraFeeUsdm": 1 },
  "pool": { "dex": "Kumbaya", "feeTier": 10000, "pair": "MEGACHAD/WETH" },
  "timestamp": "2026-03-17T00:00:00.000Z"
}
```

### GET /api/wallet?address=0x...
Returns wallet balances, NFT count, burn eligibility, and early access status.

Response:
```json
{
  "address": "0x...",
  "balances": {
    "eth": "1.5",
    "megachad": 500000,
    "looksmaxxedNFTs": 2
  },
  "burnEligibility": {
    "canBurn": true,
    "burnRequirement": 225000,
    "tokensNeeded": 0,
    "message": "Ready to burn 225000 $MEGACHAD"
  },
  "earlyAccess": {
    "instantAccess": false,
    "referralPath": true,
    "eligible": true
  }
}
```

### GET /api/x402/quote?ethAmount=0.1
Returns swap quote and pre-built transaction parameters for buying $MEGACHAD with ETH via Kumbaya DEX.

Response includes:
- Quote (ETH in, MEGACHAD out, has enough for burn)
- Pre-built swap calldata (router address, function params, msg.value)
- Chain info

### GET /api/x402/looksmaxx
Returns HTTP 402 with x402 payment requirements and $MEGACHAD burn requirements.

Headers: `X-Payment-Required: true`, `X-402-Version: 1`

Response includes:
- x402 payment requirements (1 USDm via Meridian)
- Burn requirements (225,000 tokens split 50/50)
- Step-by-step instructions

### POST /api/x402/looksmaxx
Submits burn proof + x402 payment + base64 image for looksmaxxing.

Request body:
```json
{
  "burnTxHash": "0x...",
  "devTxHash": "0x...",
  "burnerAddress": "0x...",
  "image": "<base64>",
  "imageType": "image/png",
  "paymentPayload": { "payload": { "signature": "0x..." } }
}
```

Response:
```json
{
  "success": true,
  "imageUrl": "https://...",
  "ipfsCid": "Qm...",
  "ipfsUrl": "https://gateway.pinata.cloud/ipfs/Qm...",
  "tokenId": "42",
  "burnTxHash": "0x...",
  "devTxHash": "0x..."
}
```

### GET /api/agent/looksmaxx?wallet=0x...&ethAmount=0.5
Returns the complete orchestrated looksmaxx flow as ordered steps with pre-built calldata. This is the recommended endpoint for agents — it handles the complexity of multi-step sequencing.

Response:
```json
{
  "wallet": "0x...",
  "currentState": { "ethBalance": "1.5", "megachadBalance": 0, "hasEnoughTokens": false },
  "steps": [
    { "step": 1, "action": "swap", "transaction": { "to": "0x...", "data": "0x...", "value": "..." } },
    { "step": 2, "action": "burn", "transaction": { "to": "0x...", "data": "0x..." } },
    { "step": 3, "action": "tren_fund", "transaction": { "to": "0x...", "data": "0x..." } },
    { "step": 4, "action": "submit", "postRequest": { "method": "POST", "url": "...", "bodyTemplate": {} } }
  ]
}
```

### GET /api/stats
Returns token statistics: total supply, circulating supply, tokens burned, total burn count.

### GET /api/gallery?limit=20&offset=0
Returns paginated list of recent looksmaxxed burns with IPFS image URLs.

### GET /api/chadboard
Returns burner leaderboard with ERC-8004 reputation scores, .mega domain names, and profile info.

### GET /api/agent/info
Returns ERC-8004 registration metadata, on-chain identity, and contract addresses.

### POST /api/early/register
Register a wallet for testnet beta access. Verifies on-chain eligibility.

Request: `{ "wallet": "0x...", "twitter": "@handle", "referralCode": "abc123" }`
Response: `{ "success": true, "referralCode": "...", "referralLink": "...", "eligibility": { ... } }`

### GET /api/bridge
Returns bridge information for moving assets to MegaETH from other chains.

### GET /api/events
Server-Sent Events stream. Emits `stats`, `burn`, and `heartbeat` events. Reconnect after 55s.

### GET /api/metadata/{tokenId}
Returns ERC-721 metadata for a looksmaxxed NFT.

### POST /api/agent/chat
Natural language transaction engine. POST plain English and receive structured responses with calldata. Supports 17 intents including swap, burn, looksmaxx, cross-chain, compare, schedule, and multi-burn.

Request: `{ "message": "looksmaxx 0xYOUR_WALLET" }`

### GET|POST /api/agent/register
Register as a referral agent. Earn 5% (11,250 $MEGACHAD) per referred burn.

### GET /api/agent/referrals?address=0x...
Returns referral count, earnings, and reward info for a registered agent.

### GET /api/cross-chain/intent?sourceChain=base&wallet=0x...
Build a cross-chain looksmaxx plan from any of 10 chains. Returns bridge → swap → burn → generate → mint steps.

### GET /api/cross-chain/status?id=cc_...
Track cross-chain intent progress.

### GET /api/identity/{address}
Unified MegaETH identity profile — MegaNames, balances, burn history, reputation, tier, referral stats. Accepts 0x addresses or .mega names.

### GET /api/portal/tokens?address=0x...
All MegaETH token balances for a wallet (ETH, WETH, MEGACHAD, USDm).

### GET /api/portal/protocols
Curated MegaETH protocol directory.

### GET|POST /api/gasless/burn
EIP-712 gasless burn via relayer — no gas fees needed. GET returns typed data for signing, POST submits the signed meta-transaction.

### POST /api/warren/deploy
Warren on-chain permanent image storage (~$5 ETH).

### POST /api/chat/auth
ChadChat Ably auth token. Requires connected wallet with at least 1 burn.

### GET|POST /api/chat/messages
Chat message storage for ChadChat.

### GET|POST /api/chat/name
Display name management for ChadChat.

### POST /api/telegram
Telegram bot webhook handler.

### POST /api/telegram/alerts
Trigger burn/mint notification alerts.

### GET /api/frame
Farcaster frame navigation for gallery and leaderboard.

### GET /api/analytics
Per-endpoint and per-MCP-tool usage tracking.

## Full Agent Flow

1. **Check price:** `GET /api/price` — see current $MEGACHAD/ETH rate and burn cost
2. **Bridge if needed:** `GET /api/bridge` — get bridge instructions for moving ETH to MegaETH
3. **Get orchestrated plan:** `GET /api/agent/looksmaxx?wallet=0x...&ethAmount=0.5` — get pre-built calldata for every step
4. **Execute step 1:** Sign and send the swap transaction (if tokens needed)
5. **Execute step 2:** Sign and send burn transaction (112,500 to 0x...dEaD)
6. **Execute step 3:** Sign and send tren fund transfer (112,500 to tren fund)
7. **Execute step 4:** POST to `/api/x402/looksmaxx` with burn tx hashes, base64 image, and x402 payment
8. **Receive:** Looksmaxxed image URL, IPFS CID, and minted NFT token ID
9. **Monitor:** Subscribe to `GET /api/events` for real-time burn notifications

## MCP Server

Connect any MCP-compatible agent to `https://megachad.xyz/api/mcp`

Available tools (20):
- `get_megachad_stats` — Token supply, circulating supply, burn count
- `get_price` — Current $MEGACHAD price in ETH from Kumbaya DEX
- `get_swap_quote` — Swap quote for ETH → $MEGACHAD with calldata
- `get_wallet_info` — Wallet balances, NFT count, burn eligibility
- `get_portfolio` — Full MegaETH token portfolio (ETH, WETH, MEGACHAD, USDm)
- `get_gallery` — Browse looksmaxxed burns with IPFS images
- `get_chadboard` — Burner leaderboard with reputation scores and .mega names
- `get_identity` — Resolve wallet or .mega name into unified identity profile
- `get_nft_metadata` — ERC-721 metadata for looksmaxxed NFTs
- `get_looksmaxx_requirements` — Burn requirements and x402 payment info
- `get_looksmaxx_plan` — Full transaction plan: swap → burn → tren fund → submit
- `cross_chain_looksmaxx` — Cross-chain plan from 10+ chains to MegaETH
- `gasless_burn_info` — EIP-712 typed data for gasless meta-transaction burns
- `get_bridge_info` — Bridge options for moving assets to MegaETH
- `get_agent_info` — ERC-8004 agent registration and reputation data
- `register_referral_agent` — Register as referring agent (earn 11,250 $MEGACHAD per burn)
- `get_referral_stats` — Referral count, earnings, and reward info
- `register_early_access` — Register wallet for beta access
- `chat_with_megachad` — Natural language interface for all operations
- `get_megaeth_protocols` — Curated MegaETH protocol directory

## ERC-8004 Reputation

The Reputation Registry at `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` allows anyone to leave feedback on Agent #12408. Reputation scores are aggregated and displayed on the chadboard.

To give feedback:
```
giveFeedback(agentId=12408, value=<int128>, valueDecimals=0, tag1="starred", tag2="", endpoint="", feedbackURI="", feedbackHash=0x0)
```

## Burn Economics

- **Burn amount:** 225,000 $MEGACHAD per looksmaxx
- **Split:** 112,500 burned (to 0x...dEaD) + 112,500 to tren fund
- **Infra fee:** 1 USDm (covers Replicate AI generation + IPFS pinning)
- **Output:** AI-enhanced portrait + IPFS pin + NFT mint to burner address
- **Optional:** Warren on-chain permanent storage ($5 ETH)
- **Referral:** Agents earn 11,250 $MEGACHAD (5% of burn) per referred burn

## Tier System

Burn count determines tier: Normie (0) → Mewer (1+) → Bonesmasher (3+) → Chad (10+) → Gigachad (25+). The wallet with the most burns overall is crowned MOGGER. All .mega domain holders appear on the Chadboard.

## ChadChat

Burn-gated real-time messaging on the Chadboard. Only wallets with at least 1 burn (Mewer tier+) can send messages. Powered by Ably for instant delivery. Display names use .mega names or custom names.

## Telegram Alerts

Real-time burn and mint notifications via the MegaChad Telegram bot at https://t.me/megachads.

- `POST /api/telegram/alerts` — Trigger burn/mint notifications
- `GET /api/telegram/setup` — Bot configuration info

## MEGA Protocol Governance

The MEGA Protocol is MegaChad's governance layer on MegaETH.

- **$MEGAGOONER:** Governance/reward token (50M cap, 225-week quadratic emission)
- **Framemogger:** Burn $MEGACHAD → earn governance rights → mint $MEGAGOONER
- **MoggerStaking:** Stake $MEGACHAD → earn $MEGAGOONER over time
- **JESTERGOONER:** Stake LP tokens → earn $MEGAGOONER
- **Jestermogger:** Governance voting — top 3 burners propose, $MEGAGOONER holders vote

All contracts are UUPS upgradeable proxies on MegaETH (chain ID 4326).