Swap

Build the execution payload for a quote

post/api/v1/execute

Request

  • Base URL: https://app.ravn.exchange
  • URL: https://app.ravn.exchange/api/v1/execute
  • Auth: one of:
    • API key in header x-api-key
    • none

Headers

Idempotency-Keystring

Any unique value per swap attempt (e.g. a UUID), 1–255 printable ASCII characters. Retrying with the same key and the same request (quoteToken and any addresses) within 24 h returns the first answer instead of building again — at a deposit venue (NEAR Intents, Chainflip, Houdini) a second call would otherwise open a second deposit address. The same key with another quoteToken or other addresses is refused (400); a retry while the first call is still running answers 503 UNAVAILABLE with error.details.retryAfterSec.

Request body

quoteTokenstring required

Token returned from POST /api/v1/quote

destinationAddressstring

Late-bound output recipient, honoured by venues that bind the recipient at execution time (Chainflip, Garden, Houdini Swap, Layerswap, Mayan, NEAR Intents, Rift, RAVN two-hop routes). Every other venue fixes the recipient when it prices the quote: supplying a DIFFERENT address here is rejected with INVALID_REQUEST rather than silently ignored, because the payout would otherwise go to the address the quote was priced for while this call reported success. Supply destinationAddress on the quote call instead, and it is honoured by every venue including same-chain ones. A known non-wallet address (a listed token's mint/contract, this swap's own tokens, the native-coin sentinel, burn addresses, Solana core programs, and — via an on-chain lookup that fails open — a Solana token account or program) is rejected with INVALID_REQUEST on either call — funds sent there are unrecoverable. An empty string means not supplied.

refundAddressstring

Late-bound refund recipient, honoured by venues that read one at execution time (Chainflip, Garden, Houdini Swap, NEAR Intents, Rift). Every other venue, Mayan, Layerswap and RAVN two-hop routes included, fixes the refund address when it prices the quote: one that differs from the refund the quote was priced with is rejected with INVALID_REQUEST rather than silently ignored. A quote priced without one refunds where it was priced (normally userAddress) at these venues, so a refundAddress here other than userAddress is rejected too, when userAddress is a valid address on the input chain (selling native Bitcoin with no quoted refund, a venue that can execute uses this one). Supply refundAddress on the quote call instead.

clientTimezonestring

Your end user's IANA timezone, forwarded only to venues that require it (Houdini). Defaults to UTC.

Response

Execution produced — branch on executionType

Changes

No recorded changes to this operation across all 1 revision of this API.