{"openapi":"3.1.0","info":{"title":"Ava Genesis Agent API","version":"2.0.0","description":"ERC-20 token deployment for AI agents. One call to POST /api/agents/deploy-token — no wallet, no gas, no signing. Platform deploys and returns the contract address. $10 flat on mainnet, free on Sepolia testnet.","contact":{"name":"Ava Genesis","url":"https://avagenesis.com/agents","email":"support@avagenesis.com"},"license":{"name":"Proprietary","url":"https://avagenesis.com/terms"}},"servers":[{"url":"https://avagenesis.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ava_live_<48-hex-chars>","description":"API key obtained from POST /api/agents/keys"}},"schemas":{"TokenFeatures":{"type":"object","properties":{"mintable":{"type":"boolean","default":false},"burnable":{"type":"boolean","default":false},"pausable":{"type":"boolean","default":false},"blacklist":{"type":"boolean","default":false},"transferTax":{"type":"integer","minimum":0,"maximum":2500,"default":0,"description":"Basis points (100 = 1%)"},"antiWhale":{"type":"boolean","default":false},"maxWalletPercent":{"type":"integer","minimum":0,"maximum":100,"default":0}}},"SupportedChain":{"type":"string","enum":["ethereum","base","bnb","polygon","sepolia"],"description":"Use 'sepolia' for free testnet deployments"},"IntentStatus":{"type":"string","enum":["awaiting_payment","paid","deploying","deployed","failed"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}}}},"paths":{"/api/agents/deploy-token":{"post":{"operationId":"deployToken","summary":"Deploy an ERC-20 token (recommended — no wallet needed)","description":"One-call deployment. The platform wallet signs, broadcasts, waits for on-chain confirmation, then returns the contract address. Agent needs no wallet, no ETH, no signing. Supports mainnet chains ($10 flat) and Sepolia testnet (free). Optionally pass ownerAddress to transfer tokens and initiate ownership transfer (agent must call acceptOwnership() once).","x-idempotency":"Supported via X-Idempotency-Key header","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","name","symbol","supply"],"properties":{"chain":{"$ref":"#/components/schemas/SupportedChain"},"name":{"type":"string","maxLength":64},"symbol":{"type":"string","maxLength":16,"pattern":"^[A-Z0-9]+$"},"supply":{"type":"string","description":"Human-readable supply (e.g. '1000000')"},"decimals":{"type":"integer","minimum":0,"maximum":18,"default":18},"ownerAddress":{"type":"string","description":"Wallet that receives tokens + ownership. If omitted, platform deployer keeps them."},"template":{"type":"string","description":"Template ID from /api/agents/templates"},"features":{"$ref":"#/components/schemas/TokenFeatures"},"callbackUrl":{"type":"string","format":"uri","description":"Webhook URL for status updates"},"idempotencyKey":{"type":"string","description":"Unique key for safe retries (also accepted as X-Idempotency-Key header)"}}},"example":{"chain":"sepolia","name":"Agent Test Token","symbol":"ATT","supply":"1000000","ownerAddress":"0xYourWalletAddress"}}}},"responses":{"200":{"description":"When called via MCP (ava_deploy_token tool) — returns after on-chain confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"status":{"type":"string","example":"deployed"},"contractAddress":{"type":"string"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"chain":{"type":"string"},"txHash":{"type":"string"},"explorerUrl":{"type":"string"},"tokenUrl":{"type":"string"}}}}}},"202":{"description":"Deployment started — polls automatically, returns contract address when confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"status":{"type":"string","example":"deploying"},"intentId":{"type":"string"},"message":{"type":"string"},"status_url":{"type":"string"},"stream_url":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Invalid or missing API key"},"429":{"description":"Rate limit or monthly limit exceeded"},"503":{"description":"Platform deployer not configured or factory unavailable"}}}},"/api/agents/keys":{"post":{"operationId":"createApiKey","summary":"Create API key","description":"Create a new Agent API key. The raw key is returned once and never stored.","security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80,"description":"Human-readable label for the key"},"monthlyLimit":{"type":"integer","minimum":1,"maximum":1000,"default":100},"metadata":{"type":"object","description":"Optional key-value metadata"}}}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string","description":"Raw API key — store securely, shown once"},"id":{"type":"string"},"prefix":{"type":"string"},"name":{"type":"string"},"monthlyLimit":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}}},"429":{"description":"Rate limit exceeded"}}},"get":{"operationId":"listApiKeys","summary":"List API keys","security":[],"responses":{"200":{"description":"List of keys (no raw key values)"}}}},"/api/agents/keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke API key","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked"},"404":{"description":"Key not found"}}}},"/api/agents/gas-prices":{"get":{"operationId":"getGasPrices","summary":"Get gas prices across all chains","description":"Returns current gas price and estimated deployment cost per chain. Sorted cheapest first. Use to choose the optimal chain before deploying.","security":[],"responses":{"200":{"description":"Gas price data for all supported chains"}}}},"/api/agents/templates":{"get":{"operationId":"listTemplates","summary":"List token templates","description":"Pre-built token configurations. Pass 'template' field in create-token to auto-fill features.","security":[],"responses":{"200":{"description":"Array of templates"}}}},"/api/agents/simulate-token":{"post":{"operationId":"simulateToken","summary":"Dry-run token deployment validation","description":"Validate a create-token payload without creating an intent or spending gas. Returns encoded calldata and fee estimate.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTokenRequest"},"example":{"chain":"base","name":"Agent Token","symbol":"AGT","supply":"1000000","decimals":18,"features":{"mintable":false,"burnable":true}}}}},"responses":{"200":{"description":"Simulation result with fee + calldata"},"400":{"description":"Validation errors"}}}},"/api/agents/create-token":{"post":{"operationId":"createToken","summary":"Create token deployment intent","description":"Validates the request, creates a deployment intent, and returns pre-encoded calldata for the agent to sign and broadcast. After broadcasting, submit the txHash to /api/agents/confirm/{intentId}.","x-idempotency":"Supported via X-Idempotency-Key header","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","name","symbol","supply"],"properties":{"chain":{"$ref":"#/components/schemas/SupportedChain"},"name":{"type":"string","maxLength":64},"symbol":{"type":"string","maxLength":16,"pattern":"^[A-Z0-9]+$"},"supply":{"type":"string","description":"Human-readable supply (e.g. '1000000')"},"decimals":{"type":"integer","minimum":0,"maximum":18,"default":18},"template":{"type":"string","description":"Template ID from /api/agents/templates"},"features":{"$ref":"#/components/schemas/TokenFeatures"},"callbackUrl":{"type":"string","format":"uri","description":"Webhook URL for status updates"}}},"example":{"chain":"base","name":"Agent Genesis Token","symbol":"AGT","supply":"1000000","decimals":18,"template":"governance","callbackUrl":"https://example.com/webhook"}}}},"responses":{"201":{"description":"Intent created — broadcast the returned transaction","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"intentId":{"type":"string"},"status":{"type":"string"},"next_step":{"type":"object"},"fee":{"type":"object"},"confirm_url":{"type":"string"},"status_url":{"type":"string"},"stream_url":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Invalid or missing API key"},"429":{"description":"Rate limit or monthly limit exceeded"},"503":{"description":"Factory not deployed on requested chain"}}}},"/api/agents/confirm/{intentId}":{"post":{"operationId":"confirmDeployment","summary":"Submit deployment transaction hash","description":"After broadcasting the createToken() transaction, submit the txHash here. The server monitors on-chain and updates the intent status automatically.","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["txHash"],"properties":{"txHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}}}}},"responses":{"200":{"description":"Tx received, monitoring started"},"404":{"description":"Intent not found"},"409":{"description":"Intent already failed"}}}},"/api/agents/status/{intentId}":{"get":{"operationId":"getDeploymentStatus","summary":"Poll deployment status","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Intent status and details"},"404":{"description":"Intent not found"}}}},"/api/agents/status-stream/{intentId}":{"get":{"operationId":"streamDeploymentStatus","summary":"Real-time deployment status via SSE","description":"Server-Sent Events stream. Emits status updates every 5 seconds until deployed or failed.","parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}},"/api/agents/my-tokens":{"get":{"operationId":"listMyTokens","summary":"List tokens deployed by this API key","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/IntentStatus"}},{"name":"chain","in":"query","schema":{"$ref":"#/components/schemas/SupportedChain"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Token list with summary"}}}},"/api/agents/submit-listing":{"post":{"operationId":"submitListing","summary":"Submit token for exchange listing","description":"Submit a deployed token for Trust Wallet, Etherscan, or CoinGecko listing. Requires a separate listing fee payment txHash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service","tokenAddress","chainId","txHash","logoUrl","tokenName","tokenSymbol"],"properties":{"service":{"type":"string","enum":["trust-wallet","etherscan","coingecko","bundle"]},"tokenAddress":{"type":"string"},"chainId":{"type":"integer","enum":[1,56,137,8453]},"txHash":{"type":"string"},"logoUrl":{"type":"string","format":"uri"},"tokenName":{"type":"string"},"tokenSymbol":{"type":"string"},"decimals":{"type":"integer","default":18},"website":{"type":"string","format":"uri"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"Listing submitted"},"400":{"description":"Validation error"},"402":{"description":"Payment verification failed"}}}},"/api/agents/transfer-ownership":{"post":{"operationId":"transferOwnership","summary":"Get calldata to transfer token ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","contractAddress","newOwner"],"properties":{"chain":{"$ref":"#/components/schemas/SupportedChain"},"contractAddress":{"type":"string"},"newOwner":{"type":"string"}}}}}},"responses":{"200":{"description":"Encoded transfer calldata"}}}},"/api/agents/airdrop":{"post":{"operationId":"airdrop","summary":"Get calldata for token airdrop","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chain","contractAddress","recipients"],"properties":{"chain":{"$ref":"#/components/schemas/SupportedChain"},"contractAddress":{"type":"string"},"decimals":{"type":"integer","default":18},"recipients":{"type":"array","maxItems":500,"items":{"type":"object","required":["address","amount"],"properties":{"address":{"type":"string"},"amount":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Array of encoded transfer transactions"}}}}}}