Transfer Between Wallets

Transfer assets between wallets.

Endpoint

POST /api/v3/fermata/wallet/transfer

Description

Transfers assets between wallets owned by the same user under the same dealer. This is a double-entry transaction recorded in the Formance Ledger.

Authentication

Requires Bearer token authentication.

Authorization: Bearer {access_token}

Request Body

Field	Type	Required	Description
sourceWalletId	string	Yes	Source wallet ID
destWalletId	string	Yes	Destination wallet ID
asset	string	Yes	Asset to transfer (e.g., USDT)
amount	string	Yes	Amount to transfer (decimal string, must be positive)

Response

Returns a simple success response.

Usage

import requests

headers = {"Authorization": f"Bearer {access_token}"}

response = requests.post(
    "https://cadenza-api.algo724.com/api/v3/fermata/wallet/transfer",
    headers=headers,
    json={
        "sourceWalletId": "880e8400-e29b-41d4-a716-446655440000",
        "destWalletId": "990e8400-e29b-41d4-a716-446655440001",
        "asset": "USDT",
        "amount": "5000.00"
    }
)

print(response.json())

curl -X POST https://cadenza-api.algo724.com/api/v3/fermata/wallet/transfer \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceWalletId": "880e8400-e29b-41d4-a716-446655440000",
    "destWalletId": "990e8400-e29b-41d4-a716-446655440001",
    "asset": "USDT",
    "amount": "5000.00"
  }'

Example Response

{
  "data": "ok",
  "success": true,
  "errno": 0,
  "error": null
}

Error Responses

HTTP Code	Error	Description
400	Invalid request	Missing parameters, insufficient balance, or same wallet
401	Unauthorized	Invalid or expired access token
403	Forbidden	Wallets not owned by caller
404	Not found	Wallet not found

Example Error

{
  "data": null,
  "success": false,
  "errno": -140004,
  "error": "Insufficient available balance: 3000.00 USDT < 5000.00 USDT"
}

Notes

• Both wallets must be owned by the same user
• Both wallets must be ACTIVE
• Source wallet must have sufficient available balance
• The transfer is atomic and recorded as a TRANSFER transaction in the ledger