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:

Body Parameters

Body parameters must be JSON encoded and precisely the same as the JSON payload used to construct the signature:

🚧

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: