Widget Partner API
The Widget Partner API provides server-side endpoints for building On-Ramp and Off-Ramp integrations — fetching rates and limits, managing user authentication, submitting KYC documents, and tracking transactions.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.mercuryo.io/v1.6 |
| Sandbox | https://sandbox-api.mrcr.io/v1.6 |
Authentication
Two tokens are used depending on the context:
| Token | Header | Obtained from | Used for |
|---|---|---|---|
Sdk-Partner-Token |
Sdk-Partner-Token: <token> |
Your integration manager | Partner-level requests: sign-up, sign-in |
Sdk-User-Token |
Sdk-User-Token: <token> |
Returned as bearer_token on sign-in |
User-specific requests: KYC status, document upload |
Sdk-User-Token expires in 24 hours in Production. In Sandbox, it does not expire.
API Sections
| Section | Description |
|---|---|
| Buy | Rate fetching and pre-fill data for On-Ramp (crypto purchase) flows |
| Sell | Rate fetching and pre-fill data for Off-Ramp (crypto sell) flows |
| Transaction Data | Transaction history, status, and detailed transaction information |
| User Widget Authorization | Silent user sign-up and sign-in via widget partner token |
| User API Authentication | User sign-in with OTP verification |
| KYC Verification | KYC status check and document submission |
| General | Public data: supported currencies, exchange rates, transaction limits, country availability |
Callback Reference
Transaction callbacks (webhooks) sent by Mercuryo to your server are documented separately:
- Callback Reference — payload schema, field descriptions, and examples for all transaction types (buy, sell, invoice, withdraw, Spend Card)