Wallets

A wallet is where money lives: a bank account, cash, a credit card, or mobile money. Every transaction belongs to a wallet. All routes require a bearer token and live under /api/v1.

Endpoints

Method	Path	Action
GET	/api/v1/wallets	List wallets
POST	/api/v1/wallets	Create a wallet
GET	/api/v1/wallets/{id}	Show one wallet
PUT	/api/v1/wallets/{id}	Update a wallet
DELETE	/api/v1/wallets/{id}	Delete a wallet

Fields

Field	Type	Required	Notes
name	string	yes	Up to 255 characters.
type	string	yes	bank, cash, credit_card, or mobile.
currency	string	yes	Three-letter currency code.
description	string	no	Free text.
balance	number	no	Numeric balance.
icon	string	no	Icon value.
icon_type	string	no	Required with icon: icon, image, or emoji.
client_id	string	no	Client-generated ID, {device_uuid}:{entity_uuid}.
created_at	string	no	ISO 8601.

Create

curl -X POST https://api.your-domain.example/api/v1/wallets \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cash",
    "type": "cash",
    "currency": "USD"
  }'

Response shape

{
  "success": true,
  "message": "Wallet created",
  "data": {
    "id": 1,
    "name": "Cash",
    "type": "cash",
    "description": null,
    "currency": "USD",
    "balance": 0,
    "icon": {
      "id": 12,
      "path": "wallet.png",
      "type": "image"
    },
    "stats": {
      "total_income": 0,
      "total_expense": 0
    },
    "client_generated_id": "device-uuid:entity-uuid",
    "last_synced_at": "2026-06-14T09:12:00.000000Z"
  }
}

The stats block carries the wallet’s total income and expense. The icon block describes an attached icon, image, or emoji.