{ "openapi": "3.1.0", "info": { "title": "MegaChad Agent API", "version": "1.0.0", "description": "Burn-to-create looksmaxxing engine on MegaETH. Burn $MEGACHAD tokens to generate AI-enhanced portraits, mint NFTs, and earn on-chain reputation. All endpoints run on MegaETH (chain ID 4326, RPC: https://mainnet.megaeth.com/rpc).", "contact": { "name": "MegaChad", "url": "https://megachad.xyz" } }, "servers": [ { "url": "https://megachad.xyz", "description": "Production" } ], "paths": { "/api/x402/quote": { "get": { "operationId": "getSwapQuote", "summary": "Get a swap quote for buying $MEGACHAD with ETH", "description": "Returns DEX swap instructions and quote from Kumbaya (Uniswap V3 fork). Without ethAmount, returns general swap info and contract addresses. With ethAmount, returns a live quote with pre-built transaction parameters.", "parameters": [ { "name": "ethAmount", "in": "query", "required": false, "description": "Amount of ETH to swap (e.g. \"0.1\" or wei string). Omit for general swap info.", "schema": { "type": "string", "example": "0.1" } } ], "responses": { "200": { "description": "Swap quote and transaction parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "ethIn": { "type": "string", "description": "ETH amount (human readable)" }, "ethInWei": { "type": "string", "description": "ETH amount in wei" }, "megachadOut": { "type": "number", "description": "Estimated $MEGACHAD output" }, "megachadOutWei": { "type": "string", "description": "$MEGACHAD output in wei" }, "hasEnoughForBurn": { "type": "boolean", "description": "Whether output covers the 225,000 burn requirement" }, "burnRequirement": { "type": "number", "description": "Required burn amount (225000)" }, "gasEstimate": { "type": "string" } } }, "swap": { "type": "object", "description": "Pre-built transaction parameters for exactInputSingle", "properties": { "router": { "type": "string", "description": "Kumbaya SwapRouter address" }, "functionName": { "type": "string", "enum": ["exactInputSingle"] }, "params": { "type": "object", "properties": { "tokenIn": { "type": "string" }, "tokenOut": { "type": "string" }, "fee": { "type": "integer" }, "recipient": { "type": "string", "description": "Replace with your wallet address" }, "amountIn": { "type": "string" }, "amountOutMinimum": { "type": "string", "description": "2% slippage applied" }, "sqrtPriceLimitX96": { "type": "string" } } }, "value": { "type": "string", "description": "Native ETH to send as msg.value" } } }, "chain": { "type": "object", "properties": { "name": { "type": "string" }, "chainId": { "type": "integer" }, "rpc": { "type": "string" } } } } } } } }, "400": { "description": "Invalid ethAmount parameter" }, "502": { "description": "DEX quote failed (liquidity issue)" } } } }, "/api/x402/looksmaxx": { "get": { "operationId": "getLooksmaxxRequirements", "summary": "Get payment and burn requirements for looksmaxxing", "description": "Returns HTTP 402 with x402 payment requirements (1 USDm via Meridian) and $MEGACHAD burn requirements (225,000 tokens split between burn address and tren fund).", "responses": { "402": { "description": "Payment required — contains x402 payment requirements and burn instructions", "headers": { "X-Payment-Required": { "schema": { "type": "string", "enum": ["true"] } }, "X-402-Version": { "schema": { "type": "string", "enum": ["1"] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "x402Version": { "type": "integer", "enum": [1] }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string", "enum": ["megaeth"] }, "asset": { "type": "string", "description": "USDm Forwarder address" }, "payTo": { "type": "string", "description": "Meridian Facilitator address" }, "maxAmountRequired": { "type": "string", "description": "1 USDm in wei (1000000000000000000)" }, "resource": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object" } } } }, "burnRequirements": { "type": "object", "properties": { "token": { "type": "string", "description": "$MEGACHAD contract address" }, "totalAmount": { "type": "string", "description": "Total burn in wei" }, "burnAddress": { "type": "string", "description": "0x...dEaD" }, "burnAmount": { "type": "string", "description": "Half to burn address (wei)" }, "trenFundWallet": { "type": "string" }, "trenFundAmount": { "type": "string", "description": "Half to tren fund (wei)" } } }, "instructions": { "type": "object", "properties": { "step1": { "type": "string" }, "step2": { "type": "string" }, "step3": { "type": "string" }, "step4": { "type": "string" } } } } } } } } } }, "post": { "operationId": "submitLooksmaxx", "summary": "Submit burn proof + x402 payment + image for looksmaxxing", "description": "Verifies on-chain burns, settles x402 USDm payment via Meridian, generates AI looksmaxxed portrait via Replicate, pins to IPFS, and mints NFT to the burner address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["burnTxHash", "devTxHash", "burnerAddress", "image", "paymentPayload"], "properties": { "burnTxHash": { "type": "string", "description": "Tx hash of 112,500 $MEGACHAD transfer to 0x...dEaD", "pattern": "^0x[a-fA-F0-9]{64}$" }, "devTxHash": { "type": "string", "description": "Tx hash of 112,500 $MEGACHAD transfer to tren fund wallet", "pattern": "^0x[a-fA-F0-9]{64}$" }, "burnerAddress": { "type": "string", "description": "Wallet address that sent both transfers", "pattern": "^0x[a-fA-F0-9]{40}$" }, "image": { "type": "string", "description": "Base64-encoded portrait image (JPEG/PNG/WebP, max 4MB)" }, "imageType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"], "default": "image/png" }, "paymentPayload": { "type": "object", "description": "x402 TransferWithAuthorization payment payload", "required": ["payload"], "properties": { "x402Version": { "type": "integer" }, "scheme": { "type": "string" }, "network": { "type": "string" }, "payload": { "type": "object", "required": ["signature"], "properties": { "signature": { "type": "string", "description": "EIP-712 signature for USDm TransferWithAuthorization" }, "authorization": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" }, "validAfter": { "type": "string" }, "validBefore": { "type": "string" }, "nonce": { "type": "string" } } } } } } } } } } } }, "responses": { "200": { "description": "Looksmaxx successful — image generated, pinned, and NFT minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] }, "source": { "type": "string", "enum": ["x402-agent"] }, "imageUrl": { "type": "string", "description": "Generated looksmaxxed image URL" }, "ipfsCid": { "type": "string", "description": "IPFS content identifier" }, "ipfsUrl": { "type": "string", "description": "IPFS gateway URL" }, "tokenId": { "type": "string", "nullable": true, "description": "Minted NFT token ID" }, "burnTxHash": { "type": "string" }, "devTxHash": { "type": "string" } } } } } }, "400": { "description": "Invalid input, missing fields, or burn verification failed" }, "402": { "description": "x402 payment settlement failed" }, "409": { "description": "Burn transaction already used (replay protection)" }, "502": { "description": "On-chain RPC or image generation failure" } } } }, "/api/stats": { "get": { "operationId": "getTokenStats", "summary": "Get $MEGACHAD token statistics", "description": "Returns total supply, circulating supply, tokens burned, and total burn count.", "responses": { "200": { "description": "Token statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalSupply": { "type": "number", "nullable": true }, "circulatingSupply": { "type": "number" }, "tokensBurned": { "type": "number", "nullable": true }, "totalBurns": { "type": "integer" } } } } } } } } }, "/api/gallery": { "get": { "operationId": "getGallery", "summary": "Get recent looksmaxxed burns", "description": "Returns a paginated list of recent burns with IPFS image URLs.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Gallery entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "burns": { "type": "array", "items": { "type": "object", "properties": { "txHash": { "type": "string" }, "burner": { "type": "string" }, "prompt": { "type": "string" }, "cid": { "type": "string" }, "ipfsUrl": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "burnAmount": { "type": "number" }, "tokenId": { "type": "string" } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } } }, "/api/chadboard": { "get": { "operationId": "getChadboard", "summary": "Get burner leaderboard with ERC-8004 reputation scores", "description": "Returns ranked list of top $MEGACHAD burners with burn counts, images, .mega names, profiles, and on-chain reputation scores from the ERC-8004 Reputation Registry.", "responses": { "200": { "description": "Leaderboard entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "megaName": { "type": "string", "nullable": true, "description": ".mega domain name" }, "megaProfile": { "type": "object", "nullable": true, "properties": { "avatar": { "type": "string" }, "description": { "type": "string" }, "twitter": { "type": "string" }, "url": { "type": "string" } } }, "totalBurns": { "type": "integer" }, "totalBurned": { "type": "number" }, "latestImage": { "type": "string" }, "latestTimestamp": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "type": "object", "properties": { "ipfsUrl": { "type": "string" }, "timestamp": { "type": "string" }, "txHash": { "type": "string" } } } }, "reputation": { "type": "object", "properties": { "score": { "type": "number", "nullable": true }, "count": { "type": "integer" } } } } } }, "agentId": { "type": "string", "nullable": true } } } } } } } } }, "/api/agent/info": { "get": { "operationId": "getAgentInfo", "summary": "Get MegaChad agent registration and on-chain identity", "description": "Returns ERC-8004 registration metadata, on-chain identity details, and contract addresses.", "responses": { "200": { "description": "Agent info", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "string" }, "version": { "type": "string" } } } }, "x402Support": { "type": "boolean" }, "active": { "type": "boolean" } } }, "onChain": { "type": "object", "properties": { "agentId": { "type": "string", "nullable": true }, "agentURI": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "wallet": { "type": "string", "nullable": true }, "reputationClients": { "type": "integer" } } }, "contracts": { "type": "object", "properties": { "identityRegistry": { "type": "string" }, "reputationRegistry": { "type": "string" } } }, "status": { "type": "string", "enum": ["registered", "pending_registration"] } } } } } } } } }, "/api/metadata/{tokenId}": { "get": { "operationId": "getNftMetadata", "summary": "Get ERC-721 metadata for a looksmaxxed NFT", "description": "Returns standard ERC-721 metadata including image URL (Warren on-chain or IPFS), attributes, and storage properties.", "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "NFT metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "image_url": { "type": "string" }, "external_url": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "trait_type": { "type": "string" }, "value": { "type": "string" } } } }, "properties": { "type": "object", "properties": { "ipfs_backup": { "type": "string" }, "warren_token_id": { "type": "integer", "nullable": true }, "on_chain": { "type": "boolean" } } } } } } } }, "404": { "description": "Token not found" } } } }, "/api/early/register": { "get": { "operationId": "getEarlyAccessInfo", "summary": "Get early access eligibility requirements", "description": "Returns eligibility criteria, registration instructions, and contract addresses for MegaChad testnet beta access.", "responses": { "200": { "description": "Early access info and registration instructions", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "eligibility": { "type": "object", "properties": { "instantAccess": { "type": "string" }, "referralPath": { "type": "string" } } }, "registration": { "type": "object" }, "contracts": { "type": "object" } } } } } } } }, "post": { "operationId": "registerEarlyAccess", "summary": "Register a wallet for MegaChad testnet beta access", "description": "Verifies on-chain eligibility ($MEGACHAD balance or looksmaxxed NFTs) and registers the wallet. Returns a referral code and access status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["wallet"], "properties": { "wallet": { "type": "string", "description": "Ethereum wallet address (0x...)", "pattern": "^0x[a-fA-F0-9]{40}$" }, "twitter": { "type": "string", "description": "X/Twitter handle (optional for agents)" }, "tweetUrl": { "type": "string", "description": "Tweet URL (optional for agents)" }, "referralCode": { "type": "string", "description": "Referral code from an existing registrant" } } } } } }, "responses": { "200": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "wallet": { "type": "string" }, "eligibility": { "type": "object", "properties": { "hasTokens": { "type": "boolean" }, "nftCount": { "type": "integer" }, "instantAccess": { "type": "boolean" }, "path": { "type": "string", "enum": ["instant", "referral"] } } }, "referralCode": { "type": "string" }, "referralLink": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid wallet address" }, "403": { "description": "Not eligible — wallet has no $MEGACHAD or NFTs" }, "502": { "description": "Registration backend unavailable" } } } }, "/api/price": { "get": { "operationId": "getTokenPrice", "summary": "Get current $MEGACHAD price from DEX", "description": "Returns the current $MEGACHAD price in ETH from the Kumbaya DEX pool, estimated burn cost, and pool info.", "responses": { "200": { "description": "Token price data", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object" }, "price": { "type": "object", "properties": { "megachadPerEth": { "type": "number" }, "ethPerMegachad": { "type": "number" }, "ethPerMillionMegachad": { "type": "string", "nullable": true } } }, "burnCost": { "type": "object", "properties": { "tokensRequired": { "type": "integer" }, "estimatedEth": { "type": "number" }, "infraFeeUsdm": { "type": "integer" } } }, "pool": { "type": "object" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "502": { "description": "DEX quote failed" } } } }, "/api/wallet": { "get": { "operationId": "getWalletInfo", "summary": "Check wallet balances and burn eligibility", "description": "Returns ETH balance, $MEGACHAD balance, NFT count, burn eligibility status, and early access qualification for a wallet address.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "responses": { "200": { "description": "Wallet info", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "balances": { "type": "object", "properties": { "eth": { "type": "string" }, "megachad": { "type": "number" }, "looksmaxxedNFTs": { "type": "integer" } } }, "burnEligibility": { "type": "object", "properties": { "canBurn": { "type": "boolean" }, "burnRequirement": { "type": "integer" }, "tokensNeeded": { "type": "number" }, "message": { "type": "string" } } }, "earlyAccess": { "type": "object", "properties": { "instantAccess": { "type": "boolean" }, "referralPath": { "type": "boolean" }, "eligible": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid address" } } } }, "/api/agent/looksmaxx": { "get": { "operationId": "getLooksmaxxPlan", "summary": "Get orchestrated looksmaxx flow with pre-built calldata", "description": "Returns a complete, ordered set of transaction instructions for the full looksmaxx flow (swap → burn → tren fund → submit). Each step includes pre-built calldata ready to sign and send. This is the recommended endpoint for agents.", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }, { "name": "ethAmount", "in": "query", "required": false, "description": "ETH to swap. Omit if wallet already has enough $MEGACHAD.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Orchestrated looksmaxx plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string" }, "currentState": { "type": "object", "properties": { "ethBalance": { "type": "string" }, "megachadBalance": { "type": "number" }, "hasEnoughTokens": { "type": "boolean" }, "tokensNeeded": { "type": "number" } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "integer" }, "action": { "type": "string" }, "description": { "type": "string" }, "skip": { "type": "boolean" }, "skipReason": { "type": "string" }, "transaction": { "type": "object" }, "postRequest": { "type": "object" } } } }, "expectedResult": { "type": "object" } } } } } }, "400": { "description": "Invalid wallet" } } } }, "/api/bridge": { "get": { "operationId": "getBridgeInfo", "summary": "Get cross-chain bridge information for MegaETH", "description": "Returns bridge options for moving assets from Ethereum, Arbitrum, Base, and other chains to MegaETH.", "responses": { "200": { "description": "Bridge info", "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "object" }, "bridges": { "type": "array", "items": { "type": "object" } }, "tokens": { "type": "object" }, "flow": { "type": "object" } } } } } } } } }, "/api/gasless/burn": { "get": { "operationId": "getGaslessBurnInfo", "summary": "Get EIP-712 typed data for a gasless burn", "description": "Returns the EIP-712 signature payload, approval status, and nonce for a gasless relay burn. Users approve the relayer contract once, then sign typed data to burn without paying gas.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet address (0x...)" } ], "responses": { "200": { "description": "Gasless burn readiness and EIP-712 typed data", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean", "description": "True if wallet has approval and sufficient balance" }, "approval": { "type": "object", "description": "Approval status and approve transaction if needed" }, "balance": { "type": "object", "description": "Token balance vs required amount" }, "signTypedData": { "type": "object", "description": "EIP-712 domain, types, and message to sign" }, "relayerContract": { "type": "string", "description": "Relayer contract address" } } } } } } } }, "post": { "operationId": "submitGaslessBurn", "summary": "Submit a signed gasless burn for relay", "description": "Submit an EIP-712 signed burn request. The backend relays the transaction on-chain and pays gas on behalf of the burner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["burner", "deadline", "signature"], "properties": { "burner": { "type": "string", "description": "Wallet address that signed the burn request" }, "deadline": { "type": "integer", "description": "Unix timestamp after which the signature expires" }, "signature": { "type": "string", "description": "EIP-712 signature (65-byte hex, 0x-prefixed)" } } } } } }, "responses": { "200": { "description": "Burn relayed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "txHash": { "type": "string" }, "blockNumber": { "type": "integer" }, "gasUsed": { "type": "string" }, "explorerUrl": { "type": "string" } } } } } }, "400": { "description": "Invalid signature, expired deadline, or insufficient balance/approval" }, "500": { "description": "Relay transaction failed" } } } }, "/api/agent/register": { "get": { "operationId": "checkAgentRegistration", "summary": "Check if a wallet is registered as a referring agent", "description": "Returns registration status, referral code, and stats for a wallet. Agents register on-chain to earn 11,250 $MEGACHAD (5% of burn) for every burn they refer.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Agent wallet address" } ], "responses": { "200": { "description": "Registration status and stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "registered": { "type": "boolean" }, "referralCode": { "type": "string", "nullable": true }, "stats": { "type": "object", "properties": { "referralCount": { "type": "integer" }, "totalEarnings": { "type": "string" }, "totalEarningsFormatted": { "type": "string" } } }, "referralContract": { "type": "string" } } } } } }, "400": { "description": "Invalid address" } } }, "post": { "operationId": "registerReferralAgent", "summary": "Register as a MegaChad referring agent", "description": "Returns transaction calldata to register on-chain as a referring agent. After registration, earn 11,250 $MEGACHAD (5% of total burn) for every burn referred via your referral code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["wallet"], "properties": { "wallet": { "type": "string", "description": "Agent wallet address (0x...)", "pattern": "^0x[a-fA-F0-9]{40}$" }, "mcpEndpoint": { "type": "string", "description": "Agent MCP server URL (optional)" }, "description": { "type": "string", "description": "Agent description (optional)" } } } } } }, "responses": { "200": { "description": "Registration transaction calldata and referral info", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "referralCode": { "type": "string" }, "registration": { "type": "object", "properties": { "description": { "type": "string" }, "transaction": { "type": "object", "properties": { "to": { "type": "string" }, "data": { "type": "string" }, "chainId": { "type": "integer" }, "value": { "type": "string" } } } } }, "afterRegistration": { "type": "object", "properties": { "referralCode": { "type": "string" }, "howItWorks": { "type": "array", "items": { "type": "string" } }, "earnings": { "type": "object", "properties": { "perBurn": { "type": "string" }, "percentage": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid wallet address" } } } }, "/api/agent/referrals": { "get": { "operationId": "getReferralStats", "summary": "Get referral stats and burn-with-referral calldata", "description": "Returns referral count, earnings, reward-per-burn info, and pre-built calldata for executing a referred burn. Pass ?referralCode= to resolve a code to an agent.", "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Agent wallet address" }, { "name": "referralCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Referral code to resolve" } ], "responses": { "200": { "description": "Referral stats and calldata", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "registered": { "type": "boolean" }, "referralCode": { "type": "string", "nullable": true }, "stats": { "type": "object", "properties": { "referralCount": { "type": "integer" }, "totalEarnings": { "type": "string" }, "totalEarningsFormatted": { "type": "string" } } }, "rewardInfo": { "type": "object", "properties": { "currentBps": { "type": "integer" }, "percentageOfTrenFund": { "type": "string" }, "rewardPerBurn": { "type": "string" }, "rewardPerBurnRaw": { "type": "string" } } }, "referralContract": { "type": "string" }, "burnWithReferralCalldata": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Missing address or referralCode" } } } }, "/api/agent/chat": { "post": { "operationId": "chatWithMegachad", "summary": "Natural language interface for AI agents", "description": "Send a plain English message and get back structured, actionable responses with data and suggested next actions. Supports 17 intents: price, stats, wallet, looksmaxx, swap, gallery, leaderboard, bridge, gasless, referral, about, burn, compare, multi_burn, schedule, cross_chain_looksmaxx, register_agent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Natural language query", "example": "What is the current MEGACHAD price?" }, "wallet": { "type": "string", "description": "Wallet address for context (0x...)", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } }, "responses": { "200": { "description": "Structured response with intent, answer, data, and actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "type": "string", "description": "Detected intent (price, stats, wallet, etc.)" }, "answer": { "type": "string", "description": "Human-readable answer" }, "data": { "type": "object", "description": "Raw data from the underlying API" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "body": { "type": "object" } } }, "description": "Suggested follow-up actions" } } } } } }, "400": { "description": "Missing or empty message" } } }, "get": { "operationId": "getChatInfo", "summary": "Get chat endpoint documentation", "description": "Returns supported intents, example messages, and endpoint documentation.", "responses": { "200": { "description": "Endpoint documentation", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string" }, "method": { "type": "string" }, "description": { "type": "string" }, "supportedIntents": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/events": { "get": { "operationId": "getEventStream", "summary": "Subscribe to real-time protocol events via SSE", "description": "Server-Sent Events stream emitting stats updates, new burns, and heartbeats. Auto-closes after 55s — reconnect to continue.", "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE stream with events: connected, stats, burn, heartbeat, close" } } } } } } }, "/.well-known/megachad-protocol.json": { "get": { "operationId": "getProtocolRegistry", "summary": "Get the MEGA Protocol contract registry", "description": "Canonical machine-readable registry: every deployed contract (tokens, AMM, staking, governance, emissions, safety) with address, proxy/impl, key ABI functions, agent endpoints, and known gotchas (e.g. MegaChadLP tokenA/tokenB non-standard layout). Agents should fetch this once at startup and cache.", "responses": { "200": { "description": "Protocol registry JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/defi/staking": { "get": { "operationId": "getStakingPosition", "summary": "Read combined MoggerStaking + JESTERGOONER position + APRs", "description": "Without `address`: global stats only (totalStaked, rewardRate, periodFinish, APR per venue). With `address`: also includes per-wallet position (staked, earned, allowance, NFT boost, eligibility).", "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Staking state" } } } }, "/api/defi/staking/tx": { "get": { "operationId": "buildStakingTx", "summary": "Build approve+stake / unstake / claim transaction", "description": "Returns `executionPlan: [{ to, value, data, functionName, args }]`. For stake, the plan starts with approve if allowance is insufficient (or always, if `address` is omitted).", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": ["stake", "unstake", "claim"] } }, { "name": "venue", "in": "query", "required": true, "schema": { "type": "string", "enum": ["mogger", "jester"] } }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required for stake/unstake; human units (e.g. \"1000\")." }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ordered action plan" } } } }, "/api/defi/amm/quote": { "get": { "operationId": "getAmmQuote", "summary": "Quote a swap on the MEGACHAD/MEGAGOONER pair", "description": "Constant-product math (0.3% fee). Without `from`+`amount`, returns reserves + spot price. With both, returns expected output, price impact bps, and a link to the swap-tx builder. NOTE: MegaChadLP uses tokenA/tokenB rather than the V2 standard token0/token1 — generic V2 routers will not find this pool.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "enum": ["MC", "MG"] } }, { "name": "amount", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pool state + optional quote" } } } }, "/api/defi/amm/swap-tx": { "get": { "operationId": "buildAmmSwapTx", "summary": "Build a MEGACHAD↔MEGAGOONER swap transaction", "description": "Returns a two-step plan: ERC20.transfer(pair, amountIn) → pair.swap(amountAIn, amountBIn, to). MegaChadLP has no on-chain minOut — verify off-chain.", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "enum": ["MC", "MG"] } }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "recipient", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "default": 200 } } ], "responses": { "200": { "description": "Swap execution plan + minOut" } } } }, "/api/defi/amm/add-liquidity-tx": { "get": { "operationId": "buildAddLiquidityTx", "summary": "Build approve+approve+addLiquidity on the MC/MG pair", "parameters": [ { "name": "amountMC", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "amountMG", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "recipient", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liquidity provisioning plan" } } } }, "/api/defi/governance/proposals": { "get": { "operationId": "listGovernanceProposals", "summary": "List Jestermogger proposals", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Proposal list with state + tally" } } } }, "/api/defi/governance/proposals/{id}": { "get": { "operationId": "getGovernanceProposal", "summary": "Get a single proposal in detail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "voter", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full proposal state + receipt" } } } }, "/api/defi/governance/vote-tx": { "get": { "operationId": "buildVoteTx", "summary": "Build castVote transaction", "parameters": [ { "name": "proposalId", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "support", "in": "query", "required": true, "schema": { "type": "string", "enum": ["for", "against", "abstain"] } } ], "responses": { "200": { "description": "castVote plan" } } } }, "/api/defi/governance/queue-tx": { "get": { "operationId": "buildQueueTx", "summary": "Build queue transaction for a Succeeded proposal", "parameters": [ { "name": "proposalId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "queue plan" } } } }, "/api/defi/governance/execute-tx": { "get": { "operationId": "buildExecuteTx", "summary": "Build execute transaction for a Queued proposal", "parameters": [ { "name": "proposalId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "execute plan" } } } }, "/api/defi/emission": { "get": { "operationId": "getEmissionSchedule", "summary": "Get MEGAGOONER emission schedule + current state", "description": "225-week quadratic decay schedule, current week, on-chain weekly emission, and the EmissionController split (mogger / jester / treasury) in bps and pct.", "responses": { "200": { "description": "Emission schedule + split" } } } }, "/api/agent": { "get": { "operationId": "getAgentIndex", "summary": "Master agent index — single front door for AI agents", "description": "Returns a structured directory of every agent-facing surface MegaChad exposes: A2A/MCP/OpenAI-plugin manifests, OpenAPI spec, ERC-8004 registration, agents.txt, MCP server config, contract registry, all read + tx-builder endpoints grouped by domain, supported intents, and quickstart examples. Fetch this once at startup and cache (5 min).", "responses": { "200": { "description": "Agent index directory" } } } }, "/api/defi/nft": { "get": { "operationId": "getNftInventory", "summary": "Get MEGACHADNFT count + boost tier + staking eligibility", "description": "Returns NFT balance, boost tier (1.000x/1.075x/1.150x at 1/10/25 NFTs), eligibility for staking rewards (requires 1+ NFT), next tier threshold, and recent looksmaxxed items for the wallet from the gallery cache.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "responses": { "200": { "description": "NFT inventory + boost + eligibility" }, "400": { "description": "Invalid address" } } } }, "/api/defi/safety": { "get": { "operationId": "getProtocolSafety", "summary": "Get CircuitBreaker pause state + NFTVetoCouncil composition", "description": "Snapshot of safety surfaces agents should check before issuing writes. Includes CircuitBreaker (paused, pausedAt, autoUnpauseTime, guardians, pause/unpause votes) and NFTVetoCouncil (council size, veto threshold, veto window, current members, seats filled).", "responses": { "200": { "description": "Safety snapshot" } } } }, "/api/defi/activity": { "get": { "operationId": "getActivityFeed", "summary": "Unified recent on-chain activity feed across the MEGA Protocol stack", "description": "Parallel getLogs across Token transfers (burns to dEaD), staking (stake/unstake/claim) on both venues, Framemogger MegachadSent events, and Jestermogger governance (ProposalCreated/VoteCast/Queued/Executed). Normalized to { kind, blockNumber, txHash, summary, actor, amount, ... } sorted newest-first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "blocks", "in": "query", "required": false, "schema": { "type": "integer", "default": 2000, "minimum": 100, "maximum": 50000 }, "description": "Block lookback window (default ≈ 8 min on MegaETH)" } ], "responses": { "200": { "description": "Unified activity feed" } } } }, "/api/defi/governance/propose-tx": { "get": { "operationId": "getProposeEligibility", "summary": "Check Framemogger top-3 burner eligibility to propose", "description": "Returns canPropose verdict + currentWeek + getWeekTop3 burners for the proposer (or current connected agent). Only the week's top 3 burners can call Jestermogger.propose().", "parameters": [ { "name": "proposer", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } ], "responses": { "200": { "description": "Eligibility report" } } }, "post": { "operationId": "buildProposeTx", "summary": "Build a Jestermogger.propose() transaction", "description": "Validates target/value/calldata arrays and encodes propose(targets[], values[], calldatas[], description). Lifecycle: 1d delay → 3d voting → 2d timelock → 7d grace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["targets", "values", "calldatas", "description"], "properties": { "proposer": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "targets": { "type": "array", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }, "values": { "type": "array", "items": { "type": "string", "description": "wei as decimal string" } }, "calldatas": { "type": "array", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" } }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "propose() execution plan + eligibility echo" }, "400": { "description": "Validation failure (array length / address / wei / calldata)" } } } }, "/api/defi/governance/veto-tx": { "get": { "operationId": "buildVetoTx", "summary": "Build NFTVetoCouncil veto transaction(s)", "description": "If no veto window is currently open, prepends startVetoVote(id) so a council member can both kick off the window and cast in one bundle. Always appends castVetoVote(id, support). support: yes/veto = true, no/against = false. 20 seats, 11-veto threshold, 2-day window.", "parameters": [ { "name": "proposalId", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "support", "in": "query", "required": true, "schema": { "type": "string", "enum": ["yes", "no", "for", "against", "veto"] } }, { "name": "voter", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Voter address to check council membership + prior vote" } ], "responses": { "200": { "description": "Veto execution plan" } } } } }, "components": { "schemas": { "ChainInfo": { "type": "object", "properties": { "name": { "type": "string", "example": "MegaETH" }, "chainId": { "type": "integer", "example": 4326 }, "rpc": { "type": "string", "example": "https://mainnet.megaeth.com/rpc" } } }, "ContractAddresses": { "type": "object", "description": "Key contract addresses on MegaETH (chain ID 4326)", "properties": { "megachadToken": { "type": "string", "example": "0x374A17bd16B5cD76aaeFC9EAF76aE07e9aF3d888" }, "nftContract": { "type": "string", "example": "0x1f1eFd3476b95091B9332b2d36a24bDE12CC6296" }, "burnAddress": { "type": "string", "example": "0x000000000000000000000000000000000000dEaD" }, "trenFundWallet": { "type": "string", "example": "0x85bf9272DEA7dff1781F71473187b96c6f2f370C" }, "kumbayaSwapRouter": { "type": "string", "example": "0xE5BbEF8De2DB447a7432A47EBa58924d94eE470e" }, "kumbayaQuoter": { "type": "string", "example": "0x1F1a8dC7E138C34b503Ca080962aC10B75384a27" }, "weth": { "type": "string", "example": "0x4200000000000000000000000000000000000006" }, "usdmToken": { "type": "string", "example": "0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7" }, "identityRegistry": { "type": "string", "example": "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" }, "reputationRegistry": { "type": "string", "example": "0x8004BAa17C55a88189AE136b182e5fdA19dE9b63" }, "megagoonerToken": { "type": "string", "example": "0x11d819Dbd6e9aF0b13A54e88EA411155764e3F46" }, "megaChadLpMcMg": { "type": "string", "example": "0x437a433534FF6e7712D7e0A03Fa6CE577EeA1fef" }, "moggerStaking": { "type": "string", "example": "0xfd820E6189Eb3396dA71cB072643A0E1e1239853" }, "jesterGoonerV4": { "type": "string", "example": "0x2695965Dd283e2425fab5C4c1E0955656802569c" }, "emissionController": { "type": "string", "example": "0x9CBB09555395643abc016b586D7d890E6911a013" }, "framemogger": { "type": "string", "example": "0xce320179Fb66E088635f789881A939321682E0c5" }, "jestermogger": { "type": "string", "example": "0x75C38E514Ba9FEeb6EEEeF4cdEb88074Ade0582b" }, "nftVetoCouncil": { "type": "string", "example": "0xbE985E5159cDFE8d33b4E61644495B38cCb46468" }, "circuitBreaker": { "type": "string", "example": "0x8C6c634D0B698de2E98713E5a02f7905b117beAE" } } } } } }