---
title: "Convert or Move Money Between Balances"
method: POST
path: "/v2/profiles/{profileId}/balance-movements"
tags: ["balance"]
---

# Convert or Move Money Between Balances

`POST /v2/profiles/{profileId}/balance-movements`

This endpoint allows conversion and movement of funds between balance accounts.

**Convert across balance accounts:**
Convert funds between two `STANDARD` balance accounts in different currencies. Requires a quote created with `"payOut": "BALANCE"`.

**Move money between balances:**
- Add money to a same-currency jar (move from `STANDARD` to `SAVINGS` without conversion)
- Add money to another-currency jar (convert money using a quote)
- Withdraw money from a jar (move from `SAVINGS` to `STANDARD` without conversion)

Either `amount` or `quoteId` is required. Use `quoteId` for cross-currency movements.

## Path parameters

- `profileId` integer, required

## Headers

- `X-idempotence-uuid` string, uuid, required
- `X-External-Correlation-Id` string, uuid

## Request body

- object — Request body for balance movements (conversion or transfer).
  - `quoteId` string, uuid — Quote ID. Required for cross-currency movements. Quote must be created with `payOut: BALANCE`.
  - `sourceBalanceId` integer — Source balance ID. Required when moving between balances (with targetBalanceId).
  - `targetBalanceId` integer — Target balance ID. Required when moving between balances (with sourceBalanceId).
  - `amount` object — Amount to move. Required for same-currency movements. Either `amount` or `quoteId` must be provided.
    - `value` number — Amount value.
    - `currency` string — Currency code (ISO 4217 Alphabetic Code).

## Response `201`

Created - Movement completed successfully.

- object — Response from a balance movement operation.
  - `id` integer — Movement transaction ID.
  - `type` 'DEPOSIT' | 'WITHDRAWAL' | 'CONVERSION' — Type of movement.
  - `state` 'PENDING' | 'COMPLETED' | 'CANCELLED' | 'REVERSED' — State of the movement.
  - `balancesAfter` object[] — Balance states after the movement.
    - `id` integer — Balance ID.
    - `value` number — Balance value after movement.
    - `currency` string — Currency code.
  - `creationTime` string, date-time — When the movement was created.
  - `sourceAmount` object — Source amount of the movement.
    - `value` number
    - `currency` string
  - `targetAmount` object — Target amount of the movement.
    - `value` number
    - `currency` string
  - `rate` number — Exchange rate applied to the conversion.
  - `feeAmounts` object[] — Fee amounts charged for the movement.
    - `value` number
    - `currency` string
  - `steps` object[] — Steps involved in the movement.
    - `id` integer — Step ID.
    - `type` string — Step type.
    - `creationTime` string, date-time — When the step was created.
    - `balancesAfter` object[]
      - `value` number
      - `currency` string
    - `sourceAmount` object
      - `value` number
      - `currency` string
    - `targetAmount` object
      - `value` number
      - `currency` string
    - `fee` object
      - `value` number
      - `currency` string
    - `rate` number — Exchange rate applied.

## Other responses

- `429` — Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.

---

[API](https://skmtc.net/wise/apis/platform-api.md) · [All operations](https://skmtc.net/wise/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wise/platform-api/versions/4907a1d269ab/schema)