Off-Ramp — Crypto Sell

Users sell cryptocurrency and receive fiat money to their Visa or Mastercard.

Note: Off-Ramp is disabled by default. Contact your integration manager to enable it for your widget.

Prerequisites

The user must be signed in to Mercuryo and have a valid, non-expired KYC.
KYC must be completed before the sell transaction can proceed.
Only EUR and USD are available as fiat payout currencies.
Off-Ramp is available only in selected countries.

6-Hour Rule

If the user does not send crypto within 6 hours after initiating the sell, the request fails. If crypto arrives after this window, it is credited to the user's Mercuryo Wallet as a regular crypto deposit (not converted to fiat). Crypto is refunded to refund_address only if there is an error on Mercuryo's side.

Flow Overview

(Optional) Fetch data to pre-fill the widget.
Generate the widget URL.
Show the widget.
The user provides card details and sends crypto to the Mercuryo wallet address shown in the widget.
Mercuryo processes the exchange and sends fiat to the user's card.
Track transaction status via callbacks or API.

Step 1 — Fetch Pre-fill Data (Optional)

Use these endpoints before opening the widget to display rates and available currencies on your own UI, and to build the widget URL with relevant parameters.

Endpoint	Purpose
`GET /v1.6/public/data-by-ip`	User's country code
`GET /v1.6/lib/currencies`	Supported currencies with `widget_offramp_enabled` and `restricted_countries_offramp`
`GET /v1.6/public/currencies-sell`	Fiat and crypto currencies available for sell
`GET /v1.6/public/currency-limits`	Transaction limits
`GET /v1.6/lib/limits/sell`	Limits for all enabled sell currency pairs
`GET /v1.6/widget/sell/rate`	Current exchange rate and fee

Example URL for selling 0.1 BTC for USD:

https://exchange.mercuryo.io/?widget_id=67710925-8b40-4767-846e-3b88db69f04d
  &type=sell
  &currency=BTC
  &fix_currency=true
  &amount=0.1
  &fix_amount=true
  &fiat_currency=USD
  &refund_address=bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
  &merchant_transaction_id=tx_789012

Parameter summary:

Parameter	Required	Description
`widget_id`	Yes	Your Widget ID
`type`	No	Lock to `sell`
`currency`	No	Pre-select crypto to sell
`fix_currency`	No	Prevent user from changing crypto
`amount`	No	Pre-fill crypto amount
`fix_amount`	No	Lock the amount
`fiat_currency`	No	Pre-select payout fiat currency (`EUR` or `USD`)
`refund_address`	No	Wallet address for refund on failure (user can enter in widget if not provided)
`merchant_transaction_id`	No	Your tracking ID

Note: Signature is not required for Off-Ramp.

Same as On-Ramp. See Integration Methods.

The user enters card details for fiat payout.
The widget displays a crypto wallet address to send crypto to.
The user sends crypto to the displayed address.
Mercuryo confirms the deposit and initiates fiat payout.
The user's card receives the fiat amount.

Step 5 — Track Transaction Status

Callbacks — see Callbacks
API Polling — GET /v1.6/sdk-partner/transactions

See Transaction Types & Statuses for sell and deposit status values.

Spend Card Off-Ramp

If Spend Card is enabled for your widget, users can sell crypto and receive EUR directly to their Spend Card instead of an external payment card.

See Spend Card for widget URL, user flow, and transaction tracking.

On-Ramp (Buy)

Callbacks & Webhooks