# Clams REST API Guide | For Developers & Coding Agents

> Developer and coding agent guide to the Clams Server REST API. Bitcoin accounting with auth, wallet connections, syncing, and reports.

Published 2026-02-18 at https://clams.tech/blog/building-with-the-clams-api/

The [Clams Server](/server/) exposes a REST API that lets you build Bitcoin accounting into your own tools. Automate tax reporting, build portfolio dashboards, or let a coding agent manage your books. This post walks through the full workflow, from authenticating to pulling reports. The full API reference is available at [clams.tech/docs/api](/docs/api/).

**Contents:**<br>
[Authentication](#authentication)<br>
[Creating a Workspace](#creating-a-workspace)<br>
[Setting Up a Profile](#setting-up-a-profile)<br>
[Connecting Wallets](#connecting-wallets)<br>
[Syncing](#syncing)<br>
[Real-Time Updates](#real-time-updates)<br>
[Processing Journals](#processing-journals-required-before-reports)<br>
[Metadata and Annotations](#metadata-and-annotations)<br>
[Reports](#reports)<br>
[Tooling Tips](#tooling-tips)

Before anything else, [download and run Clams Server](/server/). Two prerequisites for everything below: your server is set up (`clams server setup`), and you sign in as a Clams user. Workflows that touch your books (connecting wallets, syncing, importing, processing journals, generating reports) require it.

If you're wiring up Clams from Claude Code, Codex, Open Code, or any other agent framework, everything here applies. The curl commands are copy-pasteable and both the Auth and Server API docs are designed to be machine-readable.

**Setting up your agent?** Point it at these resources in order:

1. **[Auth quickstart](/docs/auth/authentication.md)**: plain markdown that explains how the auth layer works. It's the fastest way for an LLM to understand token flows, refresh semantics, and client credentials.
2. **[Auth API reference](/docs/auth/)**: full Swagger/OpenAPI spec for the auth server.
3. **[REST API reference](/docs/api/)**: full Swagger/OpenAPI spec for the Clams Server API.

## Authentication

The API uses Bearer tokens (EdDSA-signed JWTs) issued by the Clams auth server at **auth.clams.tech**. You don't need to run the auth server yourself. We host it.

The basic flow: log in via a browser, exchange the resulting token for an audience-scoped access token and refresh token, then refresh as needed. The access token goes in the **Authorization** header on every API call. The [auth quickstart](/docs/auth/authentication.md) walks through each step with curl commands.

Key things to know:

- **Access tokens** expire in 5 minutes. If you're calling the API directly, refresh is your responsibility.
- **Refresh tokens** are opaque, 90-day TTL, and single-use: every refresh returns a new one, and presenting an old one revokes the entire session. Always persist the newest token. When the 90-day TTL expires, you'll need to re-authenticate via the browser login flow.
- **Audiences**: when requesting a token, you specify an audience. Use **svc** for the Clams Server API, **rates** for exchange rates, or **feedback** for the feedback endpoint. Most of what this guide covers uses **svc**.
- **Client credentials** (provisioned via POST /v1/oauth-clients) mint tokens for the **rates** and **feedback** audiences only. There is no machine-to-machine path to **svc**: everything that touches your books runs as a signed-in user.

**Give your automation its own session.** Don't read or rewrite the CLI's stored `credentials.json`: refresh tokens are single-use, so a script and the CLI refreshing from the same session will invalidate each other and can revoke the session outright. Instead, log in once for the automation context and keep its tokens separate:

1. Start a login session: `POST https://auth.clams.tech/v1/web/login/session/start`. The response includes a `browser_url`, a `login_session_id`, and a `poll_secret`.
2. Open `browser_url` and sign in with Google, Apple, or an email magic link.
3. Poll `GET /v1/web/login/session/{login_session_id}` with the `x-clams-login-session-poll-secret` header until it returns `"status": "completed"` and a short-lived `access_token`.
4. Exchange it for svc tokens: `POST /v1/token/exchange` with the access token as `subject_token` and `"audience": "svc"`.
5. Store the returned refresh token in your own secrets store. Refresh with `POST /v1/token` (`"grant_type": "refresh_token"`, `"audience": "svc"`), saving the rotated token every time.

The [auth quickstart](/docs/auth/authentication.md) has copy-pasteable curl commands for each step, and the [Auth API reference](/docs/auth/) documents the full request fields, including the billing fields the exchange endpoint expects.

**Postman users:** You can automate token refresh using a <a href="https://learning.postman.com/docs/tests-and-scripts/write-scripts/pre-request-scripts/" target="_blank" rel="noopener noreferrer">pre-request script</a> on your collection. The script calls the refresh endpoint before each request and stores the new token in an environment variable. No more manual 401 cycling.

Every curl command below assumes **$TOKEN** and **$CLAMS_BASE_URL** are set.

Set your base URL before making any API calls. If you've deployed Clams Server to a remote host, replace this with your server's URL (e.g. https://api.your-domain.com).

```bash
export CLAMS_BASE_URL="http://127.0.0.1:8080"
```

## Creating a Workspace

A workspace is your top-level organizational unit. Profiles live inside workspaces and each profile isolates its own user data. Create a workspace first:

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $CLAMS_BASE_URL/v1/workspaces \
  -d '{"label": "my-workspace"}'
```

Grab the **id** from the response. You'll need it for everything that follows.

## Setting Up a Profile

A profile holds your connections, settings, and data. The setup endpoint combines four separate calls (create profile, create onchain config, select it, set profile settings) into one:

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/setup \
  -d '{
    "profile_label": "main",
    "fiat_currency": "USD",
    "gains_algorithm": "FIFO",
    "tor_proxy": null,
    "onchain_label": "my-electrum",
    "onchain_kind": "Electrum",
    "onchain_url": "tcp://your-electrum-server:50001",
    "rpc_cookie": null,
    "rpc_user": null,
    "rpc_password": null,
    "select_as_default": true
  }'
```

**onchain_kind types:**
- Electrum
- Esplora
- BitcoinRpc (requires rpc_user/rpc_password or rpc_cookie)

**Tor users:** If your node is on Tor (Start9, Umbrel, etc.), you'll need to set the **tor_proxy** field. The port depends on how you run Tor: standalone Tor daemon defaults to **127.0.0.1:9050**, and Tor Browser defaults to **127.0.0.1:9150**.

If you need granular control, you can make the four calls individually: create profile, create onchain config, select it, set profile settings. See the [API reference](/docs/api/) for each endpoint.

## Connecting Wallets

With a profile ready, add a connection. Most kinds (Descriptor, XPub, Address, etc.) require configuration at creation time. For a descriptor wallet:

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/connections \
  -d '{"label": "my-wallet", "kind": "Descriptor", "configuration": {"descriptor": "wpkh([fingerprint/84h/0h/0h]xpub.../0/*)"}}'
```

You can update a connection's configuration later with PATCH:

```bash
curl -s -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/connections/{connection_id} \
  -d '{"configuration": {"descriptor": "wpkh([fingerprint/84h/0h/0h]xpub.../0/*)"}}'
```

List your connections to confirm:

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/connections?limit=50"
```

**Connection kinds available at time of writing:**
- **CoreLn** — Core Lightning via Commando
- **Lnd** — LND via LNC pairing phrase or gRPC
- **Nwc** — Nostr Wallet Connect
- **Phoenixd** — phoenixd's HTTP API
- **XPub**, **Descriptor**, **Address** — watch-only Bitcoin chain scanning
- **LiquidDescriptor** — Liquid CT descriptors (requires a Liquid chain source)
- **Phoenix**, **River** — built-in CSV imports
- **Custom** — CSV imports with your own mapping

Each kind has its own configuration fields. See the [API reference](/docs/api/) for details on each. You can also list available kinds from the API directly:

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/connections/kinds"
```

## Syncing

Sync all connections for a profile:

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  $CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/connections/sync
```

This returns an **operation_id**. Check its status:

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  $CLAMS_BASE_URL/v1/operations/{operation_id}
```

The status will move through **Queued** → **Running** → **Succeeded**, **SucceededWithFailures**, or **Failed**. **SucceededWithFailures** means some connections synced while others hit errors — check the **failures** array in the result for details.

### Real-Time Updates

Instead of polling, you can connect to the SSE notifications stream:

```bash
curl -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/notifications/stream?operation_id={operation_id}"
```

Events arrive as JSON:

```json
{
  "operation_id": "...",
  "phase": "Progress",
  "level": "Info",
  "message": "Fetching transactions",
  "progress": { "current": 12, "total": 50 }
}
```

Useful if you're building a UI or want to trigger the next step automatically.

## Processing Journals (Required Before Reports)

**Syncing only imports raw records.** To turn them into journal entries (which power all the reports), you need to process journals separately. If you skip this step, reports will return empty or incomplete data.

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  $CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/journals/process
```

Unlike syncing, this call is synchronous — it returns a `JournalRunOutcome` directly with the number of quarantined events (if any). Run this after every sync before pulling reports.

## Metadata and Annotations

Once journals are processed, you can add notes, tags, and exclusions to journal events before pulling reports. First, list your journal events to grab an event ID:

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/journals/events?limit=10"
```

**Add a note:**

```bash
curl -s -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/metadata/records/{event_id}/note" \
  -d '{"note": "Office hardware purchase"}'
```

**Create a tag:**

```bash
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/metadata/tags" \
  -d '{"code": "business-expense", "label": "Business Expense"}'
```

The **code** is a canonical identifier (automatically lowercased). The **label** is the display name shown in UIs.

**Exclude an event from reports:**

```bash
curl -s -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/metadata/records/{event_id}/excluded" \
  -d '{"excluded": true}'
```

## Reports

With your data synced, journals processed, and any annotations in place, you can pull reports. The balance sheet and portfolio summary always return current state. Capital gains supports date range filtering.

**Balance sheet:**

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/reports/balance-sheet?limit=50"
```

**Portfolio summary:**

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/reports/portfolio-summary"
```

**Capital gains CSV** (with optional date range for tax reporting):

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/reports/capital-gains?start=2025-01-01T00:00:00Z&end=2025-12-31T23:59:59Z" \
  -o capital-gains-2025.csv
```

**Journal entries CSV:**

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CLAMS_BASE_URL/v1/workspaces/{workspace_id}/profiles/{profile_id}/reports/journal-entries" \
  -o journal-entries.csv
```

## Tooling Tips

**Readable output:** Pipe everything through **jq .** for formatted JSON.

**API docs:** Browse the full API reference at [clams.tech/docs/api](/docs/api/) and the auth API at [clams.tech/docs/auth](/docs/auth/).

**Postman:** Import both OpenAPI specs directly into Postman to get the full collection for each API. Just paste these URLs into Postman's import dialog:
- https://clams.tech/docs/auth/openapi.json
- https://clams.tech/docs/api/openapi.json

**Error format:** Errors return JSON with a **code**, **message**, and optionally **details** and **request_id**.

**Rate limiting:** The self-hosted server has concurrency limits (default 128 concurrent requests) and request timeouts (default 30s), both configurable via environment variables. CSV exports are limited to 2 concurrent downloads.

## Go Build Something

Clams v1 is out. We're actively improving the API based on what people build with it. If you run into issues or want to share what you're working on, use the built-in feedback endpoint (POST /v1/feedback) or reach out at [support@clams.tech](mailto:support@clams.tech).

Clams Team
