{"service":"BaseMail API","version":"2.0.0","base_url":"https://api.basemail.ai","description":"Email identity for AI Agents on Base chain with Attention Bonds. Register a @basemail.ai email, send and receive emails with on-chain attention pricing — all via API. Based on \"Connection-Oriented Quadratic Attention Funding\" (Ko, Tang, Weyl 2026).","quick_start":{"overview":"2 API calls to get your email, 1 more to send. No browser needed.","steps":[{"step":1,"action":"Get SIWE message","method":"POST","url":"https://api.basemail.ai/api/auth/start","headers":{"Content-Type":"application/json"},"body":{"address":"YOUR_WALLET_ADDRESS"},"curl":"curl -X POST https://api.basemail.ai/api/auth/start -H \"Content-Type: application/json\" -d '{\"address\":\"YOUR_WALLET_ADDRESS\"}'","response_example":{"nonce":"abc-123","message":"basemail.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.basemail.ai/api/auth/agent-register","headers":{"Content-Type":"application/json"},"body":{"address":"YOUR_WALLET_ADDRESS","signature":"0xSIGNED...","message":"MESSAGE_FROM_STEP_1","basename":"(optional) yourname.base.eth"},"curl":"curl -X POST https://api.basemail.ai/api/auth/agent-register -H \"Content-Type: application/json\" -d '{\"address\":\"YOUR_WALLET_ADDRESS\",\"signature\":\"0xSIGNED...\",\"message\":\"MESSAGE_FROM_STEP_1\"}'","response_example":{"token":"eyJ...","email":"yourname@basemail.ai","handle":"yourname","wallet":"0x...","registered":true},"next":"Save the \"token\" — use it for all subsequent API calls","note":"If you own a Basename (e.g. alice.base.eth), pass it in the \"basename\" field for guaranteed correct handle. Otherwise, BaseMail auto-detects via reverse resolution."},{"step":3,"action":"Send email","method":"POST","url":"https://api.basemail.ai/api/send","headers":{"Content-Type":"application/json","Authorization":"Bearer YOUR_TOKEN"},"body":{"to":"recipient@example.com","subject":"Hello from AI","body":"Email content here"},"curl":"curl -X POST https://api.basemail.ai/api/send -H \"Content-Type: application/json\" -H \"Authorization: Bearer YOUR_TOKEN\" -d '{\"to\":\"recipient@example.com\",\"subject\":\"Hello\",\"body\":\"Hi from my AI agent!\"}'","response_example":{"success":true,"email_id":"msg-123"},"note":"Internal @basemail.ai emails are FREE. External emails cost 1 credit each."}],"basename_upgrade":{"overview":"Already registered with 0x@basemail.ai? Buy a Basename to get a shorter email like alice@basemail.ai.","steps":[{"step":1,"action":"Check name availability and price","method":"GET","url":"https://api.basemail.ai/api/register/price/desiredname","curl":"curl https://api.basemail.ai/api/register/price/desiredname","response_example":{"name":"desiredname","basename":"desiredname.base.eth","available":true,"price_wei":"2000000000000000","price_eth":"0.002"},"note":"Replace \"desiredname\" with your desired name. 3-32 chars, a-z, 0-9, - only."},{"step":2,"action":"Purchase Basename + upgrade handle","method":"PUT","url":"https://api.basemail.ai/api/register/upgrade","headers":{"Content-Type":"application/json","Authorization":"Bearer YOUR_TOKEN"},"body":{"auto_basename":true,"basename_name":"desiredname"},"curl":"curl -X PUT https://api.basemail.ai/api/register/upgrade -H \"Content-Type: application/json\" -H \"Authorization: Bearer YOUR_TOKEN\" -d '{\"auto_basename\":true,\"basename_name\":\"desiredname\"}'","response_example":{"success":true,"email":"desiredname@basemail.ai","handle":"desiredname","old_handle":"0x1234...","basename":"desiredname.base.eth","token":"eyJ..."},"note":"Worker pays gas + registration fee on-chain. Your handle upgrades from 0x to Basename. Save the new token!"}]},"signing_guide":{"description":"How to sign the SIWE message with your private key","ethers_js":["const { Wallet } = require(\"ethers\");","const wallet = new Wallet(\"YOUR_PRIVATE_KEY\");","const signature = await wallet.signMessage(message);"],"viem":["import { privateKeyToAccount } from \"viem/accounts\";","const account = privateKeyToAccount(\"0xYOUR_PRIVATE_KEY\");","const signature = await account.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 (agent-friendly)","body":"{ address: \"0x...\" }","response":"{ nonce, message }"},"POST /api/auth/agent-register":{"description":"Verify signature + auto-register in one call (agent-friendly). If already registered, returns existing account. Pass optional \"basename\" to register with a specific Basename handle.","body":"{ address: \"0x...\", signature: \"0x...\", message: \"...\", basename?: \"yourname.base.eth\" }","response":"{ token, email, handle, wallet, registered, new_account, source }","note":"If basename is provided, on-chain ownership is verified via ownerOf. Errors include a \"code\" field: nonce_expired, signature_invalid, no_nonce_in_message."},"GET /api/auth/nonce":{"description":"Get a one-time nonce (legacy, use /start instead)","response":"{ nonce }"},"POST /api/auth/message":{"description":"Build SIWE message (legacy, use /start instead)","body":"{ address, nonce }","response":"{ message }"},"POST /api/auth/verify":{"description":"Verify SIWE signature (legacy, use /agent-register instead)","body":"{ address, signature, message }","response":"{ token, wallet, registered, handle, suggested_handle, suggested_email }"},"POST /api/register":{"auth":"Bearer token or MPP Payment ($1.00)","description":"Register a @basemail.ai email. Pass \"basename\" to claim an existing Basename, or \"auto_basename\" to buy one. Supports MPP: pay $1.00 via Tempo to register without SIWE.","x-payment-info":{"method":"tempo","intent":"charge","amount":"1.00","currency":"USDC.e"},"body":"{ basename?: \"yourname.base.eth\", auto_basename?: boolean, basename_name?: \"desiredname\" }","response":"{ success, email, handle, wallet, basename, source, token, upgrade_hint? }","note":"If no basename provided, defaults to 0x address handle. Response includes upgrade_hint with instructions to upgrade later."},"GET /api/register/check/:address":{"description":"Preview what email a wallet would get (public, no auth). Includes next_steps if basename NFT detected.","response":"{ wallet, handle, email, basename, source, registered, has_basename_nft, next_steps? }"},"PUT /api/register/upgrade":{"auth":"Bearer token","description":"Upgrade 0x handle to Basename handle. Can auto-purchase a Basename if auto_basename is true.","body":"{ basename?: \"name.base.eth\", auto_basename?: boolean, basename_name?: \"desiredname\" }","response":"{ success, email, handle, old_handle, basename, token, migrated_emails }","note":"If auto_basename is true, the worker buys the Basename on-chain (worker pays gas + fees). Otherwise, you must already own the Basename."},"GET /api/register/price/:name":{"description":"Check Basename availability and registration price (public, no auth)","response":"{ name, basename, available, price_wei?, price_eth? }"},"POST /api/send":{"auth":"Bearer token or MPP Payment ($0.01)","description":"Send email. Internal @basemail.ai is free. External costs 1 credit. Supports MPP: pay $0.01 via Tempo to send without SIWE.","x-payment-info":{"method":"tempo","intent":"charge","amount":"0.01","currency":"USDC.e"},"body":"{ to, subject, body, html?, in_reply_to?, attachments?: [{ filename, content_type, data }], usdc_payment?: { tx_hash, amount } }","response":"{ success, email_id, from, to, usdc_payment? }","note":"If usdc_payment is provided, the USDC transfer is verified on-chain (Base Sepolia). See labs.usdc_hackathon for full flow."},"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 (includes raw body)","response":"{ id, from_addr, to_addr, subject, body, created_at, ... }"},"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 ETH payment tx hash to receive credits","body":"{ tx_hash: \"0x...\" }","note":"Send ETH on Base chain to 0x4BbdB896eCEd7d202AD7933cEB220F7f39d0a9Fe, then submit tx hash here.","pricing":"1 ETH = 1,000,000 credits. Min: 0.0001 ETH = 100 credits. 1 credit = 1 external email."},"GET /api/pro/status":{"auth":"Bearer token","description":"Check Pro membership status and pricing","response":"{ handle, tier, is_pro, benefits, upgrade }"},"POST /api/pro/buy":{"auth":"Bearer token","description":"Purchase BaseMail Pro with ETH payment (one-time lifetime)","body":"{ tx_hash: \"0x...\", chain_id?: 8453|1 }","response":"{ success, tier: \"pro\", eth_spent, benefits, bonus_credits }","note":"Send 0.008 ETH to 0x4BbdB896eCEd7d202AD7933cEB220F7f39d0a9Fe on Base or ETH Mainnet, then submit tx hash. Pro removes email signatures, adds gold badge."},"GET /api/attention/price/:handle":{"description":"Get current attention price for a recipient (dynamic pricing)","response":"{ handle, attention_bonds_enabled, base_price_usdc, current_price_usdc, demand_7d, response_window_hours }"},"GET /api/attention/price/:handle/for/:sender":{"description":"Get sender-specific price (includes reply rate discount)","response":"{ handle, sender, price_usdc, reply_rate, whitelisted }"},"GET /api/attention/qaf/:handle":{"description":"Get QAF (Quadratic Attention Funding) score for a recipient","response":"{ handle, qaf_value, unique_senders, total_bonds_usdc, breadth_premium }"},"GET /api/attention/coqaf/:handle":{"description":"Get CO-QAF breakdown with α_ij social graph and per-sender discounted bonds","response":"{ handle, qaf_value, coqaf_value, discount_ratio, alpha_method, senders: [{ sender, bond_usdc, sum_alpha, discounted_bond, connections }] }","note":"α_ij estimated via Jaccard similarity of recipient sets. Bridging senders (low α) retain full weight; bonding senders (high α) are discounted."},"PUT /api/attention/config":{"auth":"Bearer token","description":"Configure your attention bond settings","body":"{ enabled: bool, base_price?: number, alpha?: number, beta?: number, gamma?: number, response_window_hours?: number }"},"POST /api/attention/bond":{"auth":"Bearer token","description":"Record an attention bond deposit (after on-chain tx)","body":"{ email_id, recipient_handle, amount_usdc, tx_hash }"},"POST /api/attention/reply/:email_id":{"auth":"Bearer token","description":"Mark reply to bonded email → triggers refund tracking"},"GET /api/attention/whitelist":{"auth":"Bearer token","description":"List your whitelisted senders"},"POST /api/attention/whitelist":{"auth":"Bearer token","description":"Add sender to whitelist (exempt from bonds)","body":"{ sender_handle?: string, sender_wallet?: string, note?: string }"},"DELETE /api/attention/whitelist/:sender":{"auth":"Bearer token","description":"Remove sender from whitelist"},"GET /api/attention/stats":{"auth":"Bearer token","description":"Dashboard: bonds received/sent, QAF score"},"GET /api/attn/balance":{"auth":"Bearer token","description":"Get your ATTN balance, daily earned, and claim status","response":"{ handle, balance, daily_earned, daily_earn_cap, can_claim, next_claim_in_seconds, constants }"},"POST /api/attn/claim":{"auth":"Bearer token","description":"Claim daily ATTN drip (manual, no accumulation — miss a day, lose it)","response":"{ claimed, amount, balance, next_claim_in_seconds }","note":"Returns claimed:false with reason if already claimed today or cap reached."},"GET /api/attn/history":{"auth":"Bearer token","description":"ATTN transaction history","query":"?limit=20","response":"{ transactions: [{ id, amount, type, note, created_at }] }"},"GET /api/attn/settings":{"auth":"Bearer token","description":"Get your ATTN receive price setting","response":"{ receive_price, note }"},"PUT /api/attn/settings":{"auth":"Bearer token","description":"Set ATTN receive price (how much senders stake to email you)","body":"{ receive_price: 1-10 }"},"POST /api/attn/buy":{"auth":"Bearer token","description":"Purchase ATTN with USDC (on-chain verified)","body":"{ tx_hash: \"0x...\", amount_usdc: number }"},"GET /api/attn-price/:handle":{"description":"Check ATTN stake price for a recipient (public, no auth)","response":"{ handle, attn_enabled, cold_email_stake, reply_thread_stake }"},"GET /api/airdrop/waves":{"auth":"Bearer token","description":"List all airdrop waves with your score and claim status","response":"{ waves: [{ id, name, badge, multiplier, status, score: { breakdown, base_score, total }, claim_opens_at, claimed? }] }","note":"status: preview (locked) | claimable | claimed | expired"},"GET /api/airdrop/:waveId":{"auth":"Bearer token","description":"Get single wave detail with your score breakdown","response":"{ id, name, status, score: { breakdown: { emails_received, emails_read, emails_replied, emails_sent, attn_staked, days_since_signup }, base_score, multiplier, total } }"},"POST /api/airdrop/:waveId/claim":{"auth":"Bearer token","description":"Claim airdrop for a wave (only works after claim opens)","response":"{ claimed, wave, amount, score }","note":"Wave 1 (Early Bird 🐣): 2× multiplier, opens 2026-04-01T04:01 PT. Score = received×1 + read×2 + replied×5 + sent×1 + staked×0.5 + days×2."},"GET /api/airdrop/:waveId/leaderboard":{"auth":"Bearer token","description":"Top 20 airdrop earners for a wave","response":"{ wave, leaderboard: [{ handle, amount, claimed_at }] }"},"POST /api/webhooks":{"auth":"Bearer token","description":"Register a webhook URL to receive real-time notifications (e.g. message.received)","body":"{ url: \"https://...\", events?: [\"message.received\"] }","response":"{ id, url, events, secret, active, created_at }","note":"Store the secret — it is shown only once. Webhook payloads include X-BaseMail-Signature: sha256=<HMAC-SHA256 of body using secret>."},"GET /api/webhooks":{"auth":"Bearer token","description":"List your registered webhooks","response":"{ webhooks: [...] }"},"DELETE /api/webhooks/:id":{"auth":"Bearer token","description":"Delete a webhook"},"GET /api/identity/:address":{"description":"Look up email for any wallet (public, no auth)","response":"{ handle, email, basename }"}},"labs":{"usdc_hackathon":{"title":"USDC Verified Payment Email (TESTNET ONLY)","warning":"This feature runs on Base Sepolia TESTNET. Do NOT use mainnet funds or real USDC.","network":"Base Sepolia (Chain ID: 84532)","usdc_contract":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","description":"Send USDC to any BaseMail user by email address. The payment is verified on-chain and the email is marked as a Verified Payment receipt.","flow":[{"step":1,"action":"Resolve recipient wallet","method":"GET","url":"https://api.basemail.ai/api/identity/:handle","example":"curl https://api.basemail.ai/api/identity/alice","response":"{ handle, email, wallet: \"0x...\" }","note":"Use the \"wallet\" field as the USDC transfer destination."},{"step":2,"action":"Transfer USDC on Base Sepolia","description":"Call USDC.transfer(recipientWallet, amount) on Base Sepolia. Optionally append \"basemail:handle@basemail.ai\" as trailing calldata for on-chain memo.","usdc_contract":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","note":"Amount uses 6 decimals. e.g. 10 USDC = 10000000"},{"step":3,"action":"Send verified payment email","method":"POST","url":"https://api.basemail.ai/api/send","headers":{"Content-Type":"application/json","Authorization":"Bearer YOUR_TOKEN"},"body":{"to":"recipient@basemail.ai","subject":"Payment: 10 USDC","body":"Here is your payment of 10 USDC.","usdc_payment":{"tx_hash":"0x...","amount":"10.00"}},"response":"{ success, email_id, usdc_payment: { verified: true, amount: \"10.00\", tx_hash: \"0x...\", network: \"Base Sepolia (Testnet)\" } }","note":"Worker verifies the USDC Transfer event on-chain before marking the email as a verified payment."}],"on_chain_memo":{"description":"Append recipient basemail address as trailing calldata to USDC transfer for on-chain advertising.","example":"Transfer calldata + hex(\"basemail:alice@basemail.ai\")","note":"Solidity ignores trailing calldata. Visible in BaseScan Input Data field."},"faucets":{"description":"Get free testnet tokens to test USDC payments.","eth":{"url":"https://www.alchemy.com/faucets/base-sepolia","amount":"0.1 ETH per 24 hours","note":"Select \"Base Sepolia\" network, paste your wallet address."},"usdc":{"url":"https://faucet.circle.com/","amount":"20 USDC per 2 hours","note":"Select \"Base Sepolia\" network, paste your wallet address."}},"agent_quickstart":{"overview":"Full flow for AI agents to send USDC payments via email. 4 steps total.","steps":[{"step":0,"action":"Get testnet tokens","description":"Your wallet needs Base Sepolia ETH (for gas) and USDC (to send). Use the faucets above, or ask a human to send you some.","eth_faucet":"https://www.alchemy.com/faucets/base-sepolia","usdc_faucet":"https://faucet.circle.com/"},{"step":1,"action":"Register on BaseMail (if not already)","method":"POST /api/auth/start → POST /api/auth/agent-register","note":"See quick_start above for full auth flow."},{"step":2,"action":"Resolve recipient email → wallet address","method":"GET","url":"https://api.basemail.ai/api/identity/:handle","note":"Use the wallet address as the USDC transfer destination."},{"step":3,"action":"Transfer USDC on-chain (Base Sepolia)","description":"Call USDC contract transfer(recipientWallet, amountInSmallestUnit). USDC has 6 decimals, so 10 USDC = 10000000.","contract":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","chain_id":84532},{"step":4,"action":"Send verified payment email","method":"POST","url":"https://api.basemail.ai/api/send","body":"{ to: \"handle@basemail.ai\", subject: \"Payment: 10 USDC\", body: \"...\", usdc_payment: { tx_hash: \"0x...\", amount: \"10.00\" } }","note":"Worker verifies the USDC transfer on Base Sepolia and marks the email as a Verified Payment."}]}}},"notes":["Base URL is https://api.basemail.ai (or https://basemail.ai/api/* which redirects here)","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 (@basemail.ai to @basemail.ai) are FREE and unlimited","External emails cost 1 credit each — buy credits by sending ETH on Base chain","Deposit address for credits: 0x4BbdB896eCEd7d202AD7933cEB220F7f39d0a9Fe","Wallet addresses are case-insensitive","If your wallet has a Basename (e.g. alice.base.eth), your email will be alice@basemail.ai","Without a Basename, your email will be 0xYourAddress@basemail.ai","Both addresses receive mail if you have a Basename","Already registered with 0x handle? Use PUT /api/register/upgrade with auto_basename:true to purchase a Basename and upgrade","Check name availability first: GET /api/register/price/:name","Auth errors include a \"code\" field (nonce_expired, signature_invalid, no_nonce_in_message) for programmatic error handling","If GET /api/register/check shows has_basename_nft:true but basename:null, pass your basename directly in agent-register: { basename: \"yourname.base.eth\" }","All auth responses include \"tier\" field: \"free\" or \"pro\"","Free-tier emails include a BaseMail.ai signature. Upgrade to Pro (0.008 ETH one-time) to remove it."]}