Introduction¶
XMR.to - Pay the world with Monero. Monero is a secure, private, untraceable currency that is open-source and freely available to all. XMR.to converts moneroj (XMR) provided by the user to bitcoins (BTC), which are sent to a given bitcoin address.
XMR.to provides an API that enables developers to use the service in programs, apps, scripts etc. This API therefore allows developers to integrate an option to pay any bitcoin address in their product, for example, in a Monero wallet service. The API is a REST-like API using JSON as data format. It does not require authentication. This document describes this API and gives examples of its usage.
Warning
You agree to XMR.to’s Terms of Service and API Terms by accessing this API in any way or form. Read the Terms of Service here: https://xmr.to/terms-of-service and the API terms here: https://xmr.to/api-terms
Overview¶
In order to use XMR.to, a user must first create an order over a certain amount of bitcoins (BTC). Once the order has been created, XMR.to provides the user with the details for the payment in moneroj (XMR). Once the user has fully paid using Monero, XMR.to will create a bitcoin transaction over the given amount to the given bitcoin address.
When using the API, the general flow of events is similar:
get current order parameters to see if XMR.to is available and to fetch current price, order limits, etc…
create a new order by supplying bitcoin destination address and mount
check order status to get payment information
pay order
continue to repeatedly check order status for processing progress
Naming conventions¶
API base URL¶
The base URL of the API is https://xmr.to/api/
, followed by the version identifier (currently v3
),
followed by the conversion direction (currently only xmr2btc
). Therefore, the complete API base URL
is https://xmr.to/api/v3/xmr2btc/
.
Note
The current version of the API is 3.
API endpoint names¶
API endpoints are always named <noun>_<verb>
. For example, the endpoint to create
a new order is called /order_create/
. For example, for API version 3 the complete URL would be
https://xmr.to/api/v3/xmr2btc/order_create/
.
Field names and values¶
Fields are named using lower-case nouns separated by underscores. Values are given in their default format.
For example, the field btc_amount
gives the amount of an order in bitcoins rather than satoshis.
Data types are not indicated in field names.
Data format and errors¶
Responses¶
API responses are always JSON-formatted data.
API errors¶
On success, the API returns the requested data in JSON format and HTTP return code 200
.
On failure, the API returns an error message formatted in JSON and a HTTP error code. The error message is formatted as follows:
{
"error": "XMRTO-ERROR-<number>"
"error_msg": "<error_message_as_string>"
"error_msg_display": "<error_message_to_display_as_string>"
}
The error
number is unique per message across all endpoints and can be used to reliably identify
errors when they occur. The error_msg
is a human-readable description of the error and should
not be used by a script or program that uses the API. The same applies to error_msg_display
.
* error_msg
- aimed at technical users
* error_msg_display
- aimed at regular non-technical users
For example, the error below is returned if the user provided a malformed bitcoin address when creating a new order:
{
"error": "XMRTO-ERROR-002"
"error_msg": "malformed btc address"
"error_msg_display": "Is this a valid bitcoin address?"
}
List of all error codes¶
All possible XMR.to API error codes:
HTTP code |
XMR.to error code |
Error message/reason |
Solution |
---|---|---|---|
|
|
internal services not available |
try again later |
|
|
malformed bitcoin address |
check address validity |
|
|
invalid bitcoin amount |
check amount data type |
|
|
bitcoin amount out of bounds |
check min and max amount |
|
|
unexpected validation error |
contact support |
|
|
requested order not found |
check order UUID |
|
|
third party service not available |
try again later |
|
|
insufficient funds available |
try again later |
|
|
invalid request |
check request parameters |
|
|
payment protocol failed |
invalid or outdated data served by URL |
|
|
malformed payment protocol url |
URL is malformed or cannot be contacted |
|
|
too many requests |
try less often |
|
|
access forbidden |
none |
|
|
service is not available in your region |
none |
|
|
invalid monero amount |
check amount data type |
|
|
invalid currency |
check available currency options |
|
|
malformed lightning network invoice |
provide a correct invoice for the main network |
|
|
lightning payment unlikely to succeed |
check first if xmr.to has routes available |
|
|
lightning invoice preimage already known |
don’t use the same invoice more than once |
|
|
lightning invoice is expired or about to expire |
create a new lightning invoice |
Rate limiting¶
API endpoints might be rate-limited to protect them against excessive querying. If you are experiencing this, please adjust your querying behavior.
See the List of all error codes section for the relevant error code.
Region blocking¶
Depending on the regulatory landscape, XMR.to blocks certain regions in order to be compliant with local laws.
Forwarding User Information: If you acts as a proxy and send requests to our API of which you are not the originator, then you must forward the IP address of the user making the originating request, using the X-Forwarded-For HTTP header field to do so. See our API terms here: https://xmr.to/api-terms
See the List of all error codes section for the relevant error code.
Various parameters¶
Currently, XMR.to has a few additional parameters that are constant. Therefore, we do not expose them via a dedicated API endpoint. However, for the sake of completeness, we list them here:
Description |
Value |
---|---|
Number of seconds after which an order times out if no or only partial payment occurred |
900 |
Number of recommended mixins to use in Monero payments |
11 |