Smart-router

Smart Router is the AMM routing engine, pool graph, and token catalog at https://api.agentswap.co.

It is not MAS. It returns one smart-router route and catalog data. MAS calls smart-router as one of its quote sources, while callers can use smart-router directly for the token catalog. Quote requests that need source comparison go to MAS.

Service split

Need	Host	Meaning
Quote comparison	`https://meta-api.agentswap.co`	MAS compares multiple sources.
Token catalog	`https://api.agentswap.co`	smart-router returns the catalog.
Smart-router as a quote source	internal MAS call to `api.agentswap.co`	One source inside a MAS response.

Do not send quote traffic to smart-router when the caller needs MAS’s source comparison. Do not ask MAS for the token catalog.

Base URL

https://api.agentswap.co

Public HTTP contract

Health and catalog reads are available without a quote key. Quote routes are caller-facing but require X-API-Key: <key> and are subject to the quote scope, rate limit, and quota checks.

`GET /health`

The response is a large status object. Its stable top-level shape is:

{
  "status": "ok | degraded | error",
  "version": "service version",
  "uptime_secs": 0,
  "checks": {
    "sync_fresh": true,
    "v2_populated": true,
    "v3_populated": true,
    "graph_ready": true,
    "quotes_available": true,
    "v3_memory_ok": true
  },
  "bootstrap": {},
  "pools": {},
  "sync": {},
  "memory": {},
  "quotes": {},
  "graphs": [],
  "knowledge": {},
  "grades": [],
  "system": {},
  "router_selfcheck": {},
  "runtime": {}
}

degraded is a serving state. A caller should inspect both the overall status and the subsystem checks. error means the service’s graph, pool, or self-check conditions do not support normal routing. Values such as counts, blocks, memory, and uptime are observations, not constants.

Catalog reads

Endpoint	Request	Response shape
`GET /api/chains`	No body	Array of `{chain_id, name, dex_count, dexes[], pool_count, executor?}`
`GET /api/tokens`	No body	Object keyed by token address; value `{chain_id, symbol, decimals}`
`GET /api/token-list`	Optional `?chain_id=<chain id>`	Array of `{chain_id, address, symbol?, decimals?, verified}`

Use /api/chains and the optional catalog filter at runtime. Chain coverage is per deployment and is not stated on this page.

`POST /quote`

Send the JSON body with the API key:

{
  "chain_id": 8453,
  "token_in": "0xEvmTokenIn",
  "token_out": "0xEvmTokenOut",
  "amount_in": "decimal raw amount",
  "slippage_bps": 50,
  "taker": "0xEvmTaker",
  "allow_partial": false,
  "verify": false,
  "executable_only": true,
  "routing_mode": "deep"
}

routing_mode accepts the service’s supported mode strings. v4_hooks and order_context are additional request fields; use them only when the deployment and caller path require them.

The response is one QuoteResponse:

{
  "dex": "AMM or route label",
  "output": "decimal raw amount",
  "amount_out": "decimal raw amount",
  "amount_out_min": "decimal raw amount",
  "gas_estimate": "decimal gas estimate",
  "source": "local | path_hint | rpc",
  "router": "0xRouter or null",
  "calldata": "0x... or null",
  "execution": {
    "spender": "0xAllowanceTarget",
    "target": "0xTransactionTarget",
    "calldata": "0x...",
    "value": "0x0 or other hex quantity"
  },
  "steps": [],
  "route_readiness": "readiness state",
  "route_executable": true,
  "route_unexecutable_reason": null
}

Other response fields include route path, pool and tax observations, asset classes, sync observations, and optional verification results. Treat the explicit execution object as the wallet call payload only when route_executable is true.

`GET /quote_exact_output`

This route uses query parameters and the same API key:

/quote_exact_output?chain_id=<id>&token_in=<address>&token_out=<address>&target_output=<raw amount>&max_input=<raw amount>&slippage_bps=<bps>&executable_only=true&verify=false

Required parameters are chain_id, token_in, token_out, target_output, and max_input. slippage_bps, executable_only, and verify are optional. The response has the QuoteResponse shape plus input_consumed. If the target cannot be reached within max_input, the endpoint can return HTTP 200 with route_executable: false and route_unexecutable_reason: "target_unreachable".

Caller states

ok, degraded, and error are health states, not quote amounts. degraded can still serve a quote when checks.quotes_available is true.
Catalog responses are runtime deployment data. Do not hard-code a chain list from one response.
For a quote, check route_executable and route_unexecutable_reason. A quote amount without an executable payload is not a wallet transaction.
Handle HTTP 400 for invalid input, 401 for a missing or invalid key, 403 for a disabled key or missing scope, 402 for exhausted quota, 404 for no route, 429 for rate limiting, and 5xx service failures. JSON API errors have error, message, and status fields when returned by the structured error handler.
Exact-output is a separate query path and consumes a weighted quote request; budget for the response and quota behavior accordingly.