Close Wallet

Close a wallet permanently.

Endpoint

POST /api/v3/fermata/wallet/close

Description

Closes a wallet. This is a terminal state -- only a final withdrawal to zero balance is allowed after closing. Admin only.

Authentication

Requires Bearer token authentication with admin role.

Authorization: Bearer {access_token}

Request Body

Field	Type	Required	Description
walletId	string	Yes	Wallet ID to close

Response

Returns the updated wallet object with status: "CLOSED".

Usage

import requests

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

response = requests.post(
    "https://cadenza-api.algo724.com/api/v3/fermata/wallet/close",
    headers=headers,
    json={"walletId": "880e8400-e29b-41d4-a716-446655440000"}
)

wallet = response.json()["data"]
print(f"Wallet {wallet['walletId']} is now {wallet['status']}")

curl -X POST https://cadenza-api.algo724.com/api/v3/fermata/wallet/close \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"walletId": "880e8400-e29b-41d4-a716-446655440000"}'

Example Response

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

Error Responses

HTTP Code	Error	Description
400	Invalid request	Wallet is already closed or has non-zero balance
401	Unauthorized	Invalid or expired access token
403	Forbidden	Requires admin role
404	Not found	Wallet not found

Example Error

{
  "data": null,
  "success": false,
  "errno": -140007,
  "error": "Cannot close wallet with non-zero balance"
}

Notes

• Closing is permanent -- a closed wallet cannot be reopened
• Only a final withdrawal to zero balance is allowed after closing
• Transaction history is preserved for audit (7-year retention)
• Both ACTIVE and FROZEN wallets can be closed