API migration

This is about migrating from API version 2 to API version 3 of the XMR.to API.

This document describes changes in already existing API calls.

Please see API version 3 for more details and new features.

Note

API version 3 is the current version.

Querying order parameters

Request

Issue a GET request to query current order parameters.

Response

Both versions of the API return:

{
    "lower_limit": <lower_order_limit_in_btc>,
    "price": <price_of_1_xmr_in_btc_as_offered_by_service>,
    "upper_limit": <upper_order_limit_in_btc>,
    "zero_conf_enabled": <true_if_zero_conf_is_enabled_as_boolean>,
    "zero_conf_max_amount": <up_to_this_amount_zero_conf_is_possible>
}

Note

API version 2 returns lower_limit, upper_limit, price and zero_conf_max_amount as float. API version 3 returns lower_limit, upper_limit, price and zero_conf_max_amount as string.

Additionally, with API version 3 you will receive:

{
    "ln_lower_limit": <lightning_lower_order_limit_in_btc_as_string>,
    "ln_upper_limit": <lightning_upper_order_limit_in_btc_as_string>
}

These are the operation limits for orders to be paid through the lighting network.

Example (API version 3)

Request

curl --url https://xmr.to/api/v3/xmr2btc/order_parameter_query/

Response

{
    "price": "0.017666",  // string
    "upper_limit": "20",  // string
    "lower_limit": "0.002",  // string
    "ln_upper_limit": "0.0077",
    "ln_lower_limit": "0.00015",
    "zero_conf_enabled": true,
    "zero_conf_max_amount": "0.1"  // string
}

Creating a new order

Request

Issue a POST request to create a new order supplying the following parameters.

With API version 2 there are separate parameters when creating orders by specifying the order amount in BTC or XMR, respectively:

{
    "btc_amount": <requested_amount_in_btc_as_float>,
    "btc_dest_address": <requested_destination_address_as_string>
}

or

{
    "xmr_amount": <requested_amount_in_xmr_as_float>,
    "btc_dest_address": <requested_destination_address_as_string>
}

With API version 3 the parameters look like this:

{
    "amount": <requested_amount_as_float>,
    "amount_currency": <currency_of_the_requested_amount_as_string>,
    "btc_dest_address": <requested_destination_address_as_string>
}

The available currencies for the amount_currency field are BTC and XMR.

Response

Both versions of the API return:

{
    "state": "TO_BE_CREATED",
    "btc_amount": <requested_amount_in_btc>,
    "btc_dest_address": <requested_destination_address_as_string>,
    "uuid": <unique_order_identifier_as_12_character_string>
}

Note

API version 2 returns btc_amount as float. API version 3 returns btc_amount as string.

Additionally with API version 3 you will receive:

{
    "uses_lightning": <boolean_indicating_the_method_for_the_payment>
}

This indicates the payment method, either onchain or offchain via lightning.

Example (API version 3)

Request

curl --data '{"btc_dest_address": "1FhnVJi2V1k4MqXm2nHoEbY5LV7FPai7bb", \
    "amount": 0.1, "amount_currency": "BTC"}' -H "Content-Type: application/json" \
    --url https://xmr.to/api/v3/xmr2btc/order_create/

Response

{
    "state": "TO_BE_CREATED",
    "btc_amount": "0.1",  // string
    "btc_dest_address": "1FhnVJi2V1k4MqXm2nHoEbY5LV7FPai7bb",
    'uses_lightning': False,
    "uuid": "xmrto-XCZEsu"
}

Querying order status

Request

Issue a POST request to to query the status of a given order supplying the following parameters.

Both versions of the API require:

{
    "uuid": <unique_order_identifier_as_12_character_string>
}

Response

Please see API version 3 for more details.

Both versions of the API return:

{
    "state": <order_state_as_string>,
    "btc_amount": <requested_amount_in_btc>,
    "btc_amount_partial": <partial_amount_in_btc>,
    "btc_dest_address": <requested_destination_address_as_string>,
    "uuid": <unique_order_identifier_as_12_character_string>
    "btc_num_confirmations_threshold": <btc_num_confirmations_threshold_as_integer>,
    "created_at": <timestamp_as_string>,
    "expires_at": <timestamp_as_string>,
    "seconds_till_timeout": <seconds_till_timeout_as_integer>,
}

Note

API version 2 returns btc_amount and btc_amount_partial as float. API version 3 returns btc_amount and btc_amount_partial as string.

With API version 3 some keys have been removed (Mostly due to the fact that we do not support integrated addresses anymore.):
  • xmr_receiving_address

  • xmr_receiving_integrated_address

  • xmr_required_payment_id_long

  • xmr_required_payment_id_short

  • xmr_required_amount (deprecated)

  • btc_num_confirmations_before_purge in favour of btc_num_confirmations_threshold only.

With API version 3 some keys have been renamed to more general names:

API version 2

API version 3

xmr_amount_total <float>

incoming_amount_total <string>

xmr_amount_remaining <float>

remaining_amount_incoming <string>

xmr_num_confirmations_remaining

incoming_num_confirmations_remaining

xmr_price_btc <float>

incoming_price_btc <string>

xmr_receiving_subaddress

receiving_subaddress

xmr_recommended_mixin

recommended_mixin

Additionally, with API version 3 you will receive:

{
    "uses_lightning": <boolean_indicating_the_method_for_the_payment>,
    "payments": [<payment_objects>]
}

uses_lightning indicates the payment method, either onchain or offchain via lightning.

The payment_object is new with API version 3. Some keys have been restructured (For On Chain payments.):

API version 2

API version 3

btc_transaction_id

payments - empty ([]) if order not paid - otherwise <payment_objects>

btc_num_confirmations

The available payment methods for the method field of a payment_object are On Chain and Lightning Network.

Please see API version 3 for more details.

Example (API version 3)

Request

curl --data '{"uuid": "xmrto-VkT2yM"}' -H "Content-Type: application/json" \
    --url https://xmr.to/api/v3/xmr2btc/order_status_query/

Response

{
    "incoming_price_btc": "0.01760396",
    "uuid": "xmrto-XCZEsu",
    "state_str": "BTC_SENT",
    "btc_amount": "0.1",  // string
    "btc_amount_partial": "0",  // string
    "btc_dest_address": "1FhnVJi2V1k4MqXm2nHoEbY5LV7FPai7bb",
    "receiving_subaddress": "83BGzCTthheE2KxNTBPnPJjJUthYPfDfCf3ENSVQcpga8RYSxNz9qCz1qp9MLye9euMjckGi11cRdeVGqsVqTLgH8w5fJ1D",
    "created_at": "2017-07-01T08:11:27Z"
    "expires_at": "2017-07-01T08:26:27Z",
    "seconds_till_timeout": 857,
    "incoming_amount_total": "5.68",
    "remaining_amount_incoming": "5.68",
    "incoming_num_confirmations_remaining": -1,
    "recommended_mixin": 4,
    "btc_num_confirmations_threshold": 144,
    "payments": [
        {
            "method": "On Chain",
            "amount": "0.001",
            "num_confirmations": 0,
            "tx_id": "320e501c29778ce280f69ba3d1564f0e890f478752cd3b59d36e2801ccb972f2"
        }
    ],
    "uses_lightning": False
}

Querying order price

Request

Issue a POST request to query the price of a BTC/XMR amount.

With API version 2 there are separate parameters when creating orders by specifying the order amount in BTC or XMR, respectively:

{
    "btc_amount": <requested_amount_in_btc_as_float>
}

or

{
    "xmr_amount": <requested_amount_in_xmr_as_float>
}

With API version 3 the parameters look like this:

{
    "amount": <requested_amount_as_float>,
    "amount_currency": <currency_of_the_requested_amount_as_string>
}

The available currencies for the amount_currency field are BTC and XMR.

Response

Both versions of the API return:

{
    "btc_amount": <requested_amount_in_btc>,
}

Note

API version 2 returns btc_amount as float. API version 3 returns btc_amount as string.

With API version 3 some keys have been renamed to more general names:

API version 2

API version 3

xmr_amount_total <float>

incoming_amount_total <string>

xmr_num_confirmations_remaining

incoming_num_confirmations_remaining

xmr_price_btc <float>

incoming_price_btc <string>

Example (API version 3)

Request

Imagine we want to check the recent price for an order including the payment of 0.15 BTC.

Request

curl --data '{"amount": 0.15, "amount_currency": "BTC"}' \
    -H "Content-Type: application/json" \
    https://xmr.to/api/v3/xmr2btc/order_check_price/

Imagine we want to check the recent price for an order including the payment of 10 XMR.

curl --data '{"amount": 10, "amount_currency": "XMR"}' \
    -H "Content-Type: application/json" \
    https://xmr.to/api/v3/xmr2btc/order_check_price/

Response

The response gives the current price for the order (when paying 0.15 BTC):

{
    "btc_amount": "0.15",  // string
    "incoming_amount_total": "21.4185",  // string
    "incoming_num_confirmations_remaining": 1,
    "incoming_price_btc": "0.00700329"  // string
}

In the above example, the order including the payment of 0.15 BTC would require the user to pay 21.4185 XMR.

The response gives the current price for the order (when paying 10 XMR):

{
    "btc_amount": "0.0701264",  // string
    "incoming_amount_total": "10",  // string
    "incoming_num_confirmations_remaining": 0,
    "incoming_price_btc": "0.00701264"  // string
}

In the above example, the order including the payment of 10 XMR would result in an order that eventually pays 0.0701264 BTC to the destination address.