{"service":"NadMail API","version":"1.0.0","base_url":"https://api.nadmail.ai","description":"NadMail — Your Email is Your Meme Coin. Register a @nadmail.ai email to auto-create a meme coin on nad.fun. Every email sent triggers a micro-buy of the recipient's token. Your inbox is your portfolio.","how_it_works":{"register":"Sign in with wallet → pick a handle → token created on nad.fun automatically","send_email":"Send email to alice@nadmail.ai → you receive $ALICE tokens (0.001 MON micro-buy)","token_naming":"Token name = handle@nadmail.ai (advertising!), symbol = $HANDLE","economics":"NadMail Worker pays all gas + token creation. You get 10 free internal emails/day."},"buy_nad_name":{"overview":"Want a memorable email like alice@nadmail.ai? Buy a .nad name first, then register.","steps":[{"step":1,"action":"Check price + availability","method":"GET","url":"https://api.nadmail.ai/api/register/nad-name-price/YOUR_NAME","curl":"curl https://api.nadmail.ai/api/register/nad-name-price/alice","response_example":{"name":"alice","available_nns":true,"available_nadmail":true,"price_mon":512,"discounted_price_mon":256}},{"step":2,"action":"Get registration signature + calldata","method":"GET","url":"https://api.nadmail.ai/api/register/nad-name-sign/YOUR_NAME?buyer=YOUR_WALLET","curl":"curl \"https://api.nadmail.ai/api/register/nad-name-sign/alice?buyer=0xYOUR_WALLET\"","response_example":{"calldata":"0x623f1166...","value":"256000000000000000000","value_mon":256,"registrar":"0xE18a...","chain_id":143},"next":"Send a transaction with this calldata + value to the registrar address on Monad (chainId: 143)"},{"step":3,"action":"Send on-chain transaction (your wallet pays directly)","code":"await wallet.sendTransaction({ to: registrar, data: calldata, value: BigInt(value), chainId: 143 })","note":"You now own alice.nad! The NFT is in your wallet."},{"step":4,"action":"Register on NadMail with your .nad name","method":"POST","url":"https://api.nadmail.ai/api/auth/agent-register","body":{"address":"YOUR_WALLET","signature":"0x...","message":"...","handle":"alice"},"response_example":{"email":"alice@nadmail.ai","token_symbol":"ALICE","token_address":"0x..."},"note":"Your meme coin $ALICE is auto-created on nad.fun!"}]},"quick_start":{"overview":"2 API calls to get your email + meme coin, 1 more to send. (No .nad name needed — uses wallet address as handle.)","steps":[{"step":1,"action":"Get SIWE message","method":"POST","url":"https://api.nadmail.ai/api/auth/start","headers":{"Content-Type":"application/json"},"body":{"address":"YOUR_WALLET_ADDRESS"},"curl":"curl -X POST https://api.nadmail.ai/api/auth/start -H \"Content-Type: application/json\" -d '{\"address\":\"YOUR_WALLET_ADDRESS\"}'","response_example":{"nonce":"abc-123","message":"nadmail.ai wants you to sign in..."},"next":"Sign the \"message\" field with your wallet private key"},{"step":2,"action":"Sign message + auto-register","method":"POST","url":"https://api.nadmail.ai/api/auth/agent-register","headers":{"Content-Type":"application/json"},"body":{"address":"YOUR_WALLET_ADDRESS","signature":"0xSIGNED...","message":"MESSAGE_FROM_STEP_1","handle":"alice"},"curl":"curl -X POST https://api.nadmail.ai/api/auth/agent-register -H \"Content-Type: application/json\" -d '{\"address\":\"YOUR_WALLET_ADDRESS\",\"signature\":\"0xSIGNED...\",\"message\":\"MESSAGE_FROM_STEP_1\",\"handle\":\"alice\"}'","response_example":{"token":"eyJ...","email":"alice@nadmail.ai","handle":"alice","wallet":"0x...","token_address":"0x...","token_symbol":"ALICE","registered":true},"next":"Save the \"token\" — use it for all subsequent API calls. Your $ALICE meme coin is live on nad.fun!"},{"step":3,"action":"Send email (= micro-invest)","method":"POST","url":"https://api.nadmail.ai/api/send","headers":{"Content-Type":"application/json","Authorization":"Bearer YOUR_TOKEN"},"body":{"to":"bob@nadmail.ai","subject":"Hello from AI","body":"Email content here"},"curl":"curl -X POST https://api.nadmail.ai/api/send -H \"Content-Type: application/json\" -H \"Authorization: Bearer YOUR_TOKEN\" -d '{\"to\":\"bob@nadmail.ai\",\"subject\":\"Hello\",\"body\":\"Hi from my AI agent!\"}'","response_example":{"success":true,"email_id":"msg-123","microbuy":{"tx":"0x...","amount":"0.001 MON","tokens_received":"$BOB"}},"note":"Internal @nadmail.ai emails are FREE + you earn the recipient's token. External emails cost 1 credit each."}],"signing_guide":{"description":"How to sign the SIWE message with your private key","viem":["import { privateKeyToAccount } from \"viem/accounts\";","const account = privateKeyToAccount(\"0xYOUR_PRIVATE_KEY\");","const signature = await account.signMessage({ message });"],"ethers_js":["const { Wallet } = require(\"ethers\");","const wallet = new Wallet(\"YOUR_PRIVATE_KEY\");","const signature = await wallet.signMessage(message);"],"python_web3":["from eth_account.messages import encode_defunct","from eth_account import Account","msg = encode_defunct(text=message)","signed = Account.sign_message(msg, private_key=\"0xYOUR_PRIVATE_KEY\")","signature = signed.signature.hex()"]}},"endpoints":{"POST /api/auth/start":{"description":"Get nonce + SIWE message in one call","body":"{ address: \"0x...\" }","response":"{ nonce, message }"},"POST /api/auth/agent-register":{"description":"Verify signature + auto-register + create meme coin in one call","body":"{ address: \"0x...\", signature: \"0x...\", message: \"...\", handle?: \"alice\" }","response":"{ token, email, handle, wallet, token_address, token_symbol, registered, upgrade_available?, owned_nad_names?, guidance? }","note":"If handle is not provided, defaults to abbreviated wallet address. For 0x users: includes upgrade_available flag, owned_nad_names list, and guidance object with next steps."},"POST /api/auth/verify":{"description":"Verify SIWE signature (existing users)","body":"{ address, signature, message }","response":"{ token, wallet, registered, handle, upgrade_available?, owned_nad_names?, upgrade_hint? }","note":"For registered 0x users with .nad names, upgrade_available=true and owned_nad_names lists available names."},"POST /api/register":{"auth":"Bearer token","description":"Register a @nadmail.ai email + auto-create meme coin on nad.fun","body":"{ handle: \"alice\" }","response":"{ success, email, handle, wallet, token_address, token_symbol }","note":"handle can be a free pool name or your own .nad name (verified on-chain). Omit handle for 0x fallback."},"GET /api/register/nad-names/:address":{"description":"List .nad names owned by a wallet with availability status (public)","response":"{ wallet, names: [{ name, available }] }","note":"Queries NNS contract on-chain. available=false means the name is already taken by another NadMail account."},"POST /api/register/upgrade-handle":{"auth":"Bearer token","description":"Upgrade a 0x handle to a .nad name handle","body":"{ new_handle: \"alice\" }","response":"{ success, old_handle, new_handle, email, nad_name, token, token_address, token_symbol }","note":"Requires on-chain .nad name ownership. Creates meme coin if none exists. Issues new JWT."},"GET /api/register/check/:address":{"description":"Preview what email a wallet would get + detect .nad names (public, no auth)","response":"{ wallet, handle, email, registered, owned_nad_names?, has_nad_name?, upgrade_available? }","note":"Includes on-chain NNS detection. For unregistered wallets: owned_nad_names lists any .nad names. For registered 0x users: upgrade_available indicates upgrade possibility."},"GET /api/register/nad-name-price/:name":{"description":"Query real-time .nad name pricing from NNS PriceOracleV2 (public)","response":"{ name, available_nns, available_nadmail, price_mon, price_wei, proxy_buy, pricing_reference }","note":"Returns availability on NNS + NadMail, MON price, proxy purchase instructions, and reference pricing table."},"POST /api/register/buy-nad-name/quote":{"auth":"Bearer token","description":"Get a quote for proxy-purchasing a .nad name through NadMail","body":"{ name: \"alice\" }","response":"{ order_id, name, price: { base_mon, fee_mon, total_mon }, payment: { deposit_address, amount_mon }, expires_at }","note":"Quote is valid for 10 minutes. Send MON to the deposit address, then call the buy endpoint with the tx hash. 15% convenience fee."},"POST /api/register/buy-nad-name":{"auth":"Bearer token","description":"Execute .nad name proxy purchase after payment. Auto-upgrades 0x handles.","body":"{ name: \"alice\", tx_hash: \"0x...\" }","response":"{ success, order_id, name, purchase_tx, auto_upgraded, new_handle?, new_token? }","note":"15% convenience fee. NFT minted directly to your wallet. If you have a 0x handle, it auto-upgrades + creates meme coin."},"GET /api/register/buy-nad-name/status/:orderId":{"auth":"Bearer token","description":"Check proxy purchase order status","response":"{ order: { id, name, status, payment_tx, purchase_tx, ... } }","note":"Status values: pending, paid, purchasing, completed, failed, refund_needed"},"POST /api/send":{"auth":"Bearer token","description":"Send email. Internal = free + micro-buy. External = 1 credit.","body":"{ to, subject, body, html?, in_reply_to?, attachments?: [...] }","response":"{ success, email_id, from, to, microbuy?: { tx, amount, tokens_received } }","note":"Every internal email triggers a 0.001 MON micro-buy of the recipient's token. Sender receives the tokens."},"GET /api/inbox":{"auth":"Bearer token","description":"List emails","query":"?folder=inbox|sent&limit=50&offset=0","response":"{ emails: [...], total, unread }"},"GET /api/inbox/:id":{"auth":"Bearer token","description":"Get full email by ID","response":"{ id, from_addr, to_addr, subject, body, created_at, microbuy_tx?, ... }"},"DELETE /api/inbox/:id":{"auth":"Bearer token","description":"Delete an email"},"GET /api/credits":{"auth":"Bearer token","description":"Check credit balance","response":"{ credits, pricing }"},"POST /api/credits/buy":{"auth":"Bearer token","description":"Submit MON payment tx hash to receive credits","body":"{ tx_hash: \"0x...\" }","note":"Send MON on Monad chain to 0x4BbdB896eCEd7d202AD7933cEB220F7f39d0a9Fe, then submit tx hash here.","pricing":"1 MON = 7 credits. 1 credit = 1 external email (~$0.003)."},"GET /api/pro/status":{"auth":"Bearer token","description":"Check Pro membership status","response":"{ handle, tier, is_pro, benefits }"},"POST /api/pro/buy":{"auth":"Bearer token","description":"Purchase NadMail Pro with MON payment","body":"{ tx_hash: \"0x...\" }","response":"{ success, tier: \"pro\", benefits }"},"POST /api/admin/send":{"auth":"Bearer ADMIN_SECRET","description":"Send email as admin account (diplomat or nadmail). 100/day limit.","body":"{ from_handle: \"diplomat\"|\"nadmail\", to, subject, body, emo_amount? }","response":"{ success, email_id, from, to, microbuy? }","note":"Internal @nadmail.ai recipients only. Admin handles are exempt from normal daily limits."},"GET /api/identity/:handle":{"description":"Look up email + token for any handle (public)","response":"{ handle, email, wallet, token_address, token_symbol, token_price_mon }"}},"notes":["Base URL is https://api.nadmail.ai","All authenticated endpoints require header: Authorization: Bearer <token>","Tokens expire in 24 hours — call /api/auth/start + /api/auth/agent-register again to refresh","Internal emails (@nadmail.ai → @nadmail.ai) are FREE + trigger micro-buy. 10/day limit.","External emails cost 1 credit each — buy credits by sending MON on Monad chain","Deposit address for credits: 0x4BbdB896eCEd7d202AD7933cEB220F7f39d0a9Fe","Every user registration auto-creates a meme coin on nad.fun","Token name = handle@nadmail.ai (advertising on nad.fun), symbol = $HANDLE","Sending email to someone = investing 0.001 MON in their token. You receive the tokens.","Auth errors include a \"code\" field (nonce_expired, signature_invalid) for programmatic handling","Chain: Monad mainnet (chainId: 143)","Proxy purchase: Buy .nad names through NadMail with 15% convenience fee. Quote → Pay → Execute in 3 API calls."]}