POST /api/v1/route

Get a quote for a same-chain swap. This endpoint returns the expected output amount, routing details, and gasless eligibility — but does not execute anything.

Request

POST https://orkidlabs.xyz/api/v1/route
Content-Type: application/json
X-ORKID-API-Key: <key>

{
  "from": "USDC",
  "to": "WETH",
  "amount": "25.0",
  "chain": "base",
  "fromAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "fromDecimals": 6,
  "toAddress": "0x4200000000000000000000000000000000000006",
  "toDecimals": 18
}

Parameters

Field	Type	Required	Description
`from`	string	Yes	Input token symbol (e.g. `USDC`) or address
`to`	string	Yes	Output token symbol (e.g. `WETH`) or address
`amount`	string	Yes	Input amount in human-readable units (e.g. `"25.0"`)
`chain`	string	Yes	`base`, `ethereum`, `arbitrum`, or `polygon`
`fromAddress`	string	Recommended	Input token contract address
`fromDecimals`	number	Recommended	Input token decimals
`toAddress`	string	Recommended	Output token contract address
`toDecimals`	number	Recommended	Output token decimals

Explicit *_address + *_decimals is recommended because symbol resolution is server-side and may not cover every token.

Response

{
  "ok": true,
  "quote": {
    "amountIn": "25.000000",
    "amountOut": "0.010184",
    "amountOutRaw": "10183963710975259",
    "volumeUsd": 25,
    "rate": "0.000407 WETH/USDC",
    "protocol": "aerodrome_slipstreams",
    "poolAddress": "0xc758d81b9b81a6fcdad075bd471874a2c46b54e0",
    "priceImpactBps": 9.66
  },
  "gaslessEligible": true,
  "computeMs": 142
}

Fields

Field	Type	Description
`ok`	boolean	`true` on success
`quote.amountIn`	string	Input amount
`quote.amountOut`	string	Expected output amount (human-readable)
`quote.amountOutRaw`	string	Expected output amount (raw integer)
`quote.volumeUsd`	number	USD value of the swap
`quote.rate`	string	Exchange rate
`quote.protocol`	string	DEX protocol used for routing
`quote.poolAddress`	string	Primary pool address
`quote.priceImpactBps`	number	Price impact in basis points
`gaslessEligible`	boolean	Whether the solver can subsidize gas
`computeMs`	number	Server-side compute time

Error response

{
  "ok": false,
  "error": "Swap too small for gasless execution: $5.00 below $20 minimum on base.",
  "gaslessEligible": false,
  "computeMs": 45
}

Common errors:

Error	Cause
`Swap too small...`	Below gasless minimum for the chain
`Price impact too high: X bps...`	Slippage exceeds 500 bps max — try a smaller amount
`Invalid or revoked API key`	Bad/missing key or rate limit hit

See Error & retry guide for the full list.