{ "openapi": "3.1.0", "info": { "title": "Rift Router API", "version": "0.2.47" }, "paths": { "/quote": { "post": { "summary": "Quote a swap", "description": "Prices `from_amount` of `from` into `to` across every admitted venue and returns the best route. The quote is stored and can be turned into an order with its `id` until `expires_at`.", "operationId": "createQuote", "requestBody": { "description": "A request to price a swap. Amounts and asset names in the request and the\n response are written in `format`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketQuoteRequest" }, "example": { "format": "formatted", "from": "bitcoin.btc", "to": "ethereum.usdc", "from_amount": "0.01", "return_full_route": true } } }, "required": true }, "responses": { "default": { "description": "The error envelope returned with every non-success status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "200": { "description": "The best executable quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "422": { "description": "No venue could quote the pair; candidates are included when `include_candidates` is set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRefusal" } } } }, "400": { "description": "Malformed request, unknown asset, or both venue lists set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/order": { "post": { "summary": "Create an order from a quote", "description": "Binds the quote to a fresh deposit address and returns the order. Send `from_amount` of `from` to `deposit_address` before `deposit_deadline`. Presenting the same `quote_id` again returns the same order.", "operationId": "createOrder", "requestBody": { "description": "Turns a quote into an order. Repeating the call with the same `quote_id`\n and the same addresses is safe and returns the order already created;\n changing the addresses is rejected because the quote is already used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" } } }, "required": true }, "responses": { "default": { "description": "The error envelope returned with every non-success status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "201": { "description": "The order awaiting its deposit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Unknown quote, or `to_address` is not valid for the destination chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The quote is already bound to another order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "description": "The quote has expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/order/{id}": { "get": { "summary": "Fetch an order", "description": "Returns the order with its current `status`.", "operationId": "getOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" }, "style": "simple" } ], "responses": { "default": { "description": "The error envelope returned with every non-success status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "200": { "description": "The order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "description": "No such order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/health": { "get": { "summary": "Liveness", "description": "Answers `ok` while the router is serving.", "operationId": "health", "responses": { "200": { "description": "The router is up", "content": { "text/plain; charset=utf-8": { "example": "ok" } } } } } } }, "components": { "schemas": { "AmountFormat": { "type": "string", "enum": [ "raw", "formatted" ] }, "ApiError": { "description": "The error envelope returned with every non-success status.", "type": "object", "properties": { "error": { "description": "What went wrong, in one sentence.", "type": "string" } }, "required": [ "error" ] }, "CandidateView": { "description": "One venue's attempt to quote the pair directly.", "type": "object", "properties": { "best": { "description": "Whether this candidate is the quote that was returned.", "type": "boolean" }, "elapsed_ms": { "description": "Milliseconds until the venue answered or was cut off.", "type": "integer", "format": "uint64", "minimum": 0 }, "venue": { "description": "The venue asked.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] } }, "oneOf": [ { "description": "The venue answered; `quote` is the costed result and `costing_audit`\n the raw answer it was derived from.", "type": "object", "properties": { "costing_audit": { "$ref": "#/components/schemas/CostingAuditView" }, "quote": { "$ref": "#/components/schemas/QuoteView" }, "status": { "type": "string", "const": "quoted" } }, "required": [ "status", "quote", "costing_audit" ] }, { "description": "The venue refused or errored.", "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string", "const": "failed" } }, "required": [ "status", "error" ] }, { "description": "The venue did not answer within the `quote_mode` deadline.", "type": "object", "properties": { "status": { "type": "string", "const": "timed_out" } }, "required": [ "status" ] } ], "required": [ "venue", "elapsed_ms", "best" ] }, "ChainAddress": { "type": "string" }, "ChainAsset": { "type": "string" }, "CostingAuditView": { "description": "The venue's raw answer before execution costs were applied.", "type": "object", "properties": { "observed_amount_in": { "description": "Amount the venue was asked to price.", "type": "string" }, "observed_amount_out": { "description": "Amount the venue said it would return for it.", "type": "string" }, "venue": { "description": "The venue that answered.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] } }, "required": [ "venue", "observed_amount_in", "observed_amount_out" ] }, "CreateOrder": { "description": "Turns a quote into an order. Repeating the call with the same `quote_id`\n and the same addresses is safe and returns the order already created;\n changing the addresses is rejected because the quote is already used.", "type": "object", "properties": { "quote_id": { "description": "The `id` of a quote from `POST /quote`. The quote must not have\n expired, and a quote binds to one order.", "type": "string", "format": "uuid" }, "refund_address": { "description": "Address on the `from` chain that receives a refund if the order cannot\n be completed. Optional; when not set, the refund goes to the original\n sender.", "anyOf": [ { "$ref": "#/components/schemas/RawAddress" }, { "type": "null" } ] }, "to_address": { "description": "Address on the `to` chain that receives the output. Validated against\n that chain's address format.", "allOf": [ { "$ref": "#/components/schemas/RawAddress" } ] } }, "additionalProperties": false, "required": [ "quote_id", "to_address" ] }, "DeliveryView": { "description": "The transfer of the route's output into `to_address`.", "type": "object", "properties": { "amount_in": { "description": "Amount of `to` handed to delivery: the last step's `step_amount_out`.", "type": "string" }, "amount_out": { "description": "Amount that arrives at `to_address`. This is `estimated_amount_out`.", "type": "string" }, "execution_cost": { "description": "Cost of the transfer into `to_address`, paid out of `amount_in`.", "type": "string" } }, "required": [ "amount_in", "execution_cost", "amount_out" ] }, "HopAttemptView": { "description": "One venue quote requested for one hop of the search.", "type": "object", "properties": { "amount_in": { "description": "Amount the hop was priced for.", "type": "string" }, "elapsed_ms": { "description": "Milliseconds until the venue answered or was cut off.", "type": "integer", "format": "uint64", "minimum": 0 }, "from": { "description": "Asset entering the hop, written per `format`.", "type": "string" }, "round": { "description": "Position of the hop in the route, counted from zero.", "type": "integer", "format": "uint", "minimum": 0 }, "to": { "description": "Asset leaving the hop, written per `format`.", "type": "string" }, "venue": { "description": "The venue asked.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] } }, "oneOf": [ { "description": "The venue answered; `step` is the costed hop.", "type": "object", "properties": { "status": { "type": "string", "const": "quoted" }, "step": { "$ref": "#/components/schemas/RouteStepView" } }, "required": [ "status", "step" ] }, { "description": "The venue refused or errored.", "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string", "const": "failed" } }, "required": [ "status", "error" ] }, { "description": "The venue did not answer within the deadline.", "type": "object", "properties": { "status": { "type": "string", "const": "timed_out" } }, "required": [ "status" ] } ], "required": [ "round", "from", "to", "amount_in", "venue", "elapsed_ms" ] }, "MarketQuoteRequest": { "description": "A request to price a swap. Amounts and asset names in the request and the\n response are written in `format`.", "type": "object", "properties": { "format": { "description": "How amounts and asset names are written in this request and in the\n response. `formatted` writes amounts as decimals in the asset's own\n units and assets as `.`; `raw` writes amounts as\n base-unit integers and assets in canonical form, `evm:.
`\n on EVM chains. Defaults to `formatted`. Key on assets with `raw`: symbols\n are presentation and may be reassigned.", "allOf": [ { "$ref": "#/components/schemas/AmountFormat" } ], "default": "formatted" }, "from": { "description": "Asset to sell, as `.`. The chain is a name (`ethereum`,\n `base`, `arbitrum`, `robinhood`, `ink`, `bitcoin`, `hyperliquid`) or\n `evm:`. The asset is a symbol, a contract address, or `eth`\n and `btc` for the native coin. Case does not matter.", "allOf": [ { "$ref": "#/components/schemas/ChainAsset" } ] }, "from_amount": { "description": "Amount of `from` to sell. A decimal in the asset's own units when\n `format` is `formatted`, an integer in base units when `raw`.", "type": "string" }, "include_candidates": { "description": "Include every venue and route that was considered under\n `quote_candidates`. Large, meant for debugging.", "type": "boolean", "default": false }, "quote_mode": { "description": "`optimal` gives every venue up to 10 seconds to answer, `fast` cuts\n each one off at 1.5 seconds. Defaults to `optimal`.", "allOf": [ { "$ref": "#/components/schemas/QuoteMode" } ], "default": "optimal" }, "return_full_route": { "description": "Include the hop-by-hop `route` in the response.", "type": "boolean" }, "to": { "description": "Asset to receive, in the same form as `from`.", "allOf": [ { "$ref": "#/components/schemas/ChainAsset" } ] }, "venue_allowlist": { "description": "Quote only these venues. Empty means every venue. Cannot be combined\n with `venue_blocklist`.", "type": "array", "default": [], "items": { "$ref": "#/components/schemas/VenueId" } }, "venue_blocklist": { "description": "Never quote these venues. Cannot be combined with `venue_allowlist`.", "type": "array", "default": [], "items": { "$ref": "#/components/schemas/VenueId" } } }, "additionalProperties": false, "required": [ "from", "to", "from_amount", "return_full_route" ] }, "MultiHopAuditView": { "description": "The graph search for routes through intermediate assets.", "type": "object", "properties": { "attempts": { "description": "Every venue quote requested while walking the paths.", "type": "array", "items": { "$ref": "#/components/schemas/HopAttemptView" } }, "complete": { "description": "Whether every path was enumerated, false when the search hit its\n limit.", "type": "boolean" }, "hops": { "description": "Number of venue steps in the routes tried, the fewest with a path.\n Null when no path exists.", "type": [ "integer", "null" ], "format": "uint", "minimum": 0 }, "paths": { "description": "Number of candidate paths found at that hop count.", "type": "integer", "format": "uint", "minimum": 0 }, "routes": { "description": "Each complete path and whether it produced a quote.", "type": "array", "items": { "$ref": "#/components/schemas/RouteCandidateView" } }, "setup_error": { "description": "Why the search could not start, when it could not.", "type": [ "string", "null" ] } }, "required": [ "paths", "complete", "attempts", "routes" ] }, "OrderResponse": { "description": "An order created from a quote, with its deposit address and current\n status.", "type": "object", "properties": { "format": { "description": "The format every amount and asset name in this response is written in,\n inherited from the quote.", "allOf": [ { "$ref": "#/components/schemas/AmountFormat" } ] }, "amount_out": { "description": "Amount of `to` delivered to `to_address`. Absent until the order is\n delivered.", "type": [ "string", "null" ] }, "created_at": { "description": "When the order was created.", "type": "string", "format": "date-time" }, "deposit_address": { "description": "Address on the `from` chain to send `from_amount` to.", "allOf": [ { "$ref": "#/components/schemas/ChainAddress" } ] }, "deposit_deadline": { "description": "Instant after which deposits are no longer watched for and the order\n expires. Seven days after creation.", "type": "string", "format": "date-time" }, "from": { "description": "Asset to deposit, written per `format`.", "type": "string" }, "from_amount": { "description": "Amount of `from` to deposit, exactly as quoted.", "type": "string" }, "id": { "description": "Identifier used in `GET /order/{id}`.", "type": "string", "format": "uuid" }, "quote_id": { "description": "The quote this order was created from.", "type": "string", "format": "uuid" }, "refund_address": { "description": "Address on the `from` chain that receives a refund if the order cannot\n be completed. Null when none was given; it is then set to the deposit's\n sender address as soon as the deposit is seen.", "allOf": [ { "$ref": "#/components/schemas/RefundTo" } ] }, "status": { "description": "`awaiting_deposit` until funds arrive at `deposit_address`; `funded`\n once they are seen; `executing` while the route runs; `delivered` when\n `amount_out` has reached `to_address`; `expired` when nothing arrived\n by `deposit_deadline`; `stalled` when execution gave up and needs an\n operator; `frozen` when a step was halted by policy and needs an\n operator.", "allOf": [ { "$ref": "#/components/schemas/OrderStatus" } ] }, "to": { "description": "Asset delivered, written per `format`.", "type": "string" }, "to_address": { "description": "Address on the `to` chain that receives the output.", "allOf": [ { "$ref": "#/components/schemas/ChainAddress" } ] }, "vault_id": { "description": "Internal identifier of the vault holding the deposit address.", "type": "string", "format": "uuid" }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } } }, "required": [ "id", "quote_id", "vault_id", "from", "to", "from_amount", "format", "deposit_address", "to_address", "refund_address", "venue_allowlist", "venue_blocklist", "status", "deposit_deadline", "created_at" ] }, "OrderStatus": { "type": "string", "enum": [ "awaiting_deposit", "funded", "underfunded", "expired", "executing", "delivered", "stalled", "frozen" ] }, "QuoteAuditView": { "description": "Everything the quoter considered, for debugging. Direct venues under\n `single_hop`, multi-venue routes under `multi_hop`.", "type": "object", "properties": { "multi_hop": { "description": "The graph search over intermediate assets and its outcome.", "allOf": [ { "$ref": "#/components/schemas/MultiHopAuditView" } ] }, "single_hop": { "description": "One entry per venue asked to quote the pair directly.", "type": "array", "items": { "$ref": "#/components/schemas/CandidateView" } } }, "required": [ "single_hop", "multi_hop" ] }, "QuoteMode": { "type": "string", "enum": [ "fast", "optimal" ] }, "QuoteRefusal": { "description": "Returned when no venue could produce an executable quote for the pair and\n amount.", "type": "object", "properties": { "error": { "description": "Why no quote was possible.", "type": "string" }, "quote_candidates": { "description": "Every venue and route that was tried, with timings and failures.\n Present only when `include_candidates` was set.", "anyOf": [ { "$ref": "#/components/schemas/QuoteAuditView" }, { "type": "null" } ] } }, "required": [ "error" ] }, "QuoteResponse": { "description": "A priced route from `from` to `to`. Valid for order creation until\n `expires_at`, ten minutes after quoting. Amounts and asset names are\n written in `format`.", "type": "object", "properties": { "format": { "description": "The format every amount and asset name in this response is written in.", "allOf": [ { "$ref": "#/components/schemas/AmountFormat" } ] }, "delivery": { "description": "The final transfer into `to_address` and what it costs.", "allOf": [ { "$ref": "#/components/schemas/DeliveryView" } ] }, "estimated_amount_out": { "description": "Expected amount of `to` delivered to the order's `to_address`, after\n every venue and delivery cost.", "type": "string" }, "expires_at": { "description": "Instant after which the quote is refused on order creation.", "type": "string", "format": "date-time" }, "from": { "description": "Asset sold, written per `format`.", "type": "string" }, "from_amount": { "description": "The amount quoted, echoed in `format`.", "type": "string" }, "id": { "description": "Identifier to pass as `quote_id` when creating the order.", "type": "string", "format": "uuid" }, "quote_candidates": { "description": "Every venue and route considered, with timings and failures. Present\n only when `include_candidates` was set.", "anyOf": [ { "$ref": "#/components/schemas/QuoteAuditView" }, { "type": "null" } ] }, "route": { "description": "The venue steps in execution order. Present only when\n `return_full_route` was set.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RouteStepView" } }, "to": { "description": "Asset received, written per `format`.", "type": "string" }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } } }, "required": [ "id", "from", "to", "from_amount", "estimated_amount_out", "delivery", "expires_at", "venue_allowlist", "venue_blocklist", "format" ] }, "QuoteView": { "description": "The priced route shared by the quote response and every candidate.", "type": "object", "properties": { "delivery": { "description": "The final transfer into `to_address` and what it costs.", "allOf": [ { "$ref": "#/components/schemas/DeliveryView" } ] }, "estimated_amount_out": { "description": "Expected amount of `to` delivered to the order's `to_address`, after\n every venue and delivery cost.", "type": "string" }, "expires_at": { "description": "Instant after which the quote is refused on order creation.", "type": "string", "format": "date-time" }, "from": { "description": "Asset sold, written per `format`.", "type": "string" }, "from_amount": { "description": "The amount quoted, echoed in `format`.", "type": "string" }, "id": { "description": "Identifier to pass as `quote_id` when creating the order.", "type": "string", "format": "uuid" }, "route": { "description": "The venue steps in execution order. Present only when\n `return_full_route` was set.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/RouteStepView" } }, "to": { "description": "Asset received, written per `format`.", "type": "string" }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } } }, "required": [ "id", "from", "to", "from_amount", "estimated_amount_out", "delivery", "expires_at", "venue_allowlist", "venue_blocklist" ] }, "RawAddress": { "type": "string" }, "RefundTo": { "type": [ "string", "null" ] }, "RouteCandidateView": { "description": "One complete path through the graph and its result.", "type": "object", "properties": { "assets": { "description": "The assets along the path, from `from` to `to`, written per `format`.", "type": "array", "items": { "type": "string" } }, "best": { "description": "Whether this route is the quote that was returned.", "type": "boolean" }, "venues": { "description": "The venue of each hop, in order.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } } }, "oneOf": [ { "description": "Every hop quoted; `quote` is the costed route.", "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/QuoteView" }, "status": { "type": "string", "const": "quoted" } }, "required": [ "status", "quote" ] }, { "description": "A hop failed; `error` is what stopped the route.", "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string", "const": "failed" } }, "required": [ "status", "error" ] } ], "required": [ "venues", "assets", "best" ] }, "RouteStepView": { "description": "One venue leg of the route.", "type": "object", "properties": { "execution": { "description": "How the step runs: on Bitcoin, on an EVM chain with vault-funded gas,\n on an EVM chain with router-funded gas, or on HyperCore.", "allOf": [ { "$ref": "#/components/schemas/StepExecutionPlan" } ] }, "from": { "description": "Asset entering the step, written per `format`.", "type": "string" }, "step_amount_in": { "description": "Amount entering the step: `from_amount` for the first step, the\n previous step's `step_amount_out` after that.", "type": "string" }, "step_amount_out": { "description": "Amount leaving the step, handed to the next step or to delivery.", "type": "string" }, "to": { "description": "Asset leaving the step, written per `format`.", "type": "string" }, "venue": { "description": "Venue that executes this step.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "venue_amount_in": { "description": "Amount sent to the venue: `step_amount_in` less this step's execution\n cost.", "type": "string" }, "venue_amount_out": { "description": "The venue's output for `venue_amount_in`.", "type": "string" } }, "required": [ "venue", "execution", "from", "to", "step_amount_in", "venue_amount_in", "venue_amount_out", "step_amount_out" ] }, "StepExecutionPlan": { "oneOf": [ { "description": "Runs on Bitcoin.", "type": "object", "properties": { "mode": { "type": "string", "const": "bitcoin" } }, "required": [ "mode" ] }, { "description": "Runs on an EVM chain with gas paid by the vault.", "type": "object", "properties": { "chain": { "description": "EVM chain id.", "type": "integer", "format": "int32" }, "mode": { "type": "string", "const": "evm" } }, "required": [ "mode", "chain" ] }, { "description": "Runs on an EVM chain with gas advanced by the router.", "type": "object", "properties": { "chain": { "description": "EVM chain id.", "type": "integer", "format": "int32" }, "mode": { "type": "string", "const": "evm_gas_desk" } }, "required": [ "mode", "chain" ] }, { "description": "Runs on HyperCore.", "type": "object", "properties": { "mode": { "type": "string", "const": "hyperliquid" } }, "required": [ "mode" ] } ] }, "VenueId": { "type": "string", "enum": [ "aave", "across", "cctp_fast", "cctp_hyperliquid_fast", "cctp_hyperliquid_standard", "cctp_standard", "chainflip", "flytrade", "hyperliquid_spot", "kyberswap", "lifi_fast", "lifi_standard", "mayan", "morpho", "nordstern", "near_intents", "okx", "relay", "transit", "unit", "velora" ] } } }, "servers": [ { "url": "https://api.rift.trade", "description": "Production" } ] }