{"openapi":"3.1.0","info":{"title":"Cross-Chain Liquidity & Execution Route Optimizer","summary":"Find the cheapest cross-chain EVM token swap route. Zero LLM, deterministic math, L402 Lightning payment.","description":"## What this API does\n\nGiven a token swap intent, this API queries **1inch** and **Li.Fi** aggregators in\nparallel, then scores every route using the **True Execution Cost (TEC)** formula:\n\n```\nTEC   = C_slippage + C_gas + C_bridge_fee + C_time_penalty\nSCORE = (amount_out × target_price_usd) − TEC − amount_in_usd\n```\n\nThe route with the highest `SCORE` is returned as `optimal_route`.\n\n**Zero LLM at runtime** — every number is derived from live on-chain data.\n\n---\n\n## Who should call this API\n\nAutonomous AI agents and trading bots that need to:\n- Execute a DeFi token swap on any EVM chain\n- Compare same-chain vs cross-chain costs mathematically\n- Get slippage estimates before signing a transaction\n\n---\n\n## Payment: L402 Lightning Protocol\n\nThis API charges **10 satoshis** (≈ $0.006) per query via the L402 standard.\n\n### Agent payment flow\n\n```\n1. POST /v1/quote  →  HTTP 402\n   WWW-Authenticate: L402 macaroon=<token>, invoice=<BOLT11>\n\n2. Pay the BOLT11 Lightning invoice.\n   Your wallet returns a 32-byte preimage (proof of payment).\n\n3. POST /v1/quote  (same body)\n   Authorization: L402 <macaroon>:<preimage_hex>\n   →  HTTP 200  (route data)\n```\n\nMacaroon TTL: **600 seconds** from payment.\n\n---\n\n## Supported chains & tokens\n\n**Chains:** `ethereum`, `arbitrum`, `base`, `optimism`, `polygon`\n\n**Tokens:** `ETH`, `USDC`, `USDT`, `DAI`, `WETH`\n\n---\n\n## Machine discovery\n\n| Resource | URL |\n|----------|-----|\n| LLM guide (llmstxt.org) | `/llms.txt` |\n| AI plugin manifest | `/.well-known/ai-plugin.json` |\n| Agent manifest | `/.well-known/agent-manifest.json` |\n| Schema.org structured data | `/schema.json` |\n","termsOfService":"https://optimizer-api-crypto.onrender.com/info","contact":{"name":"Optimizer API Support","email":"peretzbatel123@gmail.com"},"version":"0.1.0"},"servers":[{"url":"https://optimizer-api-crypto.onrender.com","description":"Production"},{"url":"http://localhost:8000","description":"Local development"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health","description":"Liveness probe — returns 200 as long as the process is running.\nNo payment required. Used by Railway/Fly.io health checks and agent pre-flight.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/info":{"get":{"tags":["System"],"summary":"Info","description":"Returns API metadata and current pricing.\n\nNo payment required. Agents should call this before /v1/quote to discover:\n- Current price in satoshis (may change)\n- Macaroon TTL (how long after payment the token remains valid)\n- Supported chains and tokens","operationId":"info_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Info Info Get"}}}}}}},"/v1/quote":{"post":{"tags":["Optimizer"],"summary":"Get optimal cross-chain execution route","description":"Returns the mathematically optimal execution route for a token swap across one or more EVM chains.  Requires L402 Lightning payment. All computation is deterministic — zero LLM, zero heuristics.","operationId":"get_optimal_quote_v1_quote_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"required":true},"responses":{"200":{"description":"Optimal route found (or null if no viable routes exist)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimalRouteResponse"}}}},"402":{"description":"Payment required — see WWW-Authenticate header for Lightning invoice"},"422":{"description":"Invalid request body"},"503":{"description":"All aggregators failed — retry shortly"}}}}},"components":{"schemas":{"Chain":{"type":"string","enum":["ethereum","arbitrum","base","optimism","polygon"],"title":"Chain","description":"Supported EVM-compatible chains.  Add new chains here only — do not\nscatter chain IDs as magic strings throughout the codebase."},"OptimalRouteResponse":{"properties":{"optimal_route":{"anyOf":[{"$ref":"#/components/schemas/RouteBreakdownResponse"},{"type":"null"}]},"all_routes":{"items":{"$ref":"#/components/schemas/RouteBreakdownResponse"},"type":"array","title":"All Routes"},"gas_snapshot":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Gas Snapshot"},"meta":{"additionalProperties":true,"type":"object","title":"Meta"}},"type":"object","required":["optimal_route","all_routes","gas_snapshot","meta"],"title":"OptimalRouteResponse","description":"Top-level API response for POST /v1/quote.\n\nStructure:\n  optimal_route  — the single best route (highest profit_score among viable routes)\n  all_routes     — full ranked list (viable first, then disqualified, for agent debugging)\n  gas_snapshot   — current gas prices per chain for agent auditability\n  meta           — request echo + timing stats"},"QuoteRequest":{"properties":{"token_in":{"type":"string","maxLength":10,"minLength":1,"title":"Token In","description":"Input token ticker symbol (uppercase). Supported values: 'ETH', 'USDC', 'USDT', 'DAI', 'WETH'. Must differ from token_out.","examples":["ETH"]},"token_out":{"type":"string","maxLength":10,"minLength":1,"title":"Token Out","description":"Output token ticker symbol (uppercase). Supported values: 'ETH', 'USDC', 'USDT', 'DAI', 'WETH'. Must differ from token_in.","examples":["USDC"]},"amount_in":{"type":"number","exclusiveMinimum":0.0,"title":"Amount In","description":"Input amount in native token units (not USD, not wei). Example: 5.0 means 5 ETH, not 5 USDC. Must be > 0.","examples":[5.0]},"amount_in_usd":{"type":"number","exclusiveMinimum":0.0,"title":"Amount In Usd","description":"Current USD value of amount_in. The agent must pre-compute this from a price oracle (e.g. CoinGecko) before calling the API. Example: if amount_in=5.0 ETH and ETH=$3700, set amount_in_usd=18500.0. This value drives the slippage cost component of TEC.","examples":[18500.0]},"target_price_usd":{"type":"number","exclusiveMinimum":0.0,"title":"Target Price Usd","description":"Current spot price of token_out in USD, fetched by the agent from a price oracle. Used to compute Net Output Value (NOV = amount_out × target_price_usd). For stablecoins (USDC, USDT, DAI), this is typically 1.0. For ETH as token_out, use the current ETH/USD price.","examples":[1.0]},"chains":{"items":{"$ref":"#/components/schemas/Chain"},"type":"array","maxItems":5,"minItems":1,"title":"Chains","description":"List of EVM chains to include in the route search. Supported values: 'ethereum', 'arbitrum', 'base', 'optimism', 'polygon'. Including multiple chains enables cross-chain route discovery via Li.Fi. Single-chain lists restrict results to same-chain DEX routes (1inch). No duplicates allowed.","examples":[["arbitrum","base"]]},"max_slippage_bps":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Max Slippage Bps","description":"Maximum acceptable slippage in basis points (1 bps = 0.01%). Routes with slippage_bps above this threshold are disqualified. Default: 100 (1%). For large orders, consider raising to 200–300. For stablecoin swaps, consider lowering to 10–30.","default":100,"examples":[100]},"agent_time_value_per_second":{"type":"number","minimum":0.0,"title":"Agent Time Value Per Second","description":"USD value of one second of agent waiting time. Multiplied by bridge_time_seconds to compute the time penalty cost component. Default 0.0001 USD/s ≈ $0.36/hr. Raise this for time-sensitive agents (e.g. 0.01 = $36/hr). Set to 0.0 to ignore bridge time entirely in the TEC score.","default":0.0001,"examples":[0.0001]},"max_bridge_time_seconds":{"type":"integer","minimum":0.0,"title":"Max Bridge Time Seconds","description":"Hard upper limit on cross-chain bridge settlement time in seconds. Routes with bridge_time_seconds above this value are excluded entirely (not just penalised). Default: 900 (15 minutes). Set to 0 to allow only same-chain routes. Set to 3600 to allow routes up to 1 hour.","default":900,"examples":[900]}},"additionalProperties":false,"type":"object","required":["token_in","token_out","amount_in","amount_in_usd","target_price_usd","chains"],"title":"QuoteRequest","description":"Agent-facing POST /v1/quote request body.\n\nAgents must supply pre-converted USD values so the optimizer never\nneeds to hit a price oracle mid-request — keeping latency minimal."},"RouteBreakdownResponse":{"properties":{"route_id":{"type":"string","title":"Route Id"},"source":{"type":"string","title":"Source"},"route_type":{"type":"string","title":"Route Type"},"chain_in":{"type":"string","title":"Chain In"},"chain_out":{"type":"string","title":"Chain Out"},"token_in":{"type":"string","title":"Token In"},"token_out":{"type":"string","title":"Token Out"},"amount_out":{"type":"number","title":"Amount Out"},"amount_out_min":{"type":"number","title":"Amount Out Min"},"effective_rate":{"type":"number","title":"Effective Rate"},"profit_score":{"type":"number","title":"Profit Score"},"net_output_value_usd":{"type":"number","title":"Net Output Value Usd"},"true_execution_cost_usd":{"type":"number","title":"True Execution Cost Usd"},"slippage_usd":{"type":"number","title":"Slippage Usd"},"gas_usd":{"type":"number","title":"Gas Usd"},"bridge_fee_usd":{"type":"number","title":"Bridge Fee Usd"},"time_penalty_usd":{"type":"number","title":"Time Penalty Usd"},"slippage_bps":{"type":"integer","title":"Slippage Bps"},"pool_liquidity_usd":{"type":"number","title":"Pool Liquidity Usd"},"bridge_time_seconds":{"type":"integer","title":"Bridge Time Seconds"},"is_viable":{"type":"boolean","title":"Is Viable"},"disqualification_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disqualification Reason"}},"type":"object","required":["route_id","source","route_type","chain_in","chain_out","token_in","token_out","amount_out","amount_out_min","effective_rate","profit_score","net_output_value_usd","true_execution_cost_usd","slippage_usd","gas_usd","bridge_fee_usd","time_penalty_usd","slippage_bps","pool_liquidity_usd","bridge_time_seconds","is_viable","disqualification_reason"],"title":"RouteBreakdownResponse","description":"Per-route detail surfaced in the API response."}}},"tags":[{"name":"Optimizer","description":"Core route optimization endpoint. Requires L402 Lightning payment. Returns True Execution Cost analysis across all aggregators."},{"name":"System","description":"Health checks and API metadata. No payment required."},{"name":"Discovery","description":"Machine-discovery endpoints for AI agents, LLMs, and crawlers. No payment required. Includes llms.txt, ai-plugin.json, robots.txt."}]}