# Convert balances

Converts balance from one currency to another. In the API you can either send `target_amount` or `source_amount` and the API will calculate the other amount for you.

Endpoint: POST /balance_conversions
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `source_currency` (string, required)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.
    Example: USD

  - `target_currency` (string, required)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.
    Example: EUR

  - `source_amount` (number, required)
    The amount you want to convert. A positive integer representing the smallest currency unit.  For example, if the amount is $299.00, then pass 29900 in this field.  In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990.  And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295. `Only one of `source_amount` or `target_amount` can be sent.`
    Example: 1000

  - `target_amount` (number, required)
    The amount you want to receive. A positive integer representing the smallest currency unit.  For example, if the amount is $299.00, then pass 29900 in this field.  In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990.  And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295. `Only one of `source_amount` or `target_amount` can be sent.`
    Example: 1000

## Request examples:

  - `Convert a fixed amount of USD into EUR` (unknown)

  - `Receive a fixed amount of EUR, paid for in USD` (unknown)

## Response 201:

  - `201` (unknown)
    Balance conversion created successfully

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier for the balance balance.
    Example: conv_6776d57dnbTWj

  - `from` (object)

  - `from.amount` (number)
    A positive integer representing the smallest currency unit.  For example, if the amount is $299.00, then pass 29900 in this field.  In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990.  And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.
    Example: 1000

  - `from.currency` (string)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.
    Example: USD

  - `mid_market_rate` (object)

  - `mid_market_rate.currency` (string)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.
    Example: USD

  - `mid_market_rate.rate` (number)
    Units of the currency converted to (`to.currency`) per one unit of the currency converted from (`from.currency`), rounded to 2 decimal places. `1.4` means 1 unit of the source currency converts to 1.40 of the target currency. `0` when no rate was recorded.
    Example: 1.4

  - `status` (string)
    The status of the balance conversion.
- `pending` — the conversion has been created and has not completed yet.
- `success` — the converted amount has been credited. Terminal.
- `failed` — the conversion did not complete. Terminal.
    Enum: "pending", "success", "failed"

  - `created_at` (string)
    When the balance conversion was created, as an ISO 8601 date-time in UTC.
    Example: 2021-01-01T00:00:00Z

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `error` (string)
    Enum: "Bad Request"

  - `message` (string)
    Error message.
    Example: You can only send source_amount or target_amount, not both.