Create Wallet

Create a new wallet in the Fermata ledger.

Endpoint

POST /api/v3/fermata/wallet/create

Description

Creates a new client wallet under the caller's trading account. Client wallets hold multi-currency balances and participate in double-entry settlement for RFQ trades.

Authentication

Requires Bearer token authentication.

Authorization: Bearer {access_token}

Request Body

Field	Type	Required	Description
nickname	string	No	Nickname for the new wallet

Response

Returns the created wallet object.

Field	Type	Description
walletId	string	Wallet ID (same as the backing trading account ID)
walletType	string	Wallet type (CLIENT)
status	string	Wallet status (ACTIVE)
allowNegative	boolean	Whether negative balances are allowed
metadata	object	Additional attributes
createdAt	integer	Creation timestamp (milliseconds)
updatedAt	integer	Last update timestamp (milliseconds)

Usage

import requests

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

response = requests.post(
    "https://cadenza-api.algo724.com/api/v3/fermata/wallet/create",
    headers=headers,
    json={"nickname": "Trading Wallet"}
)

wallet = response.json()["data"]
print(f"Wallet created: {wallet['walletId']}")

curl -X POST https://cadenza-api.algo724.com/api/v3/fermata/wallet/create \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"nickname": "Trading Wallet"}'

Example Response

{
  "data": {
    "walletId": "880e8400-e29b-41d4-a716-446655440000",
    "walletType": "CLIENT",
    "status": "ACTIVE",
    "allowNegative": false,
    "metadata": {
      "nickname": "Trading Wallet"
    },
    "createdAt": 1711929600000,
    "createdAtDateTime": "2025-04-01T00:00:00.000Z",
    "updatedAt": 1711929600000,
    "updatedAtDateTime": "2025-04-01T00:00:00.000Z"
  },
  "success": true,
  "errno": 0,
  "error": null
}

Error Responses

HTTP Code	Error	Description
400	Invalid request	Invalid parameters
401	Unauthorized	Invalid or expired access token
403	Forbidden	Insufficient permissions

Example Error

{
  "data": null,
  "success": false,
  "errno": -140001,
  "error": "Failed to create wallet"
}

Notes

• Each user gets a default client wallet on connection to a dealer
• Additional wallets can be created for profile segregation or accounting
• Client wallets do not allow negative balances
• The wallet consists of two Formance sub-accounts: {walletId}:available and {walletId}:locked