---
title: "Transfer funds between wallets"
method: POST
path: "/wallet/transfer"
tags: ["Wallet"]
---

# Transfer funds between wallets

`POST /wallet/transfer`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/wallet/transfer`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/masspay/apis/masspay-api/docs/wallet/transfer/post.ts> (a function with typed inputs; its response is checked against the schema)

This **POST** endpoint transfers funds immediately from a source wallet to a destination wallet. <br> The `source_token` must refer to a wallet owned by the authenticated client (either a client wallet token or a user wallet token belonging to the client). <br> The `destination_token` can refer to any user wallet in the system, or to another client wallet that is linked to this client (e.g. a subclient or sister-client relationship — transfers to unrelated client wallets are not permitted). <br> Transfers between wallets of different currencies are supported; an FX exchange rate will be applied automatically. <br> Transfers are executed immediately upon request and are not reversible.

## Query parameters

- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- WalletTransferReq: Request body for transferring funds between wallets.
  - `source_token` string, required: Token representing the source wallet. Must be a wallet owned by the authenticated client (client wallet token or user wallet token belonging to this client).
  - `destination_token` string, required: Token representing the destination wallet. Can be any user wallet in the system or a linked client wallet (subclient or sister-client). Transfers to unrelated client wallets are not permitted.
  - `amount` number, required: Amount to transfer, denominated in the source wallet's currency. Up to 5 decimal places; a value with more is rejected.
  - `client_transfer_id` string: Optional client-provided identifier for this transfer. Useful for idempotency and reconciliation.
  - `notes` string: Optional human-readable note or description for this transfer.
  - `metadata` object: Optional arbitrary key-value metadata to attach to the transfer.

## Response `201`

Successfully created.

- WalletTransferResp: Response returned after a successful wallet-to-wallet transfer.
  - `transfer_token` string, required: Unique token identifying this transfer (load prefix, since a transfer is recorded as a ledger load).
  - `source_token` string, required: Token of the source wallet.
  - `destination_token` string, required: Token of the destination wallet.
  - `source_amount` number, required: Amount debited from the source wallet, in the source currency.
  - `destination_amount` number, required: Amount credited to the destination wallet, in the destination currency. May differ from `source_amount` when an FX conversion is applied.
  - `source_currency_code` string, required: Currency of the source wallet. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
  - `destination_currency_code` string, required: Currency of the destination wallet. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
  - `exchange_rate` number: FX exchange rate applied to convert between currencies. Present only when source and destination currencies differ.
  - `fee` number: Fee charged for the transfer, in the source currency.
  - `status` 'COMPLETED' | 'QUOTE', required: Status of the transfer. Transfers are immediate, so this will always be `COMPLETED` unless `dry_run` was requested.
  - `client_transfer_id` string: Client-provided identifier echoed back from the request.
  - `notes` string: Note or description echoed back from the request.
  - `metadata` object: Metadata echoed back from the request.
  - `created_at` string, date-time, required: Timestamp of when the transfer was created.

## Other responses

- `400`: Bad request.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not found.
- `405`: Method Not Allowed.
- `500`: Internal server error.
- `504`: Gateway Time-out.

## Changes

- **2026-11-03** `f9fa41b7c45c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/wallet/transfer/post.md)

---

[API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)