Soheil.fi
Soheil RouterDocs
DevelopersOpenAPI
API reference

Get a quote

The best price for a swap, with the transaction that makes it. Also POST /v1/quote with the same fields as JSON.

MarkdownAll docs for AI (llms-full.txt)
GET/v1/quoteAPI key

Request

curl
curl "https://api.soheil.fi/v1/quote?fromChainId=8453&toChainId=8453\
&fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\
&toToken=0x0000000000000000000000000000000000000000\
&fromAmount=100000000&fromAddress=0xYourUser&slippageBps=50" \
  -H "x-api-key: sk_xxxxxxxx_…"

Fields

fromChainIdintegerrequired
Chain ID where the user sends from.
toChainIdintegerrequired
Chain ID where the recipient receives: the same as fromChainId until bridges come.
fromTokenaddressrequired
Token sold (the coin is 0x000…0).
toTokenaddressrequired
Token bought.
fromAmountstringrequired
Amount sold, in the token's smallest unit, above 0.
fromAddressaddressrequired
The wallet that signs and pays.
toAddressaddress
Who receives the output, on toChainId; fromAddress by default. Never a token or our contract.
slippageBpsinteger
1 to 5000; 50 (0.5%) by default.
integratorBpsinteger
Your fee for this request, 0 up to your key's ceiling; your key's default when left out.

Response

200 OK
{
  "id": "0x9f2c…",                     // the trade's request id (bytes32 in the call and in the Traded event)
  "type": "swap",                      // "swap" on one network; "bridge" when bridges come
  "fromChainId": 8453, "toChainId": 8453,
  "fromToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "toToken": "0x0000000000000000000000000000000000000000",
  "fromAmount": "100000000",
  "toAmount": "41287340000000000",     // expected output, both fees already taken from the input
  "toAmountMin": "41080903300000000",  // the least the recipient gets: the transaction reverts below it
  "fees": { "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "totalBps": 30, "routerBps": 10, "integratorBps": 20,
            "routerFee": "100000", "integratorFee": "200000" },
  "approvalAddress": "0x…",            // our contract: approve exactly fromAmount first (null for the coin)
  "transactionRequest": { "to": "0x…", "data": "0x4c5d1e10…", "value": "0x0", "chainId": 8453 },
  "gasEstimate": "270000",
  "validUntil": 1793710800,            // unix seconds: send before it, or quote again
  "estimatedDurationSeconds": 0        // from mined to received: 0 for a swap (the same transaction)
}

Reading the answer

  • toAmount is what the user should receive, with both fees already taken.
  • toAmountMin is the least they will receive, enforced by the contract.
  • fees are taken from fromAmount, in fees.token.
  • gasEstimate includes the contract's own work.
  • validUntil (about 20 minutes ahead) is how long the price is fresh, not an on-chain deadline: send before it, or quote again. Sent later, the trade may revert (the user keeps their tokens) or fill at a worse price, never below toAmountMin.