Wallet logo Wallet API Reference

Base URL: https://rest.budgetbakers.com/wallet

Full Specification: OpenAPI (Swagger UI) — all endpoints, schemas, and interactive testing

Authentication

All endpoints require an API token, obtained in the Web app (Premium plan required):

Authorization: Bearer <your_api_token>

Pagination

All User Data endpoints support pagination:

Parameter Default Max Description
limit 30 100 Items per page
offset 0 - Items to skip

Response includes nextOffset when more results are available.

Rate Limiting

API uses the Token Bucket Rate limiting algorithm, which allows short bursts of requests while enforcing an average rate over time.

Header Example Description
X-RateLimit-Limit 500 Maximum request capacity
X-RateLimit-Remaining 487 Remaining request capacity

Query Filter Prefixes

Some endpoints have query parameters that require filter prefixes in format: prefix.value

Example: amount=gte.100 → amount ≥ 100

Text Filters

Use prefix operators to filter text fields (e.g. note, payee fields).

Prefix Meaning Example
eq. Exact match payee=eq.Amazon
contains. Contains substring (case-sensitive) note=contains.Bill
contains-i. Contains substring (case-insensitive) note=contains-i.grocery

Text filters can be specified up to 2 times for AND logic. E.g. note=contains-i.grocery&note=contains-i.market

Range Filters

Used for numeric properties (e.g. amount) and datetime fields (recordDate, createdAt).

Prefix Meaning Example (numeric) Example (datetime)
eq. Equals amount=eq.100 createdAt=eq.2024-01-15T10:30:00Z
gt. Greater than amount=gt.100 createdAt=gt.2024-01-01T00:00:00Z
gte. Greater than or equal amount=gte.100 createdAt=gte.2024-01-01T00:00:00Z
lt. Less than amount=lt.500 createdAt=lt.2024-12-31T23:59:59Z
lte. Less than or equal amount=lte.500 createdAt=lte.2024-12-31T23:59:59Z
Date-only values

When date-only values (no time component) are provided, whole-day (in UTC) semantics apply.:

Filter Equivalent Meaning
gt.2025-01-14 gte.2025-01-15T00:00:00Z Starting from Jan 15
gte.2025-01-14 gte.2025-01-14T00:00:00Z Starting from Jan 14
lt.2025-01-15 lt.2025-01-15T00:00:00Z Before Jan 15
lte.2025-01-15 lt.2025-01-16T00:00:00Z Up to and including Jan 15
eq.2025-01-13 gte.2025-01-13T00:00:00Z&lt.2025-01-14T00:00:00Z Entire day of Jan 13

Range filters support up to 2 conditions (AND logic) using repeated parameters:

Comma-separated syntax is also accepted: amount=gte.100,lte.500

Data Synchronization

User data is synchronized from Wallet app. Changes made in the app may not appear immediately via API.

Initial Sync

Synchronization begins when you generate your first API key. Until the initial sync completes, requests return 409 Conflict:

{
  "error": "init_sync_in_progress",
  "message": "Data synchronization in progress. Please retry later.",
  "retry_after_minutes": 5
}

Ongoing Sync

After initial sync, data is always returned, but recent changes in user data may not appear immediately. These response headers indicate sync status:

Header Example Description
X-Last-Data-Change-At 2024-01-28T14:23:45Z Timestamp of last data modification
X-Last-Data-Change-Rev r1234 Revision counter. Compare values to detect changes.
X-Sync-In-Progress false If true, response is valid but more changes may follow shortly.

Agent Hints

Advisory information for AI agents. Hints can provide context about results, pagination, and rate limits.

Enable: Add agentHints=true to any request.

Type Severity When Generated
pagination.has_more instruction More results available (includes next page URL)
result.partial_match info Some requested IDs not found
result.empty info No records match filters
param.inferred info Filtering date bound auto-inferred
(relevant to recordDate in /records)
rate_limit.warning warning Approaching rate limit
data.recency info Queried data recently modified