AgentSwap API ============= Optimal DEX routing for AI agents. Base URL: https://api.agentswap.co ENDPOINTS --------- POST /quote Get the best swap route across 14+ DEXes on Base and Arbitrum. Headers: Content-Type: application/json, X-API-Key: Request body: chain_id u64 Required. 8453 (Base) or 42161 (Arbitrum). token_in address Required. Input token contract address. token_out address Required. Output token contract address. amount_in string Required. Raw amount with decimals (e.g. "1000000000" for 1000 USDC). slippage_bps u16 Optional. Default 50 (0.5%). taker address Optional. Wallet address that will submit the execution transaction. allow_partial bool Optional. Default false. Notes: Smart Router derives USD sizing internally from chain-local pricing data. Client-supplied extra fields such as amount_usd are ignored. Response: dex string "AgentSwap" output string Net output amount (raw, with decimals). gas_estimate string Estimated gas units. source string "local" | "path_hint" | "rpc" route_path string Human-readable route, e.g. "USDC>[UniV3:500]>WETH" price_impact_bps u16 Price impact in basis points. pool_grades [string] Pool quality grades (A-F) for each hop. router address Legacy executor contract address compatibility field. calldata string Legacy ABI-encoded calldata compatibility field. execution object Explicit wallet execution payload for executable routes. spender address Contract that must receive ERC20 allowance. target address Transaction `to` address. calldata string Transaction data payload. value string Hex msg.value quantity, always present for executable routes. route_readiness string "ready" | "verified" | "custody_invalid" | other non-executable states. steps [object] Per-hop route details. last_sync_block u64 Latest synced block number. sync_lag_ms u64 Milliseconds since last sync. verify_block_lag u64 Blocks between cached state and on-chain verification (verify=true only). tax_in_bps u16 Fee-on-transfer input tax (0 for standard tokens). tax_out_bps u16 Fee-on-transfer output tax (0 for standard tokens). route_executable bool True only when the returned execution payload is directly executable. route_unexecutable_reason string Machine-readable reason when execution is unavailable. Errors: 400 bad request, 402 quota exhausted, 404 no route found. POST /quote_lp_disposal Route an LP position's tokens into one target token using USD value instead of raw amounts. Built for callers that know a position's USD value but not exact per-token amounts (e.g. liquidation bots pre-baking a route before crossing). Smart Router converts each leg's value_usd to a raw amount using its cached USD-per-raw-unit price, so the caller never needs token decimals. SAFETY: the value-derived amount is biased strictly DOWN (floor + haircut, plus an optional hard cap) so a stale/understated price can never make the route try to consume MORE token than is held (over-consume -> revert). Under-consuming is safe. For volatile collateral, supply a per-leg max_amount hard ceiling; for guaranteed-exact execution, supply an explicit amount (haircut not applied). Headers: Content-Type: application/json, X-API-Key: Request body: chain_id u64 Required. 8453 (Base) or 42161 (Arbitrum). target_token address Required. Token every leg is routed into (e.g. repay token). legs [object] Required. The position's tokens (1-8). Each: token address Required. One of the position's tokens. value_usd f64 Estimated USD value held in this token. Ignored if `amount` set. amount string Optional. Explicit raw amount override (skips USD estimation + haircut). max_amount string Hard upper bound (raw); resolved amount is clamped to it. REQUIRED for value-derived legs (no explicit amount) unless allow_unbounded_estimate=true. Makes over-consume impossible regardless of price staleness. Derive it from position liquidity. slippage_bps u16 Optional. Default 50 (0.5%). amount_haircut_bps u16 Optional. Default 50. Bias applied DOWN to value-derived amounts (not to explicit amount). taker address Optional. Wallet that will submit the execution transaction. routing_mode string Optional. "deep" (default) or "ultra". allow_partial bool Optional. Default false. When true, a failed leg is reported in-band (error field) instead of failing the whole request. allow_unbounded_estimate bool Optional. Default false. Opt out of the max_amount requirement for value-derived legs. Use ONLY for estimation / route-shape discovery (not verbatim execution) — caller owns staleness risk. Response: chain_id u64 target_token address complete bool True when every non-passthrough leg routed. If false (only with allow_partial=true), DO NOT treat the bundle as complete. failed_legs usize Count of failed legs (0 when complete). total_estimated_output string Sum of every leg's output in target token (estimate). legs [object] Per leg: token address value_usd f64 estimated_amount_in string Raw amount SR resolved/used (post-haircut, post-cap). amount_source string "value_usd" | "explicit". capped bool True if clamped to max_amount (omitted when false). passthrough bool True when token == target_token (no swap needed). quote object Full route + calldata (same shape as POST /quote). Omitted for passthrough. error string Present only for a failed leg when allow_partial=true. Errors: 400 bad request (unpriced token without amount, bad address, too many legs), 402 quota exhausted, 404 no route found for a leg (when allow_partial=false). GET /quote_exact_output Find a SmartRouter route that minimizes input for a target output. Headers: X-API-Key: Query parameters: chain_id u64 Required. 8453 (Base) or 42161 (Arbitrum). token_in address Required. Input token contract address. token_out address Required. Output token contract address. target_output string Required. Desired output amount, raw with decimals. max_input string Required. Maximum input amount, raw with decimals. slippage_bps u16 Optional. Default 50 (0.5%). executable_only bool Optional. Default true. verify bool Optional. Default false. Response: Same shape as POST /quote, plus input_consumed string. source is "SmartRouter:exact_output_via_exact_input" for the initial implementation. Notes: The route uses the existing exact-input calldata path at the solved input amount. The endpoint consumes 16 quote quota/rate-limit units because it performs bounded internal exact-input probes. If the target is unreachable within max_input, the response is HTTP 200 with route_executable=false and route_unexecutable_reason="target_unreachable". POST /compare/simulate Compare normalized aggregator execution payloads by dry-run realized output. Headers: Content-Type: application/json, X-API-Key: Request body: chainId u64 Required. 8453 (Base) or 42161 (Arbitrum). candidates [object] Required. At least one normalized execution candidate. providerId string Provider label, e.g. "agentswap", "odos", "lifi", "kyberswap". target address Transaction `to` address for execution. data string ABI-encoded calldata. value string Hex or decimal msg.value quantity. inputToken address Input token address (use zero address for native input). outputToken address Output token address. inputAmount string Raw input amount. approveTarget address ERC20 allowance spender used for simulation. quotedOutput string Aggregator-reported quote output amount. Response: results [object] Per-provider simulation results in request order. providerId string Provider label from the request. status string "ok" | "simulation_failed" | "simulation_unavailable". success bool True only when dry-run simulation succeeded. quotedOutput string Provider-reported quote output amount. actualOutput string Simulated realized output amount when successful. accuracyDelta string actualOutput - quotedOutput, signed decimal string. accuracyBps u32 actualOutput / quotedOutput * 10000 when successful. error string Failure reason when simulation is unavailable or failed. winnerProviderId string Provider with the highest actualOutput among successful simulations. Notes: ERC20 input simulation depends on balance-slot discovery and state overrides. Native input routes are simulated with each candidate's own msg.value. Errors: 400 bad request, 402 quota exhausted, 503 RPC unavailable. GET /auth/pricing Returns x402-style pricing metadata and on-chain quota purchase contracts. No auth required. Response: x402_version u8 Protocol version (2). unit_price_usd f64 Price per quote in USD (0.0001). unit_price_usdc_6dec u64 Price per quote in USDC 6-decimal units (100). contracts [object] Per-chain quota contract info: chain_id u64 Chain ID. network string CAIP-2 identifier (e.g. "eip155:8453"). quota_contract address ApiQuotaManager contract. payment_token address USDC address on that chain. amount_per_quote string Raw USDC amount per quote. POST /auth/quota/claim Apply purchased quota from an on-chain payment transaction. Headers: Content-Type: application/json, X-API-Key: Request body: chain_id u64 Required. Chain where payment was made. tx_hash string Required. Transaction hash of the payment. Response: purchased_quotes u64 Number of quotes purchased in this tx. quota_total u64 Total quota for this key. quota_used u64 Quota already consumed. quota_remaining u64 Remaining quota. GET /health Health check. No auth required. Response: status string "ok" | "degraded" | "error" version string Service version. uptime_secs u64 Seconds since service start. GET /api/tokens Token registry. No auth required. Response: JSON object mapping address -> {chain_id, symbol, decimals}. AUTHENTICATION -------------- Quota-based. Each API key has a quote quota. 1. Call GET /auth/pricing to discover per-quote price and payment contracts. 2. Send USDC to the ApiQuotaManager contract on-chain. 3. Call POST /auth/quota/claim with the tx hash to credit your key. 4. Include X-API-Key header on POST /quote requests. Rate limit headers returned: x-ratelimit-limit, x-ratelimit-remaining. DISCOVERY --------- EIP-8004 agent metadata: GET /.well-known/agent-registration.json CHAINS & DEXES -------------- GET /api/chains returns live chain/DEX metadata. No auth required. COMMON TOKENS ------------- Base: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 6 decimals WETH 0x4200000000000000000000000000000000000006 18 decimals DAI 0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb 18 decimals cbBTC 0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf 8 decimals AERO 0x940181a94A35A4569E4529A3CDfB74e38FD98631 18 decimals Arbitrum: USDC 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 6 decimals WETH 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 18 decimals USDT 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 6 decimals ARB 0x912CE59144191C1204E64559FE8253a0e49E6548 18 decimals WBTC 0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f 8 decimals EXECUTOR CONTRACTS ------------------ Base: 0x8b4F80818376FE1903c930A2a74823611732c7f4 Arbitrum: 0xA42Ec81A70e7406dE266eCB36E376786E5716519 ERROR CODES ----------- 400 Bad Request Invalid token address or unsupported chain_id. 401 Unauthorized Missing or invalid API key. 402 Payment Required Quota exhausted. Response includes payment-required header. 404 Not Found No route found for the given pair/amount. 429 Too Many Requests Rate limit exceeded. 503 Unavailable Service degraded.