Request a Conversion Quote
The POST /api/v4/currency_conversions method enables you to request a conversion quote. Before you can execute a conversion of your working capital from one currency to another, you must request a quote, which presents, among others, the conversion rate offered, the amount to spend in the source currency, the amount to receive in the target currency, and the fee charged if the quote is accepted.
Quotes expire in 30 seconds. Hence, you must accept (execute) it within this period. When a quote expires, you can no longer run it and must request a new one.
You can request the quote in two different, mutually exclusive ways:
- Setting how much you want to convert (
spend_amount) from one currency to another. - Specifying how much you expect to receive (
receive_amount) as a product of the conversion.
In either, you also specify the source and target currencies.
HTTP Request
To request a conversion, complete the following HTTP request using the appropriate body parameters:
POST https://stage.bitso.com/api/v4/currency_conversions
Header Parameters
You must specify the following authentication parameters in your request:
| Parameter | Description | Required |
|---|---|---|
key | See the section, Authentication | Yes |
signature | See the section, Authentication | Yes |
nonce | See the section, Authentication | Yes |
Body Parameters
Body parameters must be JSON encoded and precisely the same as the JSON payload used to construct the signature:
| Parameter | Description | Type | Required |
|---|---|---|---|
from_currency | The ticker of the source currency. For example, mxn. | String | Yes |
to_currency | The ticker of the target currency. For example, btc. | String | Yes |
receive_amount | The amount you expect to receive as a result of the conversion, specified in the target currency. This value should be a positive number. | String | No. See callout below |
spend_amount | The amount you are willing to convert, specified in the source currency. This value should be a positive number. | String | No. See callout below |
Mutually exclusive parameters
Recall these amounts are mutually exclusive, so ensure you include only one of them in your request.
Supported currencies
For details on supported currencies, see the section, Currency Dictionary.
Request Examples
The next examples show the two ways the endpoint offers to specify the amount in your request.
{
"from_currency":"mxn",
"to_currency":"usd",
"receive_amount":"100"
}
{
"from_currency":"mxn",
"to_currency":"usd",
"spend_amount":"1000"
}
JSON Response Payload
A successful call returns a JSON object representing a conversion quote. The following response objects exemplify the JSON object returned:
{
"success": true,
"payload": {
"id": "zmAfx2rvNnv1Jn0Q",
"from_amount": "1854.21860516",
"from_currency": "mxn",
"to_amount": "100.00000000",
"to_currency": "usd",
"estimated_slippage": {
"value": "0.0000",
"level": "normal",
"message": ""
},
"created": 1719862339217,
"expires": 1719862369217,
"rate": "18.54",
"plain_rate": "18.36",
"rate_currency": "mxn",
"padding": "0.0098",
"book": "xrp_mxn",
"next_recurrent_events": {
"WEEKLY": 1720467139217,
"DAILY": 1719948739217,
"MONTHLY": 1722540739217
}
}
}
{
"success": true,
"payload": {
"id": "IJAdSHvtsyGSCnPq",
"from_amount": "1000.00000000",
"from_currency": "mxn",
"to_amount": "53.93125050",
"to_currency": "usd",
"estimated_slippage": {
"value": "0.0000",
"level": "normal",
"message": ""
},
"created": 1719956986165,
"expires": 1719957016165,
"rate": "18.54",
"plain_rate": "18.36",
"rate_currency": "mxn",
"padding": "0.0098",
"book": "xrp_mxn",
"next_recurrent_events": {
"DAILY": 1720043386165,
"WEEKLY": 1720561786165,
"MONTHLY": 1722635386165
}
}
}
The value of the id variable is the path parameter (quote_id) you need to use when executing-a-conversion-quote.
The fields included in the response object have the following meaning:
| Field Name | Description | Type |
|---|---|---|
book | The book to use. | String |
created | The quote's creation epoch in milliseconds. | Number |
estimated_slippage | An estimation of the difference between the expected execution rate and the actual execution rate. | Object |
expires | The quote's expiration epoch in milliseconds. | Number |
from_amount | The amount you are willing to convert specified in the source currency. | String |
from_currency | The ticker of the source currency. | String |
id | The quote's unique ID. | String |
next_recurrent_events | Indicates when the next conversions are to take place in milliseconds. Used when conversions are programmed in the Bitso application to occur at specific periods. | Object |
padding | The fee users pay for the conversion. | String |
plain_rate | The market's exchange rate without the spread value added to rate. | String |
rate | The exchange rate Bitso offers users for the conversion. | String |
rate_currency | The ticker of the currency in which the conversion rate is expressed. | String |
to_amount | The amount you expect to receive as a product of the conversion specified in the target currency. | String |
to_currency | The ticker of the target currency. | String |
Updated 3 days ago