Treasury & Finance Guide

A practical walkthrough of the treasury domain: chart of accounts, double-entry journal entries, invoicing, payments, bank accounts, and payroll.

All monetary amounts are in whole cents (e.g., $50,000.00 = 5000000).

---

Overview

The treasury domain implements a double-entry general ledger (GL) with supporting workflows for invoicing customers, recording payments, managing bank accounts, and running payroll. Every financial mutation is tracked as a journal entry with balanced debits and credits.

Concept	Purpose
Accounts	Chart of accounts — each account has a code, name, and currency
Journal Entries	Double-entry records: draft → posted → voided
Invoices	Bill customers: draft → sent → paid (or voided)
Payments	Record outgoing payments to vendors and service providers
Bank Accounts	Track bank relationships: open → active → closed
Payroll Runs	Process payroll: draft → approved → processed

---

1. Chart of Accounts

Set up the accounts your entity needs. Common account codes for a startup:

CLI

corp finance create-account --account-code cash --account-name "Cash" --currency usd
corp finance create-account --account-code accounts_receivable --account-name "Accounts Receivable" --currency usd
corp finance create-account --account-code accounts_payable --account-name "Accounts Payable" --currency usd
corp finance create-account --account-code accrued_expenses --account-name "Accrued Expenses" --currency usd
corp finance create-account --account-code founder_capital --account-name "Founder Capital" --currency usd
corp finance create-account --account-code revenue --account-name "Revenue" --currency usd
corp finance create-account --account-code operating_expenses --account-name "Operating Expenses" --currency usd
corp finance create-account --account-code cogs --account-name "Cost of Goods Sold" --currency usd

API

curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/accounts \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_code": "cash",
    "account_name": "Cash",
    "currency": "usd"
  }'

Repeat for each account code. Save the returned account_id values — you’ll reference them in journal entry lines.

List accounts

# CLI
corp finance accounts

# API
curl http://localhost:8000/v1/entities/$ENTITY_ID/accounts \
  -H "Authorization: Bearer $CORP_API_KEY"

Deactivate an account

# API
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/accounts/$ACCOUNT_ID/deactivate \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

---

2. Journal Entries (Double-Entry)

Every journal entry has two or more lines. Total debits must equal total credits — the API rejects unbalanced entries.

Create a journal entry

Record a $50,000 founder investment (debit cash, credit founder capital):

corp finance create-entry \
  --date 2026-01-15 \
  --description "Founder investment" \
  --lines '[
    {"account_id": "'$CASH_ACCOUNT_ID'", "amount_cents": 5000000, "side": "debit"},
    {"account_id": "'$FOUNDER_CAPITAL_ACCOUNT_ID'", "amount_cents": 5000000, "side": "credit"}
  ]'

API

curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/journal-entries \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-01-15",
    "description": "Founder investment",
    "lines": [
      {"account_id": "'$CASH_ACCOUNT_ID'", "amount_cents": 5000000, "side": "debit"},
      {"account_id": "'$FOUNDER_CAPITAL_ACCOUNT_ID'", "amount_cents": 5000000, "side": "credit"}
    ]
  }'

Entry lifecycle: draft → posted → voided

Journal entries start as draft. Post them to commit to the ledger, or void them to cancel.

# Post a draft entry (makes it permanent)
corp finance post-entry $ENTRY_ID

# Void a posted entry (reversal)
corp finance void-entry $ENTRY_ID

API — post and void

# Post
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/journal-entries/$ENTRY_ID/post \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Void
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/journal-entries/$ENTRY_ID/void \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List journal entries

# CLI
corp finance journal-entries

# API
curl http://localhost:8000/v1/entities/$ENTITY_ID/journal-entries \
  -H "Authorization: Bearer $CORP_API_KEY"

Balance rule

Every journal entry must balance: the sum of all debit amount_cents must equal the sum of all credit amount_cents. The API returns a 400 error if they don’t match.

---

3. Invoicing

Invoices follow a state machine: draft → sent → paid (or voided at any stage before payment).

Create an invoice

corp finance create-invoice \
  --customer "Acme Corp" \
  --email [email protected] \
  --amount-cents 1500000 \
  --currency usd \
  --description "Q1 consulting" \
  --due-date 2026-04-30

API

curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/invoices \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "Acme Corp",
    "email": "[email protected]",
    "amount_cents": 1500000,
    "currency": "usd",
    "description": "Q1 consulting",
    "due_date": "2026-04-30"
  }'

Send, pay, and void

# Send the invoice to the customer
corp finance send-invoice $INVOICE_ID

# Mark as paid
corp finance pay-invoice $INVOICE_ID

# Void (cancel) an invoice
corp finance void-invoice $INVOICE_ID

API — invoice transitions

# Send
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID/send \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Pay
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID/pay \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Void
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID/void \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

---

4. Payments

Record outgoing payments to vendors, contractors, or service providers.

CLI

corp finance create-payment \
  --recipient-name "AWS" \
  --amount-cents 250000 \
  --method ach \
  --reference "Invoice #1234"

API

curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/payments \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "AWS",
    "amount_cents": 250000,
    "method": "ach",
    "reference": "Invoice #1234"
  }'

List payments

# CLI
corp finance payments

# API
curl http://localhost:8000/v1/entities/$ENTITY_ID/payments \
  -H "Authorization: Bearer $CORP_API_KEY"

---

5. Bank Accounts

Bank accounts follow a lifecycle: open → active → closed.

CLI

# Open a new bank account
corp finance create-bank-account \
  --bank-name "Silicon Valley Bank" \
  --account-type checking \
  --currency usd

# Activate (after bank confirms the account)
corp finance activate-bank-account $BANK_ID

# Close the account
corp finance close-bank-account $BANK_ID

API

# Create
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/bank-accounts \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_name": "Silicon Valley Bank",
    "account_type": "checking",
    "currency": "usd"
  }'

# Activate
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/bank-accounts/$BANK_ID/activate \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Close
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/bank-accounts/$BANK_ID/close \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List bank accounts

# CLI
corp finance bank-accounts

# API
curl http://localhost:8000/v1/entities/$ENTITY_ID/bank-accounts \
  -H "Authorization: Bearer $CORP_API_KEY"

---

6. Payroll Runs

Payroll follows a lifecycle: draft → approved → processed.

CLI

# Create a payroll run
corp finance create-payroll-run \
  --pay-date 2026-03-31 \
  --period-start 2026-03-01 \
  --period-end 2026-03-31 \
  --total-gross-cents 2500000

# Approve (manager sign-off)
corp finance approve-payroll-run $RUN_ID

# Process (disburse funds)
corp finance process-payroll-run $RUN_ID

API

# Create
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/payroll-runs \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pay_date": "2026-03-31",
    "period_start": "2026-03-01",
    "period_end": "2026-03-31",
    "total_gross_cents": 2500000
  }'

# Approve
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/payroll-runs/$RUN_ID/approve \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Process
curl -X POST http://localhost:8000/v1/entities/$ENTITY_ID/payroll-runs/$RUN_ID/process \
  -H "Authorization: Bearer $CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List payroll runs

# CLI
corp finance payroll-runs

# API
curl http://localhost:8000/v1/entities/$ENTITY_ID/payroll-runs \
  -H "Authorization: Bearer $CORP_API_KEY"

---

Summary

Resource	CLI prefix	API base path
Accounts	corp finance *-account	/v1/entities/{id}/accounts
Journal Entries	corp finance *-entry	/v1/entities/{id}/journal-entries
Invoices	corp finance *-invoice	/v1/entities/{id}/invoices
Payments	corp finance *-payment	/v1/entities/{id}/payments
Bank Accounts	corp finance *-bank-account	/v1/entities/{id}/bank-accounts
Payroll Runs	corp finance *-payroll-run	/v1/entities/{id}/payroll-runs