Request a Conversion Quote

The POST /currency_conversions/ method enables you to request a conversion quote. Before you can execute a conversion of funds of your working capital, you must request a quote, which presents the conversion rate offered and the number of assets to spend and receive if the quote is accepted.

Quotes expire in 20 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 ways: set the number of assets you want to convert or the number of assets you wish to receive. In either, you also specify the source and target currencies.

HTTP Request

POST https://sandbox.bitso.com/api/v3/currency_conversions

Header Parameters

You must specify the following authorization parameters in your request:

Parameter	Description	Required
`key`	See the section, Authorization	Yes
`signature`	See the section, Authorization	Yes
`nonce`	See the section, Authorization	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`	Ticker of the source currency. For example, mxn.	String	Yes
`to_currency`	Ticker of the target currency. For example, btc.	String	Yes
`receive_amount`	Number of funds you expect to receive as a product of the conversion, specified in the target currency.	String	No. See callout below
`spend_amount`	Number of funds you are willing to convert, specified in the source currency.	String	No. See callout below

🚧
Mutually exclusive parameters
In your request, you can specify either how much you want to convert (spend_amount) or how much you expect to receive as a product of the conversion (receive_amount). However, 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.

The next examples show the two ways you have to specify the amount in your request.

{
    "from_currency":"mxn",
    "to_currency":"usd",
    "receive_amount":"100"
}

{
    "from_currency":"mxn",
    "to_currency":"usd", 
    "spend_amount":"2000"
}

JSON Response Payload

The endpoint returns a JSON object representing a quote. This object includes the following fields:

Field Name	Description	Type
`book`	The book to use.	String
`created`	Creation epoch of the quote in milliseconds.	Number
`direction`	Indicates whether it is a buy or a sell.	String
`estimated slippage`	An estimation of the difference between the expected execution rate and the actual execution rate.	Object
`expires`	Expiration epoch of the quote in milliseconds.	Number
`from_amount`	Number of funds you are willing to convert specified in the source currency.	String
`from_currency`	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 app to occur at specific periods.	Object
`oid`	The order ID.	String
`padding`	The fee users pay for the conversion.	String
`rate`	The exchange rate Bitso offers for the conversion.	String
`rate_currency`	Ticker of the currency in which the conversion rate is expressed.	String
`status`	The conversion's state. Possible values: open, completed, and failed.	String
`to_amount`	Number of funds you expect to receive as a product of the conversion specified in the target currency.	String
`to_currency`	Ticker of the target currency.	String

The following response objects exemplify the JSON object returned:

{
    "success": true,
    "payload": {
        "id": "EOTMmUZG",
        "from_amount": "1866.09342781",
        "from_currency": "mxn",
        "to_amount": "100.00000000",
        "to_currency": "usd",
        "estimated_slippage": {
            "level": "normal",
            "message": "",
            "value": "0.00"
        },
        "created": 1678480752145,
        "expires": 1678480782145,
        "rate": "18.66",
        "rate_currency": "mxn",
        "padding": "0.008",
        "direction": "buy",
        "book": "xrp_mxn",
        "status": "open",
        "oid": "EOTMmUZG",
        "next_recurrent_events": {
            "DAILY": 1678567152145,
            "WEEKLY": 1679085552145,
            "MONTHLY": 1681155552145
        }
    }
}

{
    "success": true,
    "payload": {
        "id": "2OAZRmUN",
        "from_amount": "2000.00000000",
        "from_currency": "mxn",
        "to_amount": "107.16865318",
        "to_currency": "usd",
        "estimated_slippage": {
            "level": "normal",
            "message": "",
            "value": "0.00"
        },
        "created": 1678480873166,
        "expires": 1678480903166,
        "rate": "18.66",
        "rate_currency": "mxn",
        "padding": "0.008",
        "direction": "buy",
        "book": "xrp_mxn",
        "status": "open",
        "oid": "2OAZRmUN",
        "next_recurrent_events": {
            "DAILY": 1678567273166,
            "WEEKLY": 1679085673166,
            "MONTHLY": 1681155673166
        }
    }
}

The id variable included in the response object is the quote's identifier that you need to use in the execute-conversion call.