Docs/API Endpoints

On this page

Get a quote

Price from_amount of from into to across the available venues. Use the returned id as quote_id when creating an order, before the quote’s expires_at.

Set format to formatted (the default) for decimal amounts and asset names such as bitcoin.btc, or raw for base-unit amounts and canonical asset identifiers. See the token list for registered asset names.

Choose optimal quoting for up to 10 seconds per venue, or fast for a 1.5-second cutoff. Set return_full_route to include the route, and include_candidates for debugging details. Use either venue_allowlist or venue_blocklist to control which venues are considered.

POST/quoteOpenAPI ↗

Try it out

Production

Request example

const response = await fetch("https://api.rift.trade/quote", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    format: "formatted",
    from: "bitcoin.btc",
    from_amount: "0.01",
    return_full_route: true,
    to: "ethereum.usdc",
  }),
});

const data = await response.json();
console.log(data);

Parameters

header parameter

x-api-keystring

Your API key. Quotes made with it are attributed to your integrator id and held to its rate. Without it the quote is anonymous.

Body parameters

application/json

formatstring

How amounts and asset names are written in this request and in the response. formatted writes amounts as decimals in the asset's own units and assets as <chain name>.<symbol>; raw writes amounts as base-unit integers and assets in canonical form, evm:<chain id>.<address> on EVM chains. Defaults to formatted. Key on assets with raw: symbols are presentation and may be reassigned.

Allowed: "raw""formatted"

Default: "formatted"

fromstringrequired

Asset to sell, as <chain>.<asset>. The chain is a name (ethereum, base, arbitrum, robinhood, ink, bitcoin, hyperliquid) or evm:<chain id>. The asset is a symbol, a contract address, or eth and btc for the native coin. Case does not matter.

from_amountstringrequired

Amount of from to sell. A decimal in the asset's own units when format is formatted, an integer in base units when raw.

include_candidatesboolean

Include every venue and route that was considered under quote_candidates. Large, meant for debugging.

Default: false

integrator_idstring | null

Deprecated and ignored. Quotes are attributed to the integrator that owns the API key sent in the x-api-key header. Still accepted so existing requests keep working.

Show child attributes

Any of: string 1

string

Any of: null 2

null

quote_modestring

optimal gives every venue up to 10 seconds to answer, fast cuts each one off at 1.5 seconds. Defaults to optimal.

Allowed: "fast""optimal"

Default: "optimal"

return_full_routebooleanrequired

Include the hop-by-hop route in the response.

tostringrequired

Asset to receive, in the same form as from.

venue_allowliststring[]

Quote only these venues. Empty means every venue. Cannot be combined with venue_blocklist.

Default: []

Show child attributes

string · "aave", "across", "cctp", "chainflip", "cowswap", "flytrade", "hyperliquid", "kyberswap", "lifi", "mayan", "morpho", "near_intents", "nordstern", "okx", "relay", "transit", "unit", "velora"

venue_blockliststring[]

Never quote these venues. Cannot be combined with venue_allowlist.

Default: []

Show child attributes

string · "aave", "across", "cctp", "chainflip", "cowswap", "flytrade", "hyperliquid", "kyberswap", "lifi", "mayan", "morpho", "near_intents", "nordstern", "okx", "relay", "transit", "unit", "velora"

Responses

Response status

The best executable quote

application/json

Example response

{
  "format": "raw",
  "delivery": {
    "amount_in": "",
    "amount_out": "",
    "execution_cost": ""
  },
  "estimated_amount_out": "",
  "expires_at": "2026-09-23T12:00:00Z",
  "from": "",
  "from_amount": "",
  "id": "00000000-0000-4000-8000-000000000001",
  "to": "",
  "venue_allowlist": [],
  "venue_blocklist": []
}

formatstringrequired

The format every amount and asset name in this response is written in.

Allowed: "raw""formatted"

deliveryobjectrequired

The final transfer into to_address and what it costs.

Show child attributes

amount_instringrequired

Amount of to handed to delivery: the last step's step_amount_out.

amount_outstringrequired

Amount that arrives at to_address. This is estimated_amount_out.

execution_coststringrequired

Cost of the transfer into to_address, paid out of amount_in.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost.

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

fromstringrequired

Asset sold, written per format.

from_amountstringrequired

The amount quoted, echoed in format.

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

integrator_idstring | null

The integrator id of the API key the quote was made with, or null when it was made without one.

Show child attributes

Any of: string 1

string

Any of: null 2

null

quote_candidatesobject | null

Every venue and route considered, with timings and failures. Present only when include_candidates was set.

Show child attributes

Any of: object 1

Everything the quoter considered, for debugging. Direct venues under single_hop, multi-venue routes under multi_hop.

multi_hopobjectrequired

The graph search over intermediate assets and its outcome.

Show child attributes

attemptsobject[]required

Every venue quote requested while walking the paths.

Show child attributes

amount_instringrequired

Amount the hop was priced for.

elapsed_msintegerrequired

Milliseconds until the venue answered or was cut off.

uint64 · min: 0

fromstringrequired

Asset entering the hop, written per format.

roundintegerrequired

Position of the hop in the route, counted from zero.

uint · min: 0

tostringrequired

Asset leaving the hop, written per format.

venuestringrequired

The venue asked.

Allowed: "aave""across""across_swap""cctp_fast""cctp_hyperliquid_fast""cctp_hyperliquid_standard""cctp_standard""chainflip""cowswap""flytrade""hyperliquid_spot""kyberswap""lifi_fast""lifi_standard""mayan""mayan_swap""morpho""nordstern""near_intents""okx""relay""transit""unit""velora"

One of: quoted

The venue answered; step is the costed hop.

statusstringrequired

Value: "quoted"

stepobjectrequired

One venue leg of the route.

Show child attributes

executionobjectrequired

How the step runs: on Bitcoin, on an EVM chain with vault-funded gas, on an EVM chain with router-funded gas, or on HyperCore.

Show child attributes

One of: bitcoin

Runs on Bitcoin.

See the OpenAPI specification for the complete schema.

One of: evm

Runs on an EVM chain with gas paid by the vault.

See the OpenAPI specification for the complete schema.

One of: evm_gas_desk

Runs on an EVM chain with gas advanced by the router.

See the OpenAPI specification for the complete schema.

One of: hyperliquid

Runs on HyperCore.

See the OpenAPI specification for the complete schema.

fromstringrequired

Asset entering the step, written per format.

step_amount_instringrequired

Amount entering the step: from_amount for the first step, the previous step's step_amount_out after that.

step_amount_outstringrequired

Amount leaving the step, handed to the next step or to delivery.

tostringrequired

Asset leaving the step, written per format.

venuestringrequired

Venue that executes this step.

venue_amount_instringrequired

Amount sent to the venue: step_amount_in less this step's execution cost.

venue_amount_outstringrequired

The venue's output for venue_amount_in.

One of: failed

The venue refused or errored.

errorstringrequired

statusstringrequired

Value: "failed"

One of: timed_out

The venue did not answer within the deadline.

statusstringrequired

Value: "timed_out"

completebooleanrequired

Whether every path was enumerated, false when the search hit its limit.

hopsinteger | null

Number of venue steps in the routes tried, the fewest with a path. Null when no path exists.

uint · min: 0

pathsintegerrequired

Number of candidate paths found at that hop count.

uint · min: 0

routesobject[]required

Each complete path and whether it produced a quote.

Show child attributes

assetsstring[]required

The assets along the path, from from to to, written per format.

Show child attributes

string

bestbooleanrequired

Whether this route is the quote that was returned.

venuesstring[]required

The venue of each hop, in order.

Show child attributes

string · "aave", "across", "across_swap", "cctp_fast", "cctp_hyperliquid_fast", "cctp_hyperliquid_standard", "cctp_standard", "chainflip", "cowswap", "flytrade", "hyperliquid_spot", "kyberswap", "lifi_fast", "lifi_standard", "mayan", "mayan_swap", "morpho", "nordstern", "near_intents", "okx", "relay", "transit", "unit", "velora"

One of: quoted

Every hop quoted; quote is the costed route.

quoteobjectrequired

The priced route shared by the quote response and every candidate.

Show child attributes

deliveryobjectrequired

The final transfer into to_address and what it costs.

Show child attributes

amount_instringrequired

Amount of to handed to delivery: the last step's step_amount_out.

amount_outstringrequired

Amount that arrives at to_address. This is estimated_amount_out.

execution_coststringrequired

Cost of the transfer into to_address, paid out of amount_in.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost.

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

fromstringrequired

Asset sold, written per format.

from_amountstringrequired

The amount quoted, echoed in format.

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

routeobject[] | null

The venue steps in execution order. Present only when return_full_route was set.

Show child attributes

See the OpenAPI specification for the complete schema.

tostringrequired

Asset received, written per format.

venue_allowliststring[]required

Venues quoting was restricted to; empty when it was not.

Show child attributes

See the OpenAPI specification for the complete schema.

venue_blockliststring[]required

Venues excluded from quoting; empty when none were.

Show child attributes

See the OpenAPI specification for the complete schema.

statusstringrequired

Value: "quoted"

One of: failed

A hop failed; error is what stopped the route.

errorstringrequired

statusstringrequired

Value: "failed"

setup_errorstring | null

Why the search could not start, when execution costs could not be priced, in the same words as single_hop.setup_error.

single_hopobjectrequired

The venues able to quote the pair directly and what each answered.

Show child attributes

candidatesobject[]required

One entry per venue able to quote the pair directly.

Show child attributes

bestbooleanrequired

Whether this candidate is the quote that was returned.

elapsed_msintegerrequired

Milliseconds until the venue answered or was cut off.

uint64 · min: 0

venuestringrequired

The venue able to quote the pair directly.

One of: quoted

The venue answered; quote is the costed result and costing_audit the raw answer it was derived from.

costing_auditobjectrequired

The venue's raw answer before execution costs were applied.

Show child attributes

observed_amount_instringrequired

Amount the venue was asked to price.

observed_amount_outstringrequired

Amount the venue said it would return for it.

venuestringrequired

The venue that answered.

quoteobjectrequired

The priced route shared by the quote response and every candidate.

Show child attributes

deliveryobjectrequired

The final transfer into to_address and what it costs.

Show child attributes

amount_instringrequired

Amount of to handed to delivery: the last step's step_amount_out.

amount_outstringrequired

Amount that arrives at to_address. This is estimated_amount_out.

execution_coststringrequired

Cost of the transfer into to_address, paid out of amount_in.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost.

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

fromstringrequired

Asset sold, written per format.

from_amountstringrequired

The amount quoted, echoed in format.

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

routeobject[] | null

The venue steps in execution order. Present only when return_full_route was set.

Show child attributes

See the OpenAPI specification for the complete schema.

tostringrequired

Asset received, written per format.

venue_allowliststring[]required

Venues quoting was restricted to; empty when it was not.

Show child attributes

See the OpenAPI specification for the complete schema.

venue_blockliststring[]required

Venues excluded from quoting; empty when none were.

Show child attributes

See the OpenAPI specification for the complete schema.

statusstringrequired

Value: "quoted"

One of: failed

The venue refused or errored.

errorstringrequired

statusstringrequired

Value: "failed"

One of: timed_out

The venue did not answer within the quote_mode deadline.

statusstringrequired

Value: "timed_out"

One of: not_asked

The venue was never asked because execution costs could not be priced; single_hop.setup_error says why.

statusstringrequired

Value: "not_asked"

setup_errorstring | null

Why no direct venue was asked, when execution costs could not be priced: pricing timed out, pricing unavailable for <asset> (a temporary outage) or no price available for <asset> (the asset has no price).

Any of: null 2

null

routeobject[] | null

The venue steps in execution order. Present only when return_full_route was set.

Show child attributes

executionobjectrequired

How the step runs: on Bitcoin, on an EVM chain with vault-funded gas, on an EVM chain with router-funded gas, or on HyperCore.

Show child attributes

One of: bitcoin

Runs on Bitcoin.

modestringrequired

Value: "bitcoin"

One of: evm

Runs on an EVM chain with gas paid by the vault.

chainintegerrequired

EVM chain id.

int32

modestringrequired

Value: "evm"

One of: evm_gas_desk

Runs on an EVM chain with gas advanced by the router.

chainintegerrequired

EVM chain id.

int32

modestringrequired

Value: "evm_gas_desk"

One of: hyperliquid

Runs on HyperCore.

modestringrequired

Value: "hyperliquid"

fromstringrequired

Asset entering the step, written per format.

step_amount_instringrequired

Amount entering the step: from_amount for the first step, the previous step's step_amount_out after that.

step_amount_outstringrequired

Amount leaving the step, handed to the next step or to delivery.

tostringrequired

Asset leaving the step, written per format.

venuestringrequired

Venue that executes this step.

venue_amount_instringrequired

Amount sent to the venue: step_amount_in less this step's execution cost.

venue_amount_outstringrequired

The venue's output for venue_amount_in.

tostringrequired

Asset received, written per format.

venue_allowliststring[]required

Venues quoting was restricted to; empty when it was not.

Show child attributes

string · "aave", "across", "cctp", "chainflip", "cowswap", "flytrade", "hyperliquid", "kyberswap", "lifi", "mayan", "morpho", "near_intents", "nordstern", "okx", "relay", "transit", "unit", "velora"

venue_blockliststring[]required

Venues excluded from quoting; empty when none were.

Show child attributes

string · "aave", "across", "cctp", "chainflip", "cowswap", "flytrade", "hyperliquid", "kyberswap", "lifi", "mayan", "morpho", "near_intents", "nordstern", "okx", "relay", "transit", "unit", "velora"