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
`503`	`XMRTO-ERROR-001`	internal services not available	try again later
`400`	`XMRTO-ERROR-002`	malformed bitcoin address	check address validity
`400`	`XMRTO-ERROR-003`	invalid bitcoin amount	check amount data type
`400`	`XMRTO-ERROR-004`	bitcoin amount out of bounds	check min and max amount
`400`	`XMRTO-ERROR-005`	unexpected validation error	contact support
`404`	`XMRTO-ERROR-006`	requested order not found	check order UUID
`503`	`XMRTO-ERROR-007`	third party service not available	try again later
`503`	`XMRTO-ERROR-008`	insufficient funds available	try again later
`400`	`XMRTO-ERROR-009`	invalid request	check request parameters
`400`	`XMRTO-ERROR-010`	payment protocol failed	invalid or outdated data served by URL
`400`	`XMRTO-ERROR-011`	malformed payment protocol url	URL is malformed or cannot be contacted
`403`	`XMRTO-ERROR-012`	too many requests	try less often
`403`	`XMRTO-ERROR-013`	access forbidden	none
`403`	`XMRTO-ERROR-014`	service is not available in your region	none
`400`	`XMRTO-ERROR-015`	invalid monero amount	check amount data type
`400`	`XMRTO-ERROR-016`	invalid currency	check available currency options
`400`	`XMRTO-ERROR-017`	malformed lightning network invoice	provide a correct invoice for the main network
`503`	`XMRTO-ERROR-018`	lightning payment unlikely to succeed	check first if xmr.to has routes available
`400`	`XMRTO-ERROR-019`	lightning invoice preimage already known	don’t use the same invoice more than once
`400`	`XMRTO-ERROR-020`	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