{ "openapi": "3.0.0", "info": { "description": "DEX aggregation and swap-quote API for EVM chains.\nMaintains a catalogue of blockchains, tokens, DEXes and liquidity\npools, and serves executable swap quotes built from on-chain AMM data.", "title": "uatu API", "contact": {}, "version": "0.1.0" }, "paths": { "/blockchains": { "get": { "description": "Returns every chain the catalogue knows about, each with its embedded\ntoken definitions.", "tags": [ "catalogue" ], "summary": "Get All Blockchains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/server.chainResponse" } } } } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } }, "/blockchains/dex": { "get": { "description": "Returns the seeded DEXes, including the router, factory, quoter and\nsettlement addresses used to price and encode a swap. Filter by chainId,\nby slug, or by both; omit both to list every DEX. A slug identifies a DEX\nonly within one chain, so pass chainId alongside it for a single result.", "tags": [ "catalogue" ], "summary": "Get DEXes", "parameters": [ { "description": "restrict results to this chain ID", "name": "chainId", "in": "query", "schema": { "type": "integer" } }, { "description": "restrict results to this DEX slug, e.g. uniswap", "name": "slug", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.Dex" } } } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } }, "/blockchains/pools": { "get": { "description": "Returns the liquidity pools discovered by the seeder for the given chain,\noptionally filtered to a single DEX. Unlike the token endpoint, chainId\nis required here.", "tags": [ "catalogue" ], "summary": "Get Pools for a Chain", "parameters": [ { "description": "EVM chain ID", "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" } }, { "description": "restrict results to this DEX slug", "name": "dex", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.Pool" } } } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } }, "/blockchains/tokens": { "get": { "description": "Returns the known tokens. Omit chainId to list tokens across every chain.", "tags": [ "catalogue" ], "summary": "Get All Tokens", "parameters": [ { "description": "restrict results to this EVM chain ID", "name": "chainId", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.Token" } } } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } }, "/quotes": { "post": { "description": "Returns the best available DEX route for matching chain IDs, or a bridge route for different chains.\nReturns a saved, pending quote with ordered transaction steps. Submit the steps yourself before the five-minute deadline (Unix seconds).\nInput `amount` uses whole-token units; response amounts use integer strings in each token's smallest units.", "tags": [ "quotes" ], "summary": "Create a swap or bridge quote", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/uatu.QuoteRequest" } } }, "description": "Swap or bridge request", "required": true }, "responses": { "200": { "description": "Saved quote with route and transaction steps", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/uatu.Quote" } } } ] } } } }, "400": { "description": "Invalid request or quote unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "401": { "description": "API key is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } }, "/quotes/routes": { "post": { "description": "Returns the best acceptable quote per DEX, sorted by output amount descending. Both chain IDs must match.\nEstimates are not saved and contain no transaction steps. Use `POST /quotes` to get a fresh executable quote; prices and the selected route may change.\nInput `amount` uses whole-token units; response amounts use integer strings in each token's smallest units.", "tags": [ "quotes" ], "summary": "Compare same-chain DEX quotes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/uatu.QuoteRequest" } } }, "description": "Same-chain swap request", "required": true }, "responses": { "200": { "description": "DEX quotes, best output first", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/server.APIResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.RouteQuote" } } } } ] } } } }, "400": { "description": "Invalid request or no acceptable same-chain quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server.APIResponse" } } } } } } } }, "servers": [ { "url": "https://api.uatu.dev", "description": "Hosted API" }, { "url": "http://localhost:8080", "description": "Self-hosted instance (set PORT in your environment)" } ], "components": { "schemas": { "server.APIResponse": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "integer" }, "data": {}, "message": { "type": "string" } } }, "server.chainResponse": { "type": "object", "properties": { "blockChainLogo": { "type": "string" }, "blockExplorer": { "type": "string" }, "chainId": { "type": "integer" }, "ecosystem": { "type": "string" }, "name": { "type": "string" }, "nativeToken": { "type": "string" }, "rpcUrl": { "type": "string" }, "slug": { "type": "string" }, "symbol": { "type": "string" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.Token" } } } }, "uatu.Actions": { "type": "object", "properties": { "amount": { "type": "string" }, "chainId": { "type": "integer" }, "data": { "type": "string" }, "from": { "type": "string" }, "message": { "type": "string" }, "spender": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" } } }, "uatu.Dex": { "type": "object", "properties": { "name": { "type": "string" }, "permit2Address": { "type": "string" }, "settlementAddress": { "type": "string" }, "slug": { "type": "string" }, "universalRouterAddress": { "type": "string" }, "v2FactoryAddress": { "type": "string" }, "v2RouterAddress": { "type": "string" }, "v3FactoryAddress": { "type": "string" }, "v3QuoterAddress": { "type": "string" }, "v3RouterAddress": { "type": "string" }, "version": { "type": "string" } } }, "uatu.Pool": { "type": "object", "properties": { "baseToken": { "$ref": "#/components/schemas/uatu.Token" }, "baseTokenAddress": { "type": "string" }, "baseTokenBalance": { "type": "string" }, "dexName": { "type": "string" }, "isActivePool": { "type": "boolean" }, "liquidity": { "$ref": "#/components/schemas/uatu.PoolLiquidity" }, "liquidityInUsd": { "$ref": "#/components/schemas/uatu.PoolLiquidityUSD" }, "marketCap": { "type": "string" }, "name": { "type": "string" }, "pairAddress": { "type": "string" }, "poolFee": { "type": "integer" }, "poolType": { "type": "string" }, "quoteToken": { "$ref": "#/components/schemas/uatu.Token" }, "quoteTokenAddress": { "type": "string" }, "quoteTokenBalance": { "type": "string" }, "symbol": { "type": "string" }, "tickSpacing": { "type": "integer" } } }, "uatu.PoolLiquidity": { "type": "object", "properties": { "baseTokenBalance": { "type": "string" }, "quoteTokenBalance": { "type": "string" } } }, "uatu.PoolLiquidityUSD": { "type": "object", "properties": { "baseTokenBalance": { "type": "string" }, "quoteTokenBalance": { "type": "string" }, "totalPoolBalance": { "type": "string" } } }, "uatu.Quote": { "type": "object", "properties": { "amountIn": { "type": "string" }, "amountInFloat": { "type": "string" }, "amountOut": { "type": "string" }, "amountOutFloat": { "type": "string" }, "amountOutMinimum": { "type": "string" }, "createdAt": { "type": "string" }, "deadline": { "type": "integer" }, "destinationChain": { "type": "string" }, "destinationChainId": { "type": "integer" }, "explorerUrl": { "type": "string" }, "hash": { "type": "string" }, "originChain": { "type": "string" }, "originChainId": { "type": "integer" }, "pairAddress": { "type": "string" }, "quoteId": { "type": "string" }, "recipientAddress": { "type": "string" }, "route": { "$ref": "#/components/schemas/uatu.Route" }, "slippageBps": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/uatu.Actions" } }, "tokenIn": { "$ref": "#/components/schemas/uatu.Token" }, "tokenOut": { "$ref": "#/components/schemas/uatu.Token" }, "updatedAt": { "type": "string" }, "walletAddress": { "type": "string" } } }, "uatu.QuoteRequest": { "type": "object", "required": [ "amount", "destinationChainId", "originChainId", "recipientAddress", "tokenIn", "tokenOut" ], "properties": { "amount": { "type": "string", "example": "1.5" }, "destinationChainId": { "type": "integer", "example": 1 }, "originChainId": { "type": "integer", "example": 1 }, "recipientAddress": { "type": "string" }, "slippageBps": { "type": "integer", "example": 50 }, "tokenIn": { "type": "string" }, "tokenOut": { "type": "string" } } }, "uatu.Route": { "type": "object", "properties": { "dex": { "type": "string" }, "fees": { "description": "Fees is the route fee in the input token's smallest unit.", "type": "string" }, "logo": { "type": "string" }, "name": { "type": "string" } } }, "uatu.RouteQuote": { "type": "object", "properties": { "amountIn": { "type": "string" }, "amountOut": { "type": "string" }, "amountOutMinimum": { "type": "string" }, "deadline": { "type": "integer" }, "route": { "$ref": "#/components/schemas/uatu.Route" }, "slippageBps": { "type": "integer" }, "tokenIn": { "$ref": "#/components/schemas/uatu.Token" }, "tokenOut": { "$ref": "#/components/schemas/uatu.Token" } } }, "uatu.Token": { "type": "object", "properties": { "address": { "type": "string" }, "blockchainId": { "type": "integer" }, "decimals": { "type": "integer" }, "logo": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "symbol": { "type": "string" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Organization API key issued from the Uatu console, sent as\n\"Bearer uatu_live_...\". The X-API-Key header carrying the bare\nkey is accepted as an alternative." } } }, "tags": [ { "name": "quotes", "description": "Price a swap and get the calldata needed to execute it." }, { "name": "catalogue", "description": "Discover the chains, tokens, DEXes and pools uatu knows about." } ] }