---
name: beancount-ledger
description: Turn the user's bank / credit-card / WeChat / Alipay statements (PDF, screenshots, CSV, xlsx) and bookkeeping sentences ("lunch 35 with WeChat", "Xiaojuan's transfers are rent") into Beancount entries via Aki Agent API. Use when the user wants to record expenses, import a statement, or set a rule for how transactions are categorised.
---

# Beancount ledger via Aki Agent API

API: `https://api.akifukaku.com` · auth: `Authorization: Bearer $AKI_API_KEY` · schema: https://api.akifukaku.com/openapi.json

## Setup (once)

If `AKI_API_KEY` is not set: `curl -s -X POST https://api.akifukaku.com/v1/keys -H 'Content-Type: application/json' -d '{"label":"my-agent"}'`.
Save the returned `key` where the user keeps secrets (it is shown once). It comes with a small trial credit.
When credits run out (HTTP 402 `insufficient_credits`): `POST /v1/credits/topup {"amount_usd": 5}` and give the user the returned `url` (card or USDC).

## Recording what the user says

1. Write each thing the user says as one line of Ledger Intent Format (https://api.akifukaku.com/docs/intents.md):
   - spending / income → `{"op":"txn","date":"YYYY-MM-DD","amount":-35,"category":"午饭","account":"微信","payee":"..."}` (negative = money out)
   - "X is always Y" → `{"op":"rule","payee":"小娟","direction":"in","category":"房租"}`
   - "零钱 means WeChat" → `{"op":"alias","name":"零钱","account":"微信"}`
2. Read the user's ledger directory: `main.bean`, the files it includes, and `wearcal.json` (if present).
3. `POST https://api.akifukaku.com/v1/ledger/convert` with `{"intents": "<the lines>", "ledger": {"files": {"main.bean": "...", "wearcal.json": "..."}}}`.
4. Append `bean` to the user's ledger (e.g. the current year's file), write `config_json` (if not null) to `wearcal.json`.
5. Tell the user how many entries were added and list the ones flagged `!` (`counts.pending`) for them to confirm.

## Importing a statement

Same call with `"parts": [{"mime": "application/pdf", "data": "<base64>"}]` (or up to 6 screenshots, or one CSV / xlsx;
generic CSV needs `"account": "<which account>"`). Already-recorded transactions are skipped (`counts.duplicates`).
If `date_check.reliable` is false, tell the user to double-check dates.

## Rules

- Never invent amounts or dates; ask the user when unclear.
- Show the user what will be appended before writing to their files, unless they asked you to just do it.
- Nothing is stored server-side; the user's ledger stays theirs.
