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 by accessing this API in any way or form. Read the Terms of Service here: https://xmr.to/terms-of-service

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 v2), followed by the conversion direction (currently only xmr2btc). Therefore, the complete API base URL is https://xmr.to/api/v2/xmr2btc/.

Note

The current version of the API is 2.

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 2 the complete URL would be https://xmr.to/api/v2/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_error_message_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. 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"
}

List of all errors 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

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 errors 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.

See the List of all errors 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 BTC confirmations required before we purge an order 144
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