Docs/API Endpoints

On this page

Get a quote

Price amount_in 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 include_candidates for debugging details. Use either venue_allowlist or venue_blocklist to control which venues are considered.

To charge your own fee on the trade, set integrator_fee_bps and integrator_fee_recipient. See integrator fees.

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",
    to: "ethereum.usdc",
    amount_in: "0.01",
  }),
});

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

Parameters

Required parameters

fromstring

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.

tostring

Asset to receive, in the same form as from.

amount_instring

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

Optional parameters

x-api-keystringheader

Your API key. Quotes made with it are attributed to your integrator id, whatever integrator_id the request sends, and held to its rate.

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"

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", "euler", "flytrade", "hyperliquid", "kyberswap", "lifi", "mayan", "metric", "morpho", "near_intents", "nordstern", "okx", "relay", "rift_otc", "transit", "tydro", "ultrayield", "uniswap", "unit", "velora", "weth_contract", "xstocks"

venue_blockliststring[]

Never quote these venues. Cannot be combined with venue_allowlist.

Default: []

Show child attributes

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"

include_candidatesboolean

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

Default: false

integrator_idstring | null

Identifies the integrator sending the request, for attribution. Optional; 1 to 64 characters of letters, digits, ., _ and -. Echoed in the quote and carried onto the order created from it. When x-api-key is set, the key's integrator takes its place.

Default: null

Show child attributes

Any of: string 1

string

Any of: null 2

null

integrator_fee_bpsinteger | null

Share of the output paid to integrator_fee_recipient, in basis points from 1 (0.01%) to 1000 (10%). Set together with integrator_fee_recipient, or not at all.

Default: null

Show child attributes

Any of: integer 1

integer

Any of: null 2

null

integrator_fee_recipientstring | null

Address on the to chain that receives the integrator fee. Set together with integrator_fee_bps, or not at all.

Default: null

Show child attributes

Any of: string 1

string

Any of: null 2

null

Responses

Response status

The best executable quote

application/json

Example response

{
  "id": "019a3c7e-5b1a-7c3e-9a51-6f3d2b8e4a10",
  "from": "bitcoin.btc",
  "to": "ethereum.usdc",
  "amount_in": "0.01",
  "estimated_amount_out": "997.130102",
  "estimated_execution_cost": "1.38421",
  "route": [
    {
      "type": "venue",
      "venue": "chainflip",
      "execution": {
        "mode": "bitcoin"
      },
      "from": "bitcoin.btc",
      "to": "ethereum.usdc",
      "amount_in": "0.01",
      "amount_out": "998.514312"
    },
    {
      "type": "delivery",
      "amount_in": "998.514312",
      "execution_cost": "1.38421",
      "integrator_fee": "0",
      "amount_out": "997.130102"
    }
  ],
  "expires_at": "2026-10-31T19:10:00Z",
  "venue_allowlist": [],
  "venue_blocklist": [],
  "integrator_fee_bps": null,
  "integrator_fee_recipient": null,
  "format": "formatted",
  "integrator_id": null
}

formatstringrequired

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

Allowed: "raw""formatted"

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

fromstringrequired

Asset sold, written per format.

tostringrequired

Asset received, written per format.

amount_instringrequired

The amount quoted, echoed in format.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost and the integrator fee: the amount_out of the route's delivery step.

estimated_execution_coststringrequired

The network fees the router pays to execute the order, in to.

routeobject[]required

The route in execution order: a venue step for each venue leg, then the delivery step into to_address.

Show child attributes

One of: venue

A venue leg.

venuestringrequired

Venue that executes this step.

Allowed: "aave""across""across_swap""cctp_fast""cctp_hyperliquid_fast""cctp_hyperliquid_standard""cctp_standard""chainflip""cowswap""euler""flytrade""hyperliquid_spot""kyberswap""lifi_fast""lifi_standard""mayan""mayan_swap""metric""morpho""nordstern""near_intents""okx""relay""rift_otc""transit""tydro""ultrayield_deposit""ultrayield_withdrawal""uniswap""unit""velora""weth_contract""xstocks"

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.

chainintegerrequired

EVM chain id.

int32

modestringrequired

Value: "evm"

One of: hyperliquid

Runs on HyperCore.

modestringrequired

Value: "hyperliquid"

fromstringrequired

Asset entering the step, written per format.

tostringrequired

Asset leaving the step, written per format.

amount_instringrequired

Amount of from entering the step: the quote's amount_in for the first step, the previous step's amount_out after that. A step on Bitcoin or HyperCore pays its chain's own fee out of it (the Bitcoin miner fee, the HyperCore account activation) before the venue trades the rest, so its rate includes that fee.

amount_outstringrequired

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

typestringrequired

Value: "venue"

One of: delivery

The transfer of the route's output into to_address. Always the last step.

amount_instringrequired

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

execution_coststringrequired

The network fees the router pays to execute the order, in to.

integrator_feestringrequired

Amount of to paid to integrator_fee_recipient: integrator_fee_bps of amount_in less execution_cost, rounded down. Zero without a fee, and when the recipient cannot receive it: below a Bitcoin output's dust floor, or a HyperCore address with no account.

amount_outstringrequired

Amount that arrives at to_address. This is estimated_amount_out.

typestringrequired

Value: "delivery"

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

venue_allowliststring[]required

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

Show child attributes

venue_blockliststring[]required

Venues excluded from quoting; empty when none were.

Show child attributes

integrator_fee_bpsinteger | null

The integrator_fee_bps the quote was asked with, or null.

Show child attributes

Any of: integer 1

integer

Any of: null 2

null

integrator_fee_recipientstring | null

The integrator_fee_recipient the quote was asked with, or null.

Show child attributes

Any of: string 1

string

Any of: null 2

null

integrator_idstring | null

The integrator the quote is attributed to: the API key's when x-api-key was set, otherwise the request's integrator_id, or null.

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.

single_hopobjectrequired

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

Show child attributes

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).

candidatesobject[]required

One entry per venue able to quote the pair directly.

Show child attributes

venuestringrequired

The venue able to quote the pair directly.

elapsed_msintegerrequired

Milliseconds until the venue answered or was cut off.

uint64 · min: 0

bestbooleanrequired

Whether this candidate is the quote that was returned.

One of: quoted

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

quoteobjectrequired

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

Show child attributes

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

fromstringrequired

Asset sold, written per format.

tostringrequired

Asset received, written per format.

amount_instringrequired

The amount quoted, echoed in format.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost and the integrator fee: the amount_out of the route's delivery step.

estimated_execution_coststringrequired

The network fees the router pays to execute the order, in to.

routeobject[]required

The route in execution order: a venue step for each venue leg, then the delivery step into to_address.

Show child attributes

See the OpenAPI specification for the complete schema.

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

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.

integrator_fee_bpsinteger | null

The integrator_fee_bps the quote was asked with, or null.

Show child attributes

Any of: integer 1

See the OpenAPI specification for the complete schema.

Any of: null 2

See the OpenAPI specification for the complete schema.

integrator_fee_recipientstring | null

The integrator_fee_recipient the quote was asked with, or null.

Show child attributes

Any of: string 1

See the OpenAPI specification for the complete schema.

Any of: null 2

See the OpenAPI specification for the complete schema.

costing_auditobjectrequired

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

Show child attributes

venuestringrequired

The venue that answered.

observed_amount_instringrequired

Amount the venue was asked to price.

observed_amount_outstringrequired

Amount the venue said it would return for it.

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"

multi_hopobjectrequired

The graph search over intermediate assets and its outcome.

Show child attributes

hopsinteger | null

Fewest venue steps of any path. Null when no path exists.

uint · min: 0

pathsintegerrequired

Number of candidate paths found, up to the hop limit.

uint · min: 0

completebooleanrequired

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

setup_errorstring | null

Why execution costs could not be priced, when that left no route quoted, in the same words as single_hop.setup_error.

rankobject | null

How the paths were ranked before the best of them were quoted live. Absent when no path exists or execution costs could not be priced.

Show child attributes

Any of: object 1

The estimates the paths were ranked by.

elapsed_msintegerrequired

Milliseconds the ranking took.

uint64 · min: 0

edgesobject[]required

Every step any path takes, estimated once at the quote's value in the step's input asset.

Show child attributes

fromstringrequired

Asset entering the step, written per format.

tostringrequired

Asset leaving the step, written per format.

amount_instring | null

The amount the step was estimated for. Absent when the quote's value could not be converted into from.

venuestring | null

The venue whose answer estimated the step. Absent when no venue did.

Show child attributes

Any of: string 1

See the OpenAPI specification for the complete schema.

Any of: null 2

See the OpenAPI specification for the complete schema.

amount_outstring | null

Estimated amount of to leaving the step, handed to the next step or to delivery.

sampled_atinteger | null

Unix time the cached answer behind the estimate was sampled. Absent when the venue was asked live.

uint64 · min: 0

attemptsobject[]

Every venue ranking asked for the step, with its answer. Absent when ranking asked none.

Show child attributes

See the OpenAPI specification for the complete schema.

routesobject[]required

The best-ranked paths, best first, at most 20.

Show child attributes

assetsstring[]required

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

Show child attributes

See the OpenAPI specification for the complete schema.

venuesstring[][]required

The venues that can serve each step, in order.

Show child attributes

See the OpenAPI specification for the complete schema.

estimated_amount_outstringrequired

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

confirmedbooleanrequired

Whether the path was quoted live. Its result is under routes when every step answered, and its failed step under attempts otherwise.

Any of: null 2

null

attemptsobject[]required

Every venue quote requested while confirming the best-ranked paths.

Show child attributes

roundintegerrequired

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

uint · min: 0

fromstringrequired

Asset entering the hop, written per format.

tostringrequired

Asset leaving the hop, written per format.

amount_instringrequired

Amount the hop was priced for.

venuestringrequired

The venue asked.

elapsed_msintegerrequired

Milliseconds until the venue answered or was cut off.

uint64 · min: 0

One of: quoted

The venue answered; step is the costed hop.

stepobjectrequired

One venue leg of the route.

Show child attributes

venuestringrequired

Venue that executes this step.

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.

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.

tostringrequired

Asset leaving the step, written per format.

amount_instringrequired

amount_outstringrequired

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

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 deadline.

statusstringrequired

Value: "timed_out"

routesobject[]required

Each complete path and whether it produced a quote.

Show child attributes

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", "euler", "flytrade", "hyperliquid_spot", "kyberswap", "lifi_fast", "lifi_standard", "mayan", "mayan_swap", "metric", "morpho", "nordstern", "near_intents", "okx", "relay", "rift_otc", "transit", "tydro", "ultrayield_deposit", "ultrayield_withdrawal", "uniswap", "unit", "velora", "weth_contract", "xstocks"

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.

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

idstringrequired

Identifier to pass as quote_id when creating the order.

uuid

fromstringrequired

Asset sold, written per format.

tostringrequired

Asset received, written per format.

amount_instringrequired

The amount quoted, echoed in format.

estimated_amount_outstringrequired

Expected amount of to delivered to the order's to_address, after every venue and delivery cost and the integrator fee: the amount_out of the route's delivery step.

estimated_execution_coststringrequired

The network fees the router pays to execute the order, in to.

routeobject[]required

The route in execution order: a venue step for each venue leg, then the delivery step into to_address.

Show child attributes

See the OpenAPI specification for the complete schema.

expires_atstringrequired

Instant after which the quote is refused on order creation.

date-time

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.

integrator_fee_bpsinteger | null

The integrator_fee_bps the quote was asked with, or null.

Show child attributes

Any of: integer 1

See the OpenAPI specification for the complete schema.

Any of: null 2

See the OpenAPI specification for the complete schema.

integrator_fee_recipientstring | null

The integrator_fee_recipient the quote was asked with, or null.

Show child attributes

Any of: string 1

See the OpenAPI specification for the complete schema.

Any of: null 2

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"

Any of: null 2

null

Try it out

Request example

Parameters

Required parameters

Optional parameters

Responses