Skip to main content
POST
Quote a swap

Authorizations

​
x-api-key
string
header
required

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.

Body

application/json
​
srcChain
string
required

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"

​
tokenIn
string
required

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
string
required

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
string<uint>
required

Input amount in tokenIn's smallest units. Decimal string (uint256-safe).

Pattern: ^\d+$
Example:

"1000000"

​
recipient
string
required

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"

​
dstChain
string

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"

​
srcAddress
string

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
string<address>

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.

Example:

"0x37a351f11e5614FC56e3BFb84aAC940767faC365"

​
slippageBps
number

Slippage tolerance in basis points (1 = 0.01%). If omitted, the service default applies.

Required range: 1 <= x <= 10000
Example:

50

​
fee
number

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.

Required range: 0 <= x <= 0.1
Example:

0.01

​
directToRecipient
boolean

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
boolean

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

Response

200 - application/json
​
id
string
required

Deterministic quote id (hex). Caller passes back when re-quoting or correlating logs.

Example:

"0x6183cb88a1199a5b85e492cf3cfb93297bae1de0d57c33c3998a256a2675972a"

​
tool
string
required

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
object
required

The bridge or exchange this route uses, with display name and logo.

​
action
object
required

What the route does: source and destination chain, token and amounts.

​
estimate
object
required

Expected output, fees, gas cost and duration for this route.

​
includedSteps
object[]
required

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.

​
transactionRequest
object
required

Ready-to-submit transaction for the payer's wallet — to, data, value, chainId. Submit as-is.

​
source
enum<string>
required

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.

Available options:
lifi,
piteas,
uniswap_v3,
superswap,
diamondSwap,
diamondTransfer,
nearIntents
Example:

"superswap"

​
isIntent
boolean
required

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
number
required

Unix seconds when this quote was generated.

Example:

1716345600

​
expiresAt
number
required

Unix seconds when this quote becomes stale. Reject after this.

Example:

1716345645

​
deposit
object

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