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