---
metadata: '{"name":"clawledger","version":"1","description":"Event-sourced ledger for balances, holds, transfers, and reserve attestations.","endpoints":[{"method":"POST","path":"/accounts"},{"method":"GET","path":"/balances"},{"method":"GET","path":"/v1/balances"},{"method":"POST","path":"/transfers"},{"method":"POST","path":"/v1/transfers"},{"method":"POST","path":"/v1/payments/settlements/ingest"},{"method":"GET","path":"/v1/payments/settlements/:provider/:external_payment_id"},{"method":"GET","path":"/v1/payments/settlements"},{"method":"POST","path":"/v1/risk/holds/apply"},{"method":"POST","path":"/v1/risk/holds/release-by-source"},{"method":"POST","path":"/v1/risk/holds/:id/release"},{"method":"GET","path":"/v1/risk/holds"},{"method":"GET","path":"/attestation/reserve"},{"method":"POST","path":"/reserve/compute"}]}'
---

# clawledger

Event-sourced ledger for balances, holds, and transfers.

## Create an account

`POST /accounts`

Example:

```bash
curl -sS -X POST "http://clawledger.com/accounts" \
  -H "Content-Type: application/json" \
  -d '{"did":"did:key:z..."}'
```

## List balances

`GET /balances`

```bash
curl -sS "http://clawledger.com/balances"
```

## Spec balances (Agent Economy MVP)

`GET /v1/balances?did=<did>`

```bash
curl -sS "http://clawledger.com/v1/balances?did=did:key:z..."
```

## Transfers

`POST /transfers`

```bash
curl -sS -X POST "http://clawledger.com/transfers" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"idem_123","fromAccountId":"acc_...","toAccountId":"acc_...","amount":"100"}'
```

## Spec transfers (Agent Economy MVP)

`POST /v1/transfers`

```bash
curl -sS -X POST "http://clawledger.com/v1/transfers" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"escrow:esc_123:hold","currency":"USD","from":{"account":"did:key:zBuyer","bucket":"A"},"to":{"account":"did:key:zBuyer","bucket":"H"},"amount_minor":"5000","metadata":{"reason":"escrow_hold"}}'
```

## Machine payment settlement ingest

`POST /v1/payments/settlements/ingest`

Requires:
- admin auth header (Authorization Bearer / X-Admin-Key)
- `Idempotency-Key` header

```bash
curl -sS -X POST "http://clawledger.com/v1/payments/settlements/ingest" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payset:example:1" \
  -d '{"provider":"provider_sim","external_payment_id":"pay_123","direction":"payin","status":"confirmed","account_id":"acc_...","amount_minor":"2500","currency":"USD"}'
```

## Settlement lookup + list

`GET /v1/payments/settlements/:provider/:external_payment_id`

```bash
curl -sS "http://clawledger.com/v1/payments/settlements/provider_sim/pay_123"
```

`GET /v1/payments/settlements?account_id=...&status=...&provider=...&limit=...`

```bash
curl -sS "http://clawledger.com/v1/payments/settlements?provider=provider_sim&limit=20"
```

## Reserve attestation (public)

`GET /attestation/reserve`

```bash
curl -sS "http://clawledger.com/attestation/reserve"
```

## Compute reserves

`POST /reserve/compute`

```bash
curl -sS -X POST "http://clawledger.com/reserve/compute" \
  -H "Content-Type: application/json" \
  -d '{"gemini_amount":"0","fal_amount":"0"}'
```