home / skills / openclaw / skills / wallet-api

wallet-api skill

safe

/skills/andresubri/wallet-api

This skill helps you query Wallet API data for accounts, categories, records, budgets, and templates from BudgetBakers.

npx playbooks add skill openclaw/skills --skill wallet-api

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.7 KB

---
name: wallet-api
description: Interact with the BudgetBakers Wallet API for personal finance data. Use when the user needs to query accounts, categories, transactions (records), budgets, or templates from their Wallet app via the REST API. Requires WALLET_API_TOKEN environment variable.
---

# Wallet API Skill

Interact with the BudgetBakers Wallet personal finance API.

## Prerequisites

1. **Premium Wallet plan** required for API access
2. **API Token** from [web.budgetbakers.com/settings/apiTokens](https://web.budgetbakers.com/settings/apiTokens)
3. Set `WALLET_API_TOKEN` environment variable

## Quick Start

```bash
export WALLET_API_TOKEN="your_token_here"
./scripts/wallet-api.sh me
```

## API Reference

See [references/api-reference.md](references/api-reference.md) for:
- Authentication details
- Rate limiting (500 req/hour)
- Query filter syntax (text and range filters)
- Pagination parameters
- Data synchronization behavior
- Agent hints

## Available Commands

| Command | Description |
|---------|-------------|
| `me` | Current user info |
| `accounts` | List accounts |
| `categories` | List categories |
| `records` | List transactions |
| `budgets` | List budgets |
| `templates` | List templates |

## Query Parameters

All list endpoints support:
- `limit` (default 30, max 100)
- `offset` (default 0)

### Filter Examples

**Recent transactions:**
```bash
./wallet-api.sh records "recordDate=gte.2025-02-01&limit=50"
```

**Amount range:**
```bash
./wallet-api.sh records "amount=gte.100&amount=lte.500"
```

**Text search:**
```bash
./wallet-api.sh records "note=contains-i.grocery"
```

**Category + date:**
```bash
./wallet-api.sh records "categoryId=eq.<id>&recordDate=gte.2025-01-01"
```

### Filter Prefixes

| Prefix | Meaning |
|--------|---------|
| `eq.` | Exact match |
| `contains.` | Contains (case-sensitive) |
| `contains-i.` | Contains (case-insensitive) |
| `gt.` | Greater than |
| `gte.` | Greater than or equal |
| `lt.` | Less than |
| `lte.` | Less than or equal |

## Common Workflows

### Get Account Balances
```bash
./wallet-api.sh accounts
```

### List Categories for Organization
```bash
./wallet-api.sh categories
```

### Recent Spending
```bash
./wallet-api.sh records "recordDate=gte.2025-02-01&limit=100"
```

### Filter by Payee
```bash
./wallet-api.sh records "payee=contains-i.amazon"
```

## Data Sync Considerations

- Initial sync returns 409 Conflict — wait and retry
- Recent app changes may not appear immediately
- Check `X-Last-Data-Change-At` header for freshness

## Rate Limit Handling

Watch for:
- `429 Too Many Requests` when exceeding 500/hour
- `X-RateLimit-Remaining` header
- Add `agentHints=true` for rate limit warnings

Overview

This skill lets you interact with the BudgetBakers Wallet REST API to query accounts, categories, transactions (records), budgets, and templates from your Wallet app. It requires a Premium Wallet plan and a WALLET_API_TOKEN environment variable to authenticate. Use it to script queries, export data, or integrate personal finance data into other tools.

How this skill works

The skill calls Wallet API endpoints for me, accounts, categories, records, budgets, and templates using the provided API token. List endpoints support pagination (limit, offset) and flexible filter syntax (range, text, exact-match prefixes). It honors rate limit headers and exposes headers like X-Last-Data-Change-At for data freshness checks.

When to use it

Export recent transactions or account balances for reporting or backup.
Automate category or budget reviews and audits.
Search transactions by payee, amount range, category, or date.
Integrate Wallet data into spreadsheets, dashboards, or accounting scripts.
Debug synchronization or check latest data-change timestamps before analyses.

Best practices

Set WALLET_API_TOKEN as an environment variable and keep it secret.
Use pagination (limit, offset) to avoid large single requests; max limit is 100.
Apply filter prefixes (eq., contains-i., gte., lte., etc.) to narrow results.
Monitor X-RateLimit-Remaining and handle 429 responses with backoff.
Check X-Last-Data-Change-At header to ensure you’re using fresh data.

Example use cases

List all accounts and current balances for a monthly financial snapshot.
Fetch transactions since a given date to calculate recent spending by category.
Find transactions with a specific payee (case-insensitive) for refunds or disputes.
Export category list to re-create budgeting rules in another tool.
Query budgets and templates to automate budget performance reports.

FAQ

Do I need a paid plan to use the API?

Yes. API access requires a Premium Wallet plan and an API token from your Wallet settings.

How do I avoid hitting rate limits?

Watch X-RateLimit-Remaining, limit request frequency to under 500/hour, use pagination, and implement exponential backoff when receiving 429 responses.