Get a Conversion Status

Given that a conversion executes asynchronously, to know when the conversion fully completes, it is necessary to retrieve its status. The GET /currency_conversions/{quoteId} method enables you to retrieve the details of a conversion and its updated state. Then, after submitting the conversion quote, you can use this method to poll the quote and determine its status.

Conversions can be in one of three possible states:

OPEN: Initial state, Bitso's Conversion Engine is currently processing the conversion; it eventually changes to a final value.
COMPLETED: The conversion ended successfully; the funds are now in the target currency.
FAILED: The system could not complete the conversion; the funds remain in the original currency. You can retry by getting another quote.

HTTP Request

GET https://sandbox.bitso.com/api/v3/currency_conversions/{quoteId}

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

Path Parameters

You must specify the following path parameter in your request:

Parameter	Description	Required
`quoteId`	Identifies the quote you want to retrieve. The request-quote call returns it as `id`.	Yes

JSON Response Payload

The endpoint returns a JSON object representing the executed conversion. 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 identifier.	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 object exemplifies the JSON object returned:

{
   "success":true,
   "payload":{
      "id":"FNMNZDOj",
      "from_amount":"2000.00000000",
      "from_currency":"mxn",
      "to_amount":"107.23505969",
      "to_currency":"usd",
      "estimated_slippage":{
         "level":"normal",
         "message":"",
         "value":"0.00"
      },
      "created":1678483859671,
      "expires":1678483889671,
      "rate":"18.65",
      "rate_currency":"mxn",
      "padding":"0.008",
      "direction":"buy",
      "book":"btc_mxn",
      "status":"open",
      "oid":"FNMNZDOj",
      "next_recurrent_events":{
         "DAILY":1678570259671,
         "WEEKLY":1679088659671,
         "MONTHLY":1681158659671
      }
   }
}