{ "openapi": "3.1.0", "info": { "title": "Rift Router API", "version": "1.0.0" }, "servers": [ { "url": "https://api.rift.trade", "description": "Production" } ], "paths": { "/quote": { "post": { "summary": "Quote a swap", "description": "Prices `amount_in` 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`. With `integrator_fee_bps` and `integrator_fee_recipient`, the order pays that share of its output to the recipient when it delivers; `estimated_amount_out` is what remains.", "operationId": "createQuote", "parameters": [ { "in": "header", "name": "x-api-key", "description": "Your API key. Quotes made with it are attributed to your integrator id, whatever `integrator_id` the request sends, and held to its rate.", "schema": { "type": "string" }, "style": "simple" } ], "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", "amount_in": "0.01" } } }, "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" }, "example": { "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", "step_amount_in": "0.01", "venue_amount_in": "0.0099938", "venue_amount_out": "998.514312", "step_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, "from_amount": "0.01", "delivery": { "amount_in": "998.514312", "execution_cost": "1.38421", "integrator_fee": "0", "amount_out": "997.130102" }, "format": "formatted", "integrator_id": null } } } }, "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, both venue lists set, only one of `integrator_fee_bps` and `integrator_fee_recipient` set, or a fee recipient that is not an address on the `to` chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "`x-api-key` is set but is not an active API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The API key is over its requests per second; retry after `Retry-After` seconds", "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 `amount_in` 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" }, "example": { "id": "019a3c7e-6d2f-7b41-8c3e-2a9f4d5e6b70", "quote_id": "019a3c7e-5b1a-7c3e-9a51-6f3d2b8e4a10", "vault_id": "4f8e2c1a-93b7-4d6e-a5f0-7c2b9e8d1a34", "from": "bitcoin.btc", "to": "ethereum.usdc", "amount_in": "0.01", "amount_out": null, "payout_tx": null, "format": "formatted", "deposit_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "to_address": "0x8ba1f109551bd432803012645ac136ddd64dba72", "refund_address": null, "venue_allowlist": [], "venue_blocklist": [], "integrator_id": null, "integrator_fee_bps": null, "integrator_fee_recipient": null, "integrator_fee": null, "integrator_fee_tx": null, "status": "awaiting_deposit", "deposit_deadline": "2026-11-07T19:00:12Z", "created_at": "2026-10-31T19:00:12Z", "from_amount": "0.01" } } } }, "400": { "description": "Unknown quote, or `to_address` is not valid for the destination chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`to_address`, `refund_address` or the quote's integrator fee recipient failed sanctions screening", "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" } } } }, "503": { "description": "Address screening is unavailable; the order was not created", "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" }, "example": { "id": "019a3c7e-6d2f-7b41-8c3e-2a9f4d5e6b70", "quote_id": "019a3c7e-5b1a-7c3e-9a51-6f3d2b8e4a10", "vault_id": "4f8e2c1a-93b7-4d6e-a5f0-7c2b9e8d1a34", "from": "bitcoin.btc", "to": "ethereum.usdc", "amount_in": "0.01", "amount_out": "997.208451", "payout_tx": "0x7f3a9c1e5b2d84f60a1c7e93d5b8426f0e9a3d17c6b24f58a0de13c79b6f2e41", "format": "formatted", "deposit_address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "to_address": "0x8ba1f109551bd432803012645ac136ddd64dba72", "refund_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "venue_allowlist": [], "venue_blocklist": [], "integrator_id": null, "integrator_fee_bps": null, "integrator_fee_recipient": null, "integrator_fee": null, "integrator_fee_tx": null, "status": "delivered", "deposit_deadline": "2026-11-07T19:00:12Z", "created_at": "2026-10-31T19:00:12Z", "from_amount": "0.01" } } } }, "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 and its database answers.", "operationId": "health", "responses": { "200": { "description": "The router is up", "content": { "text/plain; charset=utf-8": { "example": "ok" } } }, "503": { "description": "The router cannot reach its database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "schemas": { "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.", "default": "formatted", "allOf": [ { "$ref": "#/components/schemas/AmountFormat" } ] }, "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" } ] }, "to": { "description": "Asset to receive, in the same form as `from`.", "allOf": [ { "$ref": "#/components/schemas/ChainAsset" } ] }, "amount_in": { "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" }, "venue_allowlist": { "description": "Quote only these venues. Empty means every venue. Cannot be combined\n with `venue_blocklist`.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" }, "default": [] }, "venue_blocklist": { "description": "Never quote these venues. Cannot be combined with `venue_allowlist`.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" }, "default": [] }, "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`.", "default": "optimal", "allOf": [ { "$ref": "#/components/schemas/QuoteMode" } ] }, "include_candidates": { "description": "Include every venue and route that was considered under\n `quote_candidates`. Large, meant for debugging.", "type": "boolean", "default": false }, "integrator_id": { "description": "Identifies the integrator sending the request, for attribution.\n Optional; 1 to 64 characters of letters, digits, `.`, `_` and `-`.\n Echoed in the quote and carried onto the order created from it. When\n `x-api-key` is set, the key's integrator takes its place.", "anyOf": [ { "$ref": "#/components/schemas/IntegratorId" }, { "type": "null" } ], "default": null }, "integrator_fee_bps": { "description": "Share of the output paid to `integrator_fee_recipient`, in basis\n points from 1 (0.01%) to 1000 (10%). Set together with\n `integrator_fee_recipient`, or not at all.", "anyOf": [ { "$ref": "#/components/schemas/FeeBps" }, { "type": "null" } ], "default": null }, "integrator_fee_recipient": { "description": "Address on the `to` chain that receives the integrator fee. Set\n together with `integrator_fee_bps`, or not at all.", "anyOf": [ { "$ref": "#/components/schemas/RawAddress" }, { "type": "null" } ], "default": null } }, "additionalProperties": false, "required": [ "from", "to", "amount_in" ] }, "ChainAsset": { "type": "string" }, "AmountFormat": { "type": "string", "enum": [ "raw", "formatted" ] }, "VenueGroup": { "type": "string", "enum": [ "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" ] }, "QuoteMode": { "type": "string", "enum": [ "fast", "optimal" ] }, "IntegratorId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$" }, "FeeBps": { "type": "integer", "minimum": 1, "maximum": 1000 }, "RawAddress": { "type": "string" }, "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" } ] }, "id": { "description": "Identifier to pass as `quote_id` when creating the order.", "type": "string", "format": "uuid" }, "from": { "description": "Asset sold, written per `format`.", "type": "string" }, "to": { "description": "Asset received, written per `format`.", "type": "string" }, "amount_in": { "description": "The amount quoted, echoed in `format`.", "type": "string" }, "estimated_amount_out": { "description": "Expected amount of `to` delivered to the order's `to_address`, after\n every venue and delivery cost and the integrator fee: the `amount_out`\n of the route's `delivery` step.", "type": "string" }, "estimated_execution_cost": { "description": "The network fees the router pays to execute the order, in `to`.", "type": "string" }, "route": { "description": "The route in execution order: a `venue` step for each venue leg, then\n the `delivery` step into `to_address`.", "type": "array", "items": { "$ref": "#/components/schemas/RouteStepView" } }, "expires_at": { "description": "Instant after which the quote is refused on order creation.", "type": "string", "format": "date-time" }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "integrator_fee_bps": { "description": "The `integrator_fee_bps` the quote was asked with, or null.", "anyOf": [ { "$ref": "#/components/schemas/FeeBps" }, { "type": "null" } ] }, "integrator_fee_recipient": { "description": "The `integrator_fee_recipient` the quote was asked with, or null.", "anyOf": [ { "$ref": "#/components/schemas/ChainAddress" }, { "type": "null" } ] }, "from_amount": { "description": "Deprecated: use `amount_in`.", "type": "string", "deprecated": true }, "delivery": { "description": "Deprecated: use the route's `delivery` step.", "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryView" } ] }, "integrator_id": { "description": "The integrator the quote is attributed to: the API key's when\n `x-api-key` was set, otherwise the request's `integrator_id`, or null.", "anyOf": [ { "$ref": "#/components/schemas/IntegratorId" }, { "type": "null" } ] }, "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" } ] } }, "required": [ "id", "from", "to", "amount_in", "estimated_amount_out", "estimated_execution_cost", "route", "expires_at", "venue_allowlist", "venue_blocklist", "from_amount", "delivery", "format" ] }, "RouteStepView": { "description": "One step of a quote's route, told apart by `type`.", "oneOf": [ { "description": "A venue leg.", "type": "object", "properties": { "type": { "type": "string", "const": "venue" } }, "required": [ "type" ], "allOf": [ { "$ref": "#/components/schemas/VenueStepView" } ] }, { "description": "The transfer of the route's output into `to_address`. Always the last\n step.", "type": "object", "properties": { "type": { "type": "string", "const": "delivery" } }, "required": [ "type" ], "allOf": [ { "$ref": "#/components/schemas/DeliveryView" } ] } ] }, "VenueId": { "type": "string", "enum": [ "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" ] }, "StepExecutionPlan": { "oneOf": [ { "description": "Runs on Bitcoin.", "type": "object", "properties": { "mode": { "type": "string", "const": "bitcoin" } }, "required": [ "mode" ] }, { "description": "Runs on an EVM chain.", "type": "object", "properties": { "chain": { "description": "EVM chain id.", "type": "integer", "format": "int32" }, "mode": { "type": "string", "const": "evm" } }, "required": [ "mode", "chain" ] }, { "description": "Runs on HyperCore.", "type": "object", "properties": { "mode": { "type": "string", "const": "hyperliquid" } }, "required": [ "mode" ] } ] }, "VenueStepView": { "description": "One venue leg of the route.", "type": "object", "properties": { "venue": { "description": "Venue that executes this step.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "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" }, "to": { "description": "Asset leaving the step, written per `format`.", "type": "string" }, "amount_in": { "description": "Amount of `from` entering the step: the quote's `amount_in` for the\n first step, the previous step's `amount_out` after that. A step on\n Bitcoin or HyperCore pays its chain's own fee out of it (the Bitcoin\n miner fee, the HyperCore account activation) before the venue trades\n the rest, so its rate includes that fee.", "type": "string" }, "amount_out": { "description": "Amount of `to` leaving the step, handed to the next step or to the\n delivery.", "type": "string" }, "step_amount_in": { "description": "Deprecated: use `amount_in`.", "type": "string", "deprecated": true }, "venue_amount_in": { "description": "Deprecated.", "type": "string", "deprecated": true }, "venue_amount_out": { "description": "Deprecated: use `amount_out`.", "type": "string", "deprecated": true }, "step_amount_out": { "description": "Deprecated: use `amount_out`.", "type": "string", "deprecated": true } }, "required": [ "venue", "execution", "from", "to", "amount_in", "amount_out", "step_amount_in", "venue_amount_in", "venue_amount_out", "step_amount_out" ] }, "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 venue step's `amount_out`.", "type": "string" }, "execution_cost": { "description": "The network fees the router pays to execute the order, in `to`.", "type": "string" }, "integrator_fee": { "description": "Amount of `to` paid to `integrator_fee_recipient`: `integrator_fee_bps`\n of `amount_in` less `execution_cost`, rounded down. Zero without a fee,\n and when the recipient cannot receive it: below a Bitcoin output's dust\n floor, or a HyperCore address with no account.", "type": "string" }, "amount_out": { "description": "Amount that arrives at `to_address`. This is `estimated_amount_out`.", "type": "string" } }, "required": [ "amount_in", "execution_cost", "integrator_fee", "amount_out" ] }, "ChainAddress": { "type": "string" }, "QuoteAuditView": { "description": "Everything the quoter considered, for debugging. Direct venues under\n `single_hop`, multi-venue routes under `multi_hop`.", "type": "object", "properties": { "single_hop": { "description": "The venues able to quote the pair directly and what each answered.", "allOf": [ { "$ref": "#/components/schemas/SingleHopAuditView" } ] }, "multi_hop": { "description": "The graph search over intermediate assets and its outcome.", "allOf": [ { "$ref": "#/components/schemas/MultiHopAuditView" } ] } }, "required": [ "single_hop", "multi_hop" ] }, "SingleHopAuditView": { "description": "The venues able to quote the pair directly.", "type": "object", "properties": { "setup_error": { "description": "Why no direct venue was asked, when execution costs could not be\n priced: `pricing timed out`, `pricing unavailable for ` (a\n temporary outage) or `no price available for ` (the asset has\n no price).", "type": [ "string", "null" ] }, "candidates": { "description": "One entry per venue able to quote the pair directly.", "type": "array", "items": { "$ref": "#/components/schemas/CandidateView" } } }, "required": [ "candidates" ] }, "CandidateView": { "description": "One venue's attempt to quote the pair directly.", "type": "object", "properties": { "venue": { "description": "The venue able to quote the pair directly.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "elapsed_ms": { "description": "Milliseconds until the venue answered or was cut off.", "type": "integer", "format": "uint64", "minimum": 0 }, "best": { "description": "Whether this candidate is the quote that was returned.", "type": "boolean" } }, "required": [ "venue", "elapsed_ms", "best" ], "oneOf": [ { "description": "The venue answered; `quote` is the costed result and `costing_audit`\n the raw answer it was derived from.", "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/QuoteView" }, "costing_audit": { "$ref": "#/components/schemas/CostingAuditView" }, "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" ] }, { "description": "The venue was never asked because execution costs could not be\n priced; `single_hop.setup_error` says why.", "type": "object", "properties": { "status": { "type": "string", "const": "not_asked" } }, "required": [ "status" ] } ] }, "QuoteView": { "description": "The priced route shared by the quote response and every candidate.", "type": "object", "properties": { "id": { "description": "Identifier to pass as `quote_id` when creating the order.", "type": "string", "format": "uuid" }, "from": { "description": "Asset sold, written per `format`.", "type": "string" }, "to": { "description": "Asset received, written per `format`.", "type": "string" }, "amount_in": { "description": "The amount quoted, echoed in `format`.", "type": "string" }, "estimated_amount_out": { "description": "Expected amount of `to` delivered to the order's `to_address`, after\n every venue and delivery cost and the integrator fee: the `amount_out`\n of the route's `delivery` step.", "type": "string" }, "estimated_execution_cost": { "description": "The network fees the router pays to execute the order, in `to`.", "type": "string" }, "route": { "description": "The route in execution order: a `venue` step for each venue leg, then\n the `delivery` step into `to_address`.", "type": "array", "items": { "$ref": "#/components/schemas/RouteStepView" } }, "expires_at": { "description": "Instant after which the quote is refused on order creation.", "type": "string", "format": "date-time" }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "integrator_fee_bps": { "description": "The `integrator_fee_bps` the quote was asked with, or null.", "anyOf": [ { "$ref": "#/components/schemas/FeeBps" }, { "type": "null" } ] }, "integrator_fee_recipient": { "description": "The `integrator_fee_recipient` the quote was asked with, or null.", "anyOf": [ { "$ref": "#/components/schemas/ChainAddress" }, { "type": "null" } ] }, "from_amount": { "description": "Deprecated: use `amount_in`.", "type": "string", "deprecated": true }, "delivery": { "description": "Deprecated: use the route's `delivery` step.", "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryView" } ] } }, "required": [ "id", "from", "to", "amount_in", "estimated_amount_out", "estimated_execution_cost", "route", "expires_at", "venue_allowlist", "venue_blocklist", "from_amount", "delivery" ] }, "CostingAuditView": { "description": "The venue's raw answer before execution costs were applied.", "type": "object", "properties": { "venue": { "description": "The venue that answered.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "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" } }, "required": [ "venue", "observed_amount_in", "observed_amount_out" ] }, "MultiHopAuditView": { "description": "The graph search for routes through intermediate assets.", "type": "object", "properties": { "hops": { "description": "Fewest venue steps of any path. Null when no path exists.", "type": [ "integer", "null" ], "format": "uint", "minimum": 0 }, "paths": { "description": "Number of candidate paths found, up to the hop limit.", "type": "integer", "format": "uint", "minimum": 0 }, "complete": { "description": "Whether every path was enumerated, false when the search hit its\n limit.", "type": "boolean" }, "setup_error": { "description": "Why execution costs could not be priced, when that left no route\n quoted, in the same words as `single_hop.setup_error`.", "type": [ "string", "null" ] }, "rank": { "description": "How the paths were ranked before the best of them were quoted live.\n Absent when no path exists or execution costs could not be priced.", "anyOf": [ { "$ref": "#/components/schemas/RankView" }, { "type": "null" } ] }, "attempts": { "description": "Every venue quote requested while confirming the best-ranked paths.", "type": "array", "items": { "$ref": "#/components/schemas/HopAttemptView" } }, "routes": { "description": "Each complete path and whether it produced a quote.", "type": "array", "items": { "$ref": "#/components/schemas/RouteCandidateView" } } }, "required": [ "paths", "complete", "attempts", "routes" ] }, "RankView": { "description": "The estimates the paths were ranked by.", "type": "object", "properties": { "elapsed_ms": { "description": "Milliseconds the ranking took.", "type": "integer", "format": "uint64", "minimum": 0 }, "edges": { "description": "Every step any path takes, estimated once at the quote's value in the\n step's input asset.", "type": "array", "items": { "$ref": "#/components/schemas/EdgeRankView" } }, "routes": { "description": "The best-ranked paths, best first, at most 20.", "type": "array", "items": { "$ref": "#/components/schemas/RankedRouteView" } } }, "required": [ "elapsed_ms", "edges", "routes" ] }, "EdgeRankView": { "description": "One step's estimate.", "type": "object", "properties": { "from": { "description": "Asset entering the step, written per `format`.", "type": "string" }, "to": { "description": "Asset leaving the step, written per `format`.", "type": "string" }, "amount_in": { "description": "The amount the step was estimated for. Absent when the quote's value\n could not be converted into `from`.", "type": [ "string", "null" ] }, "venue": { "description": "The venue whose answer estimated the step. Absent when no venue did.", "anyOf": [ { "$ref": "#/components/schemas/VenueId" }, { "type": "null" } ] }, "amount_out": { "description": "Estimated amount of `to` leaving the step, handed to the next step or\n to delivery.", "type": [ "string", "null" ] }, "sampled_at": { "description": "Unix time the cached answer behind the estimate was sampled. Absent\n when the venue was asked live.", "type": [ "integer", "null" ], "format": "uint64", "minimum": 0 }, "attempts": { "description": "Every venue ranking asked for the step, with its answer. Absent when\n ranking asked none.", "type": "array", "items": { "$ref": "#/components/schemas/EdgeAttemptView" } } }, "required": [ "from", "to" ] }, "EdgeAttemptView": { "description": "One venue asked for a step while ranking.", "type": "object", "properties": { "venue": { "description": "The venue asked.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "elapsed_ms": { "description": "Milliseconds until the venue answered or was cut off.", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "venue", "elapsed_ms" ], "oneOf": [ { "description": "The venue answered; `step` is the costed hop.", "type": "object", "properties": { "step": { "$ref": "#/components/schemas/VenueStepView" }, "status": { "type": "string", "const": "quoted" } }, "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" ] } ] }, "RankedRouteView": { "description": "One ranked path.", "type": "object", "properties": { "assets": { "description": "The assets along the path, from `from` to `to`, written per `format`.", "type": "array", "items": { "type": "string" } }, "venues": { "description": "The venues that can serve each step, in order.", "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } } }, "estimated_amount_out": { "description": "Estimated amount of `to` delivered to the order's `to_address`, after\n every venue and delivery cost.", "type": "string" }, "confirmed": { "description": "Whether the path was quoted live. Its result is under `routes` when\n every step answered, and its failed step under `attempts` otherwise.", "type": "boolean" } }, "required": [ "assets", "venues", "estimated_amount_out", "confirmed" ] }, "HopAttemptView": { "description": "One venue quote requested for one hop of the search.", "type": "object", "properties": { "round": { "description": "Position of the hop in the route, counted from zero.", "type": "integer", "format": "uint", "minimum": 0 }, "from": { "description": "Asset entering the hop, written per `format`.", "type": "string" }, "to": { "description": "Asset leaving the hop, written per `format`.", "type": "string" }, "amount_in": { "description": "Amount the hop was priced for.", "type": "string" }, "venue": { "description": "The venue asked.", "allOf": [ { "$ref": "#/components/schemas/VenueId" } ] }, "elapsed_ms": { "description": "Milliseconds until the venue answered or was cut off.", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "round", "from", "to", "amount_in", "venue", "elapsed_ms" ], "oneOf": [ { "description": "The venue answered; `step` is the costed hop.", "type": "object", "properties": { "step": { "$ref": "#/components/schemas/VenueStepView" }, "status": { "type": "string", "const": "quoted" } }, "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" ] } ] }, "RouteCandidateView": { "description": "One complete path through the graph and its result.", "type": "object", "properties": { "venues": { "description": "The venue of each hop, in order.", "type": "array", "items": { "$ref": "#/components/schemas/VenueId" } }, "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" } }, "required": [ "venues", "assets", "best" ], "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" ] } ] }, "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" ] }, "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" ] }, "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" }, "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" } ] }, "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" } ] } }, "additionalProperties": false, "required": [ "quote_id", "to_address" ] }, "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" } ] }, "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" }, "vault_id": { "description": "Internal identifier of the vault holding the deposit address.", "type": "string", "format": "uuid" }, "from": { "description": "Asset to deposit, written per `format`.", "type": "string" }, "to": { "description": "Asset delivered, written per `format`.", "type": "string" }, "amount_in": { "description": "Amount of `from` to deposit, exactly as quoted.", "type": "string" }, "amount_out": { "description": "What the order settled: the amount of `to` that reached `to_address`\n when the status is `delivered`, or the amount of `from` that reached\n `refund_address` when it is `refunded`. Absent until then.", "type": [ "string", "null" ] }, "payout_tx": { "description": "The transaction that paid `amount_out`, to `to_address` when the status\n is `delivered` and to `refund_address` when it is `refunded`: a\n transaction hash, or a txid on Bitcoin. Null until then.", "type": [ "string", "null" ] }, "deposit_address": { "description": "Address on the `from` chain to send `amount_in` to.", "allOf": [ { "$ref": "#/components/schemas/ChainAddress" } ] }, "to_address": { "description": "Address on the `to` chain that receives the output.", "allOf": [ { "$ref": "#/components/schemas/ChainAddress" } ] }, "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 once a refund begins.", "anyOf": [ { "$ref": "#/components/schemas/ChainAddress" }, { "type": "null" } ] }, "venue_allowlist": { "description": "Venues quoting was restricted to; empty when it was not.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "venue_blocklist": { "description": "Venues excluded from quoting; empty when none were.", "type": "array", "items": { "$ref": "#/components/schemas/VenueGroup" } }, "integrator_id": { "description": "The `integrator_id` of the quote this order was created from, or null.", "anyOf": [ { "$ref": "#/components/schemas/IntegratorId" }, { "type": "null" } ] }, "integrator_fee_bps": { "description": "The `integrator_fee_bps` of the quote this order was created from, or\n null.", "anyOf": [ { "$ref": "#/components/schemas/FeeBps" }, { "type": "null" } ] }, "integrator_fee_recipient": { "description": "The `integrator_fee_recipient` of the quote this order was created\n from, or null.", "anyOf": [ { "$ref": "#/components/schemas/ChainAddress" }, { "type": "null" } ] }, "integrator_fee": { "description": "Amount of `to` paid to `integrator_fee_recipient`, written per\n `format`. Null until the order is delivered, and for an order without\n a fee; a refund pays no fee.", "type": [ "string", "null" ] }, "integrator_fee_tx": { "description": "The transaction that paid `integrator_fee`. On EVM chains and Bitcoin\n the fee is paid in the same transaction as `amount_out`, so this equals\n `payout_tx`; on HyperCore it is its own. Null when no fee was paid.", "type": [ "string", "null" ] }, "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`; `refunded` when execution gave\n up and `amount_out` was sent back to `refund_address` instead;\n `expired` when nothing arrived by `deposit_deadline`; `frozen` when the\n order was halted by policy, when execution gave up with no refund\n destination, or when the refund itself failed, and needs an operator.", "allOf": [ { "$ref": "#/components/schemas/OrderStatus" } ] }, "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" }, "created_at": { "description": "When the order was created.", "type": "string", "format": "date-time" }, "from_amount": { "description": "Deprecated: use `amount_in`.", "type": "string", "deprecated": true } }, "required": [ "id", "quote_id", "vault_id", "from", "to", "amount_in", "format", "deposit_address", "to_address", "venue_allowlist", "venue_blocklist", "status", "deposit_deadline", "created_at", "from_amount" ] }, "OrderStatus": { "type": "string", "enum": [ "awaiting_deposit", "funded", "underfunded", "expired", "executing", "delivered", "refunded", "frozen" ] } } } }