Quickstart: a ledger in five calls

Two ways to authorize

Every Ledger endpoint is either paid via x402 or authorized by a capability token. Pick one:

• x402 — send no credential; the server returns 402 and you retry with a signed X-PAYMENT header. Best for agents that pay per call and hold no account.
• Capability token — an Ed25519-signed JWT (scopes: Reader / Writer / Owner) sent as Authorization: Bearer. Bypasses x402 entirely. Best for an agent with standing access. See the comparison.

Step 1 — create two accounts (Owner)

Account creation requires Owner scope. We make an asset account (your wallet) and a revenue account.

curl -X POST https://ledger-api.novadyne.ai/ledger/accounts \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -d '{"name":"Wallet","type":"asset"}'
# 201 {"id":1,"name":"Wallet","type":"asset","balance":0}

curl -X POST https://ledger-api.novadyne.ai/ledger/accounts \
  -H "Authorization: Bearer $OWNER_TOKEN" \
  -d '{"name":"Revenue","type":"revenue"}'
# 201 {"id":2,"name":"Revenue","type":"revenue","balance":0}

Step 2 — post a balanced transaction (Writer)

Record $50 of revenue. The two entries sum to zero, so the transaction balances.

curl -X POST https://ledger-api.novadyne.ai/ledger/transactions \
  -H "Authorization: Bearer $WRITER_TOKEN" \
  -d '{"date":"2026-06-16","description":"First fee",
       "entries":[{"account_id":1,"amount":5000},
                  {"account_id":2,"amount":-5000}]}'
# 201 {"id":1,"balanced":true,"entries":2}

Step 3 — read a trial balance (Reader)

curl https://ledger-api.novadyne.ai/ledger/reports/trial-balance \
  -H "Authorization: Bearer $READER_TOKEN"
# 200 {"total_debits":5000,"total_credits":5000,"balanced":true}

The same flow with x402 (no token)

Drop the Authorization header and the first call returns a 402 with payment requirements. Sign a USDC transfer for the quoted amount and retry with X-PAYMENT. An x402 client library handles the signing; conceptually:

curl https://ledger-api.novadyne.ai/ledger/reports/trial-balance
# 402 {"x402Version":1,"accepts":[{"network":"base","maxAmountRequired":"2000", ... }]}

# pay $0.002 in USDC, then:
curl https://ledger-api.novadyne.ai/ledger/reports/trial-balance -H "X-PAYMENT: <signed payload>"
# 200 {"total_debits":5000,"total_credits":5000,"balanced":true}

Where to go next

• Track agent spend and revenue — a full worked example with expenses.
• Double-entry for agents — the model behind the calls.
• Capability tokens vs x402 — choosing an auth model.