Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Quote

Live rates across CEX, DEX and private routes (GET /v1/quote)

Get swap quote

get
/v1/quote

Returns live quotes for a token pair and amount.

Response shape

  • bestQuote — array with one item (the winner) or [] when nothing is available.

  • allQuotes — remaining quotes. When sort is not fastest, private v1/v2 winners that were not the global best are placed first; the rest stay in source order after ranking.

type (engine filter) — comma-separated, case-insensitive. Default cex.

  • cex — CEX / off-chain providers (getRatesForPairWorkflow on the CEX queue)

  • dex — DEX aggregators (started only when the DEX task queue is configured)

  • private — two-rail private routes (getPrivateQuoteWorkflow; intermediary token is not disclosed)

  • all — CEX + DEX + private

  • combinations such as cex,dex or cex,dex,private

Ranking (sort)

  • best (default) — highest rate; bestQuote[0].label is "best price"

  • fastest — lowest parsed estimatedTime; label is "fastest"

  • noKyc — CEX/DEX quotes with kycLevel === 0 only, then ranked by rate. Aliases: nokyc, no-kyc, no_kyc

Other filters

  • xmrOnly=true — keep only private version=v1 (XMR hop). Ignored when type does not include private.

  • excludeProviders — comma-separated slugs; CEX/DEX will not request those providers.

  • slippage — percent 0.1–1, default 0.5 when omitted (applied on the server before workflows).

  • addressFrom / addressTo — forwarded to CEX/DEX quote workflows for providers that need them.

Each quote gets a fresh rateId (UUID) stored in Redis for 5 minutes. Pass it as rateId on POST /v1/swap. The HTTP response itself is cached for 30 seconds; rateId values are still regenerated on every call.

Unknown tickers/networks → 404 COIN_NOT_FOUND. No successful quotes after filtering → 404 NO_QUOTES_AVAILABLE. If every source times out with no quotes, the handler returns { bestQuote: [], allQuotes: [] } (200) instead of 408.

Query parameters
tickerFromstringRequired

Source token ticker

Example: ETH
networkFromstringRequired

Source chain id — must match /v1/chains[].id (canonical slug, case-insensitive). Required.

Example: ETH
tickerTostringRequired

Target token ticker

Example: BTC
networkTostringRequired

Target chain id — must match /v1/chains[].id (canonical slug, case-insensitive). Required.

Example: BTC
amountnumber · min: 1e-8Required

Amount to exchange in source token units. Minimum 0.00000001.

Example: 1.5
typestringOptional

Engine filter. Default cex. Values: cex, dex, private, all, or comma-separated combinations (cex,dex). Case-insensitive.

Example: cex,dex
slippagenumberOptional

Slippage tolerance in percent. Range 0.1–1. Default 0.5.

Default: 0.5Example: 0.5
addressFromstringOptional

Sender wallet address for providers that require it in quote requests.

Example: 0x0000000000000000000000000000000000000000
addressTostringOptional

Recipient wallet address for providers that require it in quote requests.

Example: 0x0000000000000000000000000000000000000000
xmrOnlybooleanOptional

If true, only private v1 (XMR hop) quotes are returned. Ignored when type does not include private.

Default: falseExample: false
sortstring · enumOptional

Quote ranking: best (highest rate), fastest (lowest estimated time), noKyc (kycLevel 0 only, then by rate). Default best.

Default: bestExample: bestPossible values:
excludeProvidersstring[]Optional

Comma-separated provider slugs to skip. CEX/DEX will not request rates from these providers.

Responses
200

Best quote (0–1 items) and remaining provider quotes. Empty arrays when no source returned a quote (including global timeout).

application/json
get/v1/quote
GET /v1/quote?tickerFrom=ETH&networkFrom=ETH&tickerTo=BTC&networkTo=BTC&amount=1.5 HTTP/1.1
Host: api.yifi.io
Accept: */*

{
  "bestQuote": [
    {
      "rateId": "4f2e6d6b-6e15-4f47-8b6e-2a3d3c5b9d10",
      "engine": "off-chain",
      "provider": "providerX",
      "exchangerName": "providerX",
      "logoUrl": "https://cdn.yifi.io/providers/providerX.svg",
      "rate": "33.41404667",
      "estimatedOutput": "50.12107000",
      "inUsdValue": 1850.25,
      "inUsdRateError": "Can't fetch USD-rate",
      "outUsdValue": 1798.1,
      "outUsdDeviationPercent": -2.8162,
      "fromTokenUsdtRate": 1850.25,
      "toTokenUsdtRate": 1,
      "rateReversed": 0.02992748,
      "quoteId": "7c6b2112-d7f7-47ba-992f-8a7f098a6611",
      "gasEstimated": "0.003",
      "protocolFee": null,
      "providerFee": null,
      "slippageTolerance": "0.5",
      "estimatedTime": "~30s",
      "kycLevel": 0,
      "kycLevelName": "No KYC",
      "legal": [
        {
          "docName": "Terms of Use",
          "docLink": "https://example.com/terms"
        }
      ],
      "label": "best price",
      "dataForSign": {},
      "schemeSign": "eip712",
      "version": "v1",
      "routeKind": "two_leg"
    }
  ],
  "allQuotes": [
    {
      "rateId": "4f2e6d6b-6e15-4f47-8b6e-2a3d3c5b9d10",
      "engine": "off-chain",
      "provider": "providerX",
      "exchangerName": "providerX",
      "logoUrl": "https://cdn.yifi.io/providers/providerX.svg",
      "rate": "33.41404667",
      "estimatedOutput": "50.12107000",
      "inUsdValue": 1850.25,
      "inUsdRateError": "Can't fetch USD-rate",
      "outUsdValue": 1798.1,
      "outUsdDeviationPercent": -2.8162,
      "fromTokenUsdtRate": 1850.25,
      "toTokenUsdtRate": 1,
      "rateReversed": 0.02992748,
      "quoteId": "7c6b2112-d7f7-47ba-992f-8a7f098a6611",
      "gasEstimated": "0.003",
      "protocolFee": null,
      "providerFee": null,
      "slippageTolerance": "0.5",
      "estimatedTime": "~30s",
      "kycLevel": 0,
      "kycLevelName": "No KYC",
      "legal": [
        {
          "docName": "Terms of Use",
          "docLink": "https://example.com/terms"
        }
      ],
      "label": "best price",
      "dataForSign": {},
      "schemeSign": "eip712",
      "version": "v1",
      "routeKind": "two_leg"
    }
  ]
}
PreviousPairs
NextSwap

Last updated

Was this helpful?