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 /api/v4/currency_conversions/{conversion_id} method enables you to recover a conversion's details and its updated state. Then, after submitting the conversion quote for execution, you can use this method to poll the quote and determine its status.

Conversions can be in one of four possible states:

  • OPEN: This is the initial state. The service created the transaction and is awaiting execution. This state will eventually change to queued when the conversion starts executing.
  • QUEUED: Bitso's Conversion Engine is executing the transaction. A conversion usually remains in this state for no more than one second. However, in moments of high load, it could be longer but never higher than 10 seconds (production environment).
  • 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.

A conversion's normal flow is Open → Queued → Completed or Failed, and there is no way to bypass any status or speed up the transition to the next state. The Conversion Engine has mechanisms to monitor the transactions in the production environment continuously, and in case one becomes stuck, the Bitso team fixes it.

HTTP Request

Header Parameters

You must specify the following authentication parameters in your request:

ParameterDescriptionRequired
keySee the section, AuthenticationYes
signatureSee the section, AuthenticationYes
nonceSee the section, AuthenticationYes

Path Parameters

You must specify the following path parameter in your request:

ParameterDescriptionRequired
conversion_idIdentifies the conversion you want to retrieve. The execute-a-conversion-quote call returns it as oid.Yes

JSON Response Payload

A successful call returns a JSON object representing the executed conversion. The following response object exemplifies the JSON object returned:

{
    "success": true,
    "payload": {
        "id": "7316",
        "from_amount": "1854.21860516",
        "from_currency": "mxn",
        "to_amount": "100.00000000",
        "to_currency": "usd",
        "created": 1719862355209,
        "expires": 1719862385209,
        "rate": "18.54218605",
        "plain_rate": "18.36",
        "rate_currency": "mxn",
        "book": "xrp_mxn",
        "status": "completed"
    }
}

The response object fields have the following meaning:

Field NameDescriptionType
bookThe book used.String
createdThe conversion's creation epoch in milliseconds.Number
expiresThe conversion's expiration epoch in milliseconds.Number
from_amountThe amount converted specified in the source currency.String
from_currencyThe ticker of the source currency.String
idThe conversion's unique identifier.String
plain_rateThe market's exchange rate without the spread value added to rate.String
rateThe exchange rate Bitso offers users for the conversion.String
rate_currencyThe ticker of the currency in which the conversion rate is expressed.String
statusThe conversion's state. Possible values: open, queued, completed, and failed.String
to_amountThe amount received as a product of the conversion specified in the target currency.String
to_currencyThe ticker of the target currency.String