> ## Documentation Index > Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt > Use this file to discover all available pages before exploring further. # Quote a swap > Same-chain (omit `dstChain`): returns router calldata and a minimum output for an exact-input swap on the requested chain. Cross-chain (set `dstChain`): returns calldata that swaps on the source chain, bridges, and settles on the destination. Routing is selected per quote across every source available to us; the chosen route is reported in `source` and `tool` for display and support only. Never branch on those — the selection changes as better routes appear. The response follows the common aggregator envelope (action / estimate / includedSteps / transactionRequest), so a client already written against that shape can adopt this with minimal mapping. ## OpenAPI ````yaml /api-reference/openapi.json post /quote openapi: 3.1.0 info: title: Hypermid API description: >- Price and execute cross-chain swaps, read reference data and payer balances, and quote the fiat on-ramp. Quotes return an executable `transactionRequest` your frontend submits directly, so Hypermid never custodies the funds. Payments — `checkout`, `deposit`, and `withdrawal` sessions — and payment-link management are available through these merchant REST endpoints and the [`@hypermid/sdk`](https://docs.hypermid.io/sdk/payments) package. Payer-facing routes are intentionally omitted. version: 0.2.0 contact: {} servers: - url: https://server.hypermid.io description: Production — live keys (sk_live_…) - url: https://server.hypermid.io description: Sandbox — test keys (sk_test_…), testnets only security: [] tags: - name: payments description: >- Create and read payment sessions, manage webhooks, and configure payout addresses with a secret partner key. - name: payment links description: >- Create, read, version, and revoke reusable checkout payment links with a secret partner key. - name: quote description: >- Route pricing for the orchestration product. Returns an executable `transactionRequest` your frontend submits directly, so Hypermid never custodies the funds. - name: status description: >- Resolve the state of a submitted swap or transfer. Two endpoints with different audiences — see each one's description before choosing. - name: catalog description: >- Reference data an integration needs to render a picker: supported chains and tokens, prices, routable connections, and fee configuration. A sandbox key sees only testnets here. - name: balances description: Read a payer wallet's token balances across supported chains. - name: onramp description: >- The fiat rail — card and bank payment for crypto, quoted and settled through our onramp partner. Requires per-partner onramp credentials on your account. - name: webhooks description: >- Events Hypermid sends TO you when a session completes. These are requests we make to your server, not endpoints you call. paths: /quote: post: tags: - quote summary: Quote a swap description: >- Same-chain (omit `dstChain`): returns router calldata and a minimum output for an exact-input swap on the requested chain. Cross-chain (set `dstChain`): returns calldata that swaps on the source chain, bridges, and settles on the destination. Routing is selected per quote across every source available to us; the chosen route is reported in `source` and `tool` for display and support only. Never branch on those — the selection changes as better routes appear. The response follows the common aggregator envelope (action / estimate / includedSteps / transactionRequest), so a client already written against that shape can adopt this with minimal mapping. operationId: QuoteController_quote parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QuoteRequestDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/QuoteResponseDto' security: - x-api-key: [] components: schemas: QuoteRequestDto: type: object properties: srcChain: type: string description: >- Source chain identifier. EVM: stringified chain id (`"84532"`, `"11155111"`). Non-EVM: kebab key (`"solana-mainnet"`, `"bitcoin"`). Must resolve via `chainConfigById` to one of the supported chains. example: '11155111' dstChain: type: string description: >- Destination chain identifier. When set AND different from `srcChain`, the request is routed through the cross-chain `superswap` adapter (Hypermid diamond's SwapAndBridge). When omitted, a same-chain adapter is used. example: '84532' tokenIn: type: string description: >- Input token address (tokenIn), on `srcChain`. Format follows `srcChain`: EVM chains take a 0x-prefixed 40-char hex string, non-EVM chains take that chain's native address format (e.g. base58 for Solana). example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' tokenOut: type: string description: >- Output token address (tokenOut), on `dstChain` (or `srcChain` when same-chain). Format follows `dstChain`: EVM chains take a 0x-prefixed 40-char hex string, non-EVM chains take that chain's native address format (e.g. base58 for Solana). example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' amountIn: type: string format: uint description: >- Input amount in tokenIn's smallest units. Decimal string (uint256-safe). example: '1000000' pattern: ^\d+$ recipient: type: string description: >- Address that will receive tokenOut after the swap. This lives on the DESTINATION chain, so its format follows `dstChain` — a base58 address for a Solana payout, not a 0x EVM address. Format follows `dstChain`: EVM chains take a 0x-prefixed 40-char hex string, non-EVM chains take that chain's native address format (e.g. base58 for Solana). example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' srcAddress: type: string description: >- Source-chain SENDER — the wallet that signs + submits the source transaction (`transactionRequest.from`) and that the inner-swap routers quote against. Distinct from `recipient`: for a cross-chain swap the sender lives on the SOURCE chain while `recipient` is the destination payout. When omitted, defaults to `recipient` at the API boundary (same-chain swaps where sender == payout). REQUIRED when src and dst are in different ecosystems, where that default would be nonsense. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' refundRecipient: type: string description: >- Destination-chain principal authorised to recover funds via `SettlementFacet.sendFallback` if the executor fails to deliver before `fallbackDelay` elapses. Distinct from `recipient` (happy-path payout target) — useful when the src-tx sender + the dst-side beneficiary live at different addresses (smart wallet sources, aggregator UIs). When omitted, defaults to `recipient` at the API boundary — same address receives both happy-path payout AND fallback refund. Pass explicitly only when you want the two split (e.g. recipient = end-user, refundRecipient = treasury). Stays EVM-only on purpose, unlike `recipient`: this is a Hypermid diamond concept (`SettlementFacet.sendFallback`), and the diamond only exists on EVM chains. A non-EVM destination routes over an intent-based rail, which has no claim to recover, so the field is not meaningful there. format: address example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' slippageBps: type: number description: >- Slippage tolerance in basis points (1 = 0.01%). If omitted, the service default applies. example: 50 minimum: 1 maximum: 10000 fee: type: number description: >- Partner's NET integrator fee as a decimal share of amountIn (0.01 = 1%). The net rate has the same meaning on every rail; providers that split an app fee receive a rail-specific gross declaration so the partner still receives this rate. Converted to basis points server-side, bounded only by the contract hard cap of 1000 bps (10%) — the direct quote API has no per-partner soft cap. The fee is taken from the source token and accrues to the partner's configured fee wallet (set per API key's partner). Rejected (400) if the partner has no fee wallet configured. minimum: 0 maximum: 0.1 example: 0.01 directToRecipient: type: boolean description: >- Recipient-direct bridge mode. When true the Warp Route delivers the bridged asset straight to `recipient` on the destination chain — no dst-side claim is registered, so the registrar + executor are NOT involved. Only valid when the recipient wants the bridged asset as-is (no destination swap). Cheaper + faster, but the user receives the bridged token, not an arbitrary outputToken. Defaults false (claim flow). example: false rawSwap: type: boolean description: >- Raw-swap mode. When true, a same-chain PulseChain swap returns the DIRECT aggregator router call in `transactionRequest` instead of the diamond `swapOnly` wrapper. Set by the diamond executor's settlement path, which runs the destination swap itself from inside `SettlementFacet.executeClaim` and so needs raw router calldata (the diamond-wrapped target would make the diamond call itself and revert, and its post-fee sizing drops the estimate below the committed floor). Not for user wallets — those want the diamond route so the swap emits `SwapCompleted`. Defaults false. example: false required: - srcChain - tokenIn - tokenOut - amountIn - recipient QuoteResponseDto: type: object properties: id: type: string description: >- Deterministic quote id (hex). Caller passes back when re-quoting or correlating logs. example: '0x6183cb88a1199a5b85e492cf3cfb93297bae1de0d57c33c3998a256a2675972a' tool: type: string description: >- Opaque identifier for the routing tool that produced this quote. For display and support only — routing is chosen per quote, so code that branches on this breaks the first time a better route wins. example: hypermid-swap toolDetails: description: The bridge or exchange this route uses, with display name and logo. allOf: - $ref: '#/components/schemas/ToolDetailsDto' action: description: >- What the route does: source and destination chain, token and amounts. allOf: - $ref: '#/components/schemas/ActionDto' estimate: description: Expected output, fees, gas cost and duration for this route. allOf: - $ref: '#/components/schemas/EstimateDto' includedSteps: description: >- Per-leg breakdown of the route. A same-chain swap has a single entry; a cross-chain route runs a source swap, a bridging leg, then an optional destination swap. type: array items: $ref: '#/components/schemas/IncludedStepDto' transactionRequest: description: >- Ready-to-submit transaction for the payer's wallet — `to`, `data`, `value`, `chainId`. Submit as-is. allOf: - $ref: '#/components/schemas/TransactionRequestDto' deposit: description: >- Deposit instruction for deposit-based (intent) routes. Present when the route settles by transfer to an address rather than by a contract call. For a NON-EVM source this is the payer's only actionable output — `transactionRequest` is an inert placeholder. For an EVM source the deposit is ALSO encoded in `transactionRequest` (a plain transfer to `deposit.address`). allOf: - $ref: '#/components/schemas/DepositInstructionDto' source: type: string enum: - lifi - piteas - uniswap_v3 - superswap - diamondSwap - diamondTransfer - nearIntents description: >- Which internal adapter produced this quote. A Hypermid-specific addition to the standard aggregator envelope, for display and support only — do not branch on it. example: superswap isIntent: type: boolean description: >- True when this route settles via an INTENT (deposit-to-solver) flow rather than a direct on-chain swap/bridge. This is the ONLY signal the frontend needs to distinguish intent routes — it does NOT branch on `source`. Intent routes still execute through the same two primitives every route uses (sign `transactionRequest` for an EVM source, or sign the `deposit` instruction for a non-EVM source) and poll `/status` identically. Adding a NEW intent kind is a backend-only change: implement the adapter, add its `QuoteSource` to INTENT_SOURCES, and set this true — the frontend stays unchanged. example: false generatedAt: type: number description: Unix seconds when this quote was generated. example: 1716345600 expiresAt: type: number description: Unix seconds when this quote becomes stale. Reject after this. example: 1716345645 required: - id - tool - toolDetails - action - estimate - includedSteps - transactionRequest - source - isIntent - generatedAt - expiresAt ToolDetailsDto: type: object properties: key: type: string description: Stable key identifying the routing tool/provider. example: hypermid name: type: string description: Human display name. example: Hypermid Swap logoURI: type: string description: Logo URL for the routing tool. example: https://hypermid.xyz/logo.svg required: - key - name ActionDto: type: object properties: fromChainId: type: string description: Source chain id (stringified). example: '11155111' toChainId: type: string description: >- Destination chain id (stringified; == fromChainId for same-chain quotes). example: '84532' fromToken: description: Input token descriptor. allOf: - $ref: '#/components/schemas/TokenDescriptorDto' toToken: description: Output token descriptor. allOf: - $ref: '#/components/schemas/TokenDescriptorDto' fromAmount: type: string format: uint description: Input amount in fromToken's smallest units. example: '1000000000000000' pattern: ^\d+$ fromAddress: type: string format: address description: >- Sender / src-tx initiator — the request's `srcAddress` (or `recipient` when `srcAddress` is omitted). Same value as `transactionRequest.from`. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ toAddress: type: string format: address description: Destination-chain recipient of `toToken` on successful execute. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ slippage: type: number description: Slippage tolerance as a 0..1 fraction. `slippageBps / 10_000`. example: 0.02 required: - fromChainId - toChainId - fromToken - toToken - fromAmount - fromAddress - toAddress - slippage EstimateDto: type: object properties: tool: type: string description: Routing tool selected for this estimate. example: hypermid-swap approvalAddress: type: string format: address description: >- ERC20 approval target. For Hypermid superswap this is the source-chain DiamondShell — approve `fromAmount` before broadcasting. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ toAmountMin: type: string format: uint description: >- Floor on `toToken` delivered on destination — settle-adapter enforces this. example: '5334147' pattern: ^\d+$ toAmount: type: string format: uint description: Best-case `toToken` delivered, before applying slippage cushion. example: '5503089' pattern: ^\d+$ fromAmount: type: string format: uint description: Echo of input amount (lets the response stand alone). example: '1000000000000000000' pattern: ^\d+$ feeCosts: description: Itemised fee breakdown by leg (protocol + AMM + interchain). type: array items: $ref: '#/components/schemas/FeeCostDto' gasCosts: description: >- Itemised gas and native-fee costs the caller must account for (source-chain transaction plus the interchain delivery fee on a cross-chain route). type: array items: $ref: '#/components/schemas/GasCostDto' executionDuration: type: number description: >- Expected end-to-end execution time in seconds (source transaction, interchain finality, destination settlement). example: 90 fromAmountUSD: type: string description: >- USD value of `fromAmount` for UI display. Empty when pricing unavailable. toAmountUSD: type: string description: >- USD value of `toAmount` for UI display. Empty when pricing unavailable. priceImpact: type: string description: >- USD-value drop from input to output as a 0..1 fraction `max(0, (fromAmountUSD - toAmountUSD) / fromAmountUSD)`. `"0"` when input USD is unknown/zero. example: '0.004' required: - tool - approvalAddress - toAmountMin - toAmount - fromAmount - feeCosts - gasCosts - executionDuration IncludedStepDto: type: object properties: id: type: string description: >- Stable id for this leg. Source and destination swaps are `swap-src` and `swap-dst`; the bridging leg is named for the transport that carries it. Treat it as opaque — use it to correlate legs, not to branch on. example: swap-src type: type: string description: Step type — `swap` for AMM legs, `cross` for bridge legs. example: swap tool: type: string description: Routing tool that produces this leg's calldata. example: uniswap_v3 toolDetails: description: Display metadata for the tool. allOf: - $ref: '#/components/schemas/ToolDetailsDto' action: description: Per-leg action shape — same fields as the outer `action`. allOf: - $ref: '#/components/schemas/ActionDto' estimate: description: Per-leg estimate (toAmount / fees / etc.) for this leg in isolation. allOf: - $ref: '#/components/schemas/EstimateDto' amountIn: type: string description: Leg input amount in tokenIn smallest units (decimal string). example: '10000000000000000' minAmountOut: type: string description: Leg floor output in tokenOut smallest units (decimal string). example: '336193422942357498243973' slippageBps: type: number description: >- Slippage applied to this leg in basis points. Bridge legs are exact (0). example: 200 calldata: type: string description: >- Router/adapter calldata for swap legs (opaque aggregator payload). Absent for bridge legs. target: type: string description: >- Contract the leg's calldata targets (router/adapter). Absent for bridge legs. fee: description: >- Protocol/interchain fee on this leg. Absent when the leg bears no fee. allOf: - $ref: '#/components/schemas/StepFeeDto' gas: description: Native gas for this leg (cost/price + who pays). allOf: - $ref: '#/components/schemas/StepGasDto' required: - id - type - tool - toolDetails - action - estimate TransactionRequestDto: type: object properties: data: type: string format: hex description: >- Encoded calldata. Pass verbatim to `eth_sendTransaction` / wallet signers. example: 0x pattern: ^0x[a-fA-F0-9]*$ to: type: string format: address description: >- Contract to call — for superswap this is the source-chain DiamondShell. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ value: type: string description: >- Native value (hex-encoded wei). `0x0` for ERC20-input flows; non-zero only for `swapNativeAndBridge`. example: '0x0' from: type: string format: address description: >- Sender — the wallet that signs + submits this source tx. Equals the request's `srcAddress` (or `recipient` when `srcAddress` is omitted). example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ chainId: type: string description: EVM chain id for the source tx (stringified, matching the request). example: '11155111' gasLimit: type: string description: >- Hex-encoded gas limit for the source tx. Populated with a flow-aware safe upper bound (same-chain vs cross-chain). The wallet may re-estimate / override. example: '0x6ddd0' gasPrice: type: string description: >- Hex-encoded legacy gas price (wei). Present on non-EIP-1559 chains (e.g. BSC). Mutually exclusive with `maxFeePerGas`/`maxPriorityFeePerGas`. Live value sampled from the source chain at quote time; absent if sampling failed (wallet then decides). maxFeePerGas: type: string description: >- Hex-encoded EIP-1559 max fee per gas (wei). Present on 1559 chains. Pair with `maxPriorityFeePerGas`. Live value sampled at quote time; absent if sampling failed. maxPriorityFeePerGas: type: string description: >- Hex-encoded EIP-1559 max priority fee per gas (wei). Present on 1559 chains alongside `maxFeePerGas`. Live value sampled at quote time; absent if sampling failed. required: - data - to - value - from - chainId - gasLimit DepositInstructionDto: type: object properties: chain: type: string description: >- Chain the payer deposits the origin asset on (canonical chain id/slug, matching the request `srcChain`). example: '1151111081099710' address: type: string description: >- Address the payer sends the origin asset to. NOT necessarily an EVM address — for non-EVM source chains (Solana / BTC / TON / …) this is that chain's native address format. example: 0x1234deadbeef... amount: type: string description: >- Exact amount to deposit, in the origin asset's smallest units (decimal string). example: '1000000000000000' memo: type: string description: >- Memo/tag that MUST accompany the deposit on memo-chains (TON, XRP, …). Omitted when not required. assetId: type: string description: >- Provider-side asset id for the origin token. Opaque — useful only for status correlation and support. example: nep141:... required: - chain - address - amount TokenDescriptorDto: type: object properties: address: type: string format: address description: ERC20 address on `chainId`. example: '0x37a351f11e5614FC56e3BFb84aAC940767faC365' pattern: ^0x[a-fA-F0-9]{40}$ chainId: type: string description: >- EVM chain id this address is bound to (stringified, matching the request). example: '84532' symbol: type: string description: Ticker symbol (`USDC`, `WETH`, ...). example: USDC decimals: type: number description: ERC20 decimals — for display + amount conversion. example: 6 name: type: string description: Display name (e.g. `USD Coin`). example: USD Coin required: - address - chainId - symbol - decimals - name FeeCostDto: type: object properties: name: type: string description: Stable name identifying the fee. example: protocolFee description: type: string description: Free-form explanation surfaced in UI tooltips. percentage: type: string description: >- Fee rate as a 0..1 fraction (e.g. `0.002` for 20 bps). Zero when fee is fixed not proportional. example: '0.002' token: description: Token the fee was charged against. allOf: - $ref: '#/components/schemas/TokenDescriptorDto' amount: type: string format: uint description: Absolute fee amount in `token.decimals`. example: '2000000000000' pattern: ^\d+$ amountUSD: type: string description: USD value of the fee. Empty when oracle pricing isn't available. example: '0.005' included: type: boolean description: >- When true, the fee is already deducted from `estimate.toAmount`. When false, caller must subtract separately. example: true required: - name - description - percentage - token - amount - included GasCostDto: type: object properties: type: type: string description: >- Lifecycle hint — `SEND` for the src-chain entry tx; pipeline txs land downstream. example: SEND estimate: type: string format: uint description: Estimated gas units the src-tx consumes (legacy + EIP-1559). example: '300000' pattern: ^\d+$ limit: type: string format: uint description: Recommended gas limit to set on broadcast. example: '450000' pattern: ^\d+$ price: type: string format: uint description: >- Gas price (legacy wei) used for cost projection. 0 when EIP-1559 fields apply. example: '0' pattern: ^\d+$ amount: type: string format: uint description: Estimated total gas cost in native wei. example: '341627229073' pattern: ^\d+$ amountUSD: type: string description: USD value of `amount`. Empty when pricing unavailable. token: description: Native gas token descriptor (chain's wrapped native + decimals=18). allOf: - $ref: '#/components/schemas/TokenDescriptorDto' required: - type - estimate - limit - price - amount - token StepFeeDto: type: object properties: amount: type: string description: Raw fee amount in `token` smallest units (decimal string). example: '650000' token: type: string description: Fee token address. example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' symbol: type: string description: Fee token symbol. example: USDC decimals: type: number description: Fee token decimals. example: 6 kind: type: string description: '`fixed` = absolute amount; `bps` = rate on the leg input.' example: fixed bps: type: number description: Rate in basis points when kind=bps. example: 20 label: type: string description: Human label. example: interchain fee required: - amount - token - symbol - decimals - kind - label StepGasDto: type: object properties: native: type: string description: >- Native gas cost in wei (decimal string). Absent when wallet/executor-set. example: '91887180631883' priceWei: type: string description: Native gas price in wei (decimal string), when known. symbol: type: string description: Native currency symbol of the chain the gas is paid on. example: ETH note: type: string description: Who pays / how the price is set. example: Interchain gas (destination delivery) required: - symbol securitySchemes: x-api-key: type: apiKey in: header name: x-api-key description: >- Soft-auth read routes accept `x-api-key` with a publishable or partner key; money-moving routes require a secret partner key in `Authorization: Bearer`. ````