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 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

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 creation epoch of the conversion in milliseconds.Number
expiresThe expiration epoch of the conversion 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_rateString
rateThe exchange rate used to complete the conversion.String
rate_currencyThe ticker of the currency in which the conversion rate is expressed.String
statusThe conversion's state. Possible values: open, 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