{ "openapi": "3.1.0", "info": { "title": "Base Alpha Agent API", "version": "1.0.0", "description": "DEX aggregator API on Base chain. Get best-price swap quotes across Aerodrome, Uniswap V3, and PancakeSwap. All endpoints are x402-protected — pay with USDC on Base.", "contact": { "url": "https://base-alpha.xyz/agents" } }, "servers": [ { "url": "https://base-alpha.xyz", "description": "Production" } ], "security": [ { "x402": [] } ], "paths": { "/api/agent/quote": { "get": { "operationId": "getSwapQuote", "summary": "Get best swap quote across all DEXes", "description": "Returns the best-price quote for a token swap, comparing Aerodrome, Uniswap V3, and PancakeSwap. Cost: $0.001 USDC via x402.", "parameters": [ { "name": "tokenIn", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Address of token to sell (e.g. 0x4200000000000000000000000000000000000006 for WETH)" }, { "name": "tokenOut", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Address of token to buy (e.g. 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 for USDC)" }, { "name": "amountIn", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Amount to sell in raw token units (uint256 string, e.g. 1000000000000000000 for 1 WETH)" }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Slippage tolerance in basis points (default 50 = 0.5%)" } ], "responses": { "200": { "description": "Best quote found", "content": { "application/json": { "schema": { "type": "object", "properties": { "amountOut": { "type": "string", "description": "Expected output in raw token units" }, "minAmountOut": { "type": "string", "description": "Minimum output after slippage" }, "pool": { "type": "string", "description": "Pool address used for the swap" }, "dexId": { "type": "string", "description": "DEX identifier (aerodrome, uniswap-v3, etc.)" }, "dexName": { "type": "string", "description": "Human-readable DEX name" }, "feeBps": { "type": "integer", "description": "Platform fee in basis points" }, "feeAmount": { "type": "string", "description": "Fee amount in tokenIn units" }, "pricePerTokenIn": { "type": "number", "description": "Price of tokenIn in tokenOut units" } } } } } }, "400": { "description": "Missing or invalid parameters" }, "402": { "description": "Payment required — returns x402 PaymentRequirements" } } } }, "/api/agent/swap": { "post": { "operationId": "buildSwapTransaction", "summary": "Build unsigned swap transaction", "description": "Builds an unsigned swap transaction routed through FeeRouter. The agent must approve the token, then send the transaction. Cost: $0.01 USDC via x402.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tokenIn", "tokenOut", "amountIn", "recipient"], "properties": { "tokenIn": { "type": "string", "description": "Address of token to sell" }, "tokenOut": { "type": "string", "description": "Address of token to buy" }, "amountIn": { "type": "string", "description": "Amount in raw token units" }, "recipient": { "type": "string", "description": "Wallet address to receive output tokens" }, "slippageBps": { "type": "integer", "default": 50, "description": "Slippage tolerance in basis points" } } } } } }, "responses": { "200": { "description": "Unsigned transaction ready for signing", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object", "properties": { "to": { "type": "string" }, "data": { "type": "string" }, "value": { "type": "string" }, "chainId": { "type": "integer" } } }, "approval": { "type": "object", "properties": { "token": { "type": "string" }, "spender": { "type": "string" }, "amount": { "type": "string" } } }, "quote": { "type": "object" } } } } } }, "402": { "description": "Payment required" } } } }, "/api/agent/tokens": { "get": { "operationId": "listTokens", "summary": "List available tokens with USD prices", "description": "Returns all tokens available for trading on Base Alpha with current USD prices. Cost: $0.001 USDC via x402.", "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "priceUsd": { "type": "number" } } } }, "total": { "type": "integer" } } } } } }, "402": { "description": "Payment required" } } } }, "/api/agent/pools": { "get": { "operationId": "listPools", "summary": "List liquidity pools", "description": "Returns liquidity pools on Base, optionally filtered by token. Cost: $0.001 USDC via x402.", "parameters": [ { "name": "token0", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by first token address" }, { "name": "token1", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by second token address" } ], "responses": { "200": { "description": "Pool list", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "token0": { "type": "string" }, "token1": { "type": "string" }, "token0Symbol": { "type": "string" }, "token1Symbol": { "type": "string" }, "tvlUsd": { "type": "number" }, "dexId": { "type": "string" }, "dexName": { "type": "string" } } } }, "total": { "type": "integer" } } } } } }, "402": { "description": "Payment required" } } } } }, "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "X-PAYMENT", "description": "x402 payment header. First request returns 402 with PaymentRequirements. Sign with USDC on Base and attach as X-PAYMENT header." } } } }