# Transfer between wallets (/docs/api-reference/wallets/transfer)

`POST /v1/wallets/transfer`

Moves funds from one of the partner's wallets to another, converting between their currencies.

`amount` is in the source wallet's currency and has at most that currency's ISO 4217 decimals (none
in `KRW` or `JPY`, three in `KWD`, two in most); more decimals return `400` with code
`10001` and `INVALID_VALUE` at `amount`, whose `message` names the decimals allowed,
such as `An amount in JPY cannot have decimals.` The destination receives the amount converted at
the current rate, rounded to its own currency's decimals. Returns the `transferId`, the sent
and received amounts and currencies, the `conversionRate` and the `transferDate`. Both wallets
record an `exchange` transaction.
            
The two wallets must differ, and the amount must be above zero; otherwise the call returns `400` with
code `10001`. An unknown wallet returns `404` with code `10004`. A source wallet that cannot
pay the amount now returns `409` with code `10005` (`CONFLICT`) and
`details[0] = { path: "fromWalletId", reason }`: `INSUFFICIENT_BALANCE` when its balance is too
low, `WALLET_BLOCKED` while its spending is blocked. The same request can succeed once that changes.
            
Requires an `Idempotency-Key` header (a UUID). Repeating a completed transfer with the same key and body
returns `200` with that transfer, the same `transferId` and amounts, and moves no money again. One
still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a
`Retry-After` header, and a different body with the same key `409` with code `12001`. A
request that ended in an error can be sent again with the same key and body.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |

## Request body

- `application/json`: `WalletTransferRequest`
- `text/json`: `WalletTransferRequest`
- `application/*+json`: `WalletTransferRequest`

## Responses

### 200

OK

- `text/plain`: `WalletTransfer`
- `application/json`: `WalletTransfer`
- `text/json`: `WalletTransfer`

### 400

Invalid partner request or model validation failure.

- `application/json`: `ErrorResponse`

### 401

Unauthorized

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 403

Forbidden

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 404

Not Found

- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`

### 409

The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.

- `application/json`: `ErrorResponse`

### 429

Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.

- `application/json`: `ErrorResponse`

### 503

Idempotency state is temporarily unavailable; retry the same request and key.

- `application/json`: `ErrorResponse`

The full schemas are in the OpenAPI specification at /openapi.json.