API Overview - 0 Finance Docs

Most users should use the CLI or MCP server instead of calling the API directly.

API surfaces

0 Finance exposes two API surfaces:

CLI API — API-key authenticated endpoints at /api/cli
Dashboard API — Session/webhook authenticated endpoints at /api/*

CLI API (API keys)

Base URL

https://www.0.finance/api/cli

For local development:

http://localhost:3050/api/cli

Authentication

Include your API key in the Authorization header:

curl https://www.0.finance/api/cli/balance \
  -H "Authorization: Bearer sk_live_xxx"

Get your API key from Settings → API Keys.

Admin authentication

Admin-only endpoints require the x-admin-token header:

curl https://www.0.finance/api/cli/users \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "x-admin-token: adm_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Response format

Endpoints return JSON objects. Errors return { "error": "..." }. Example error:

{
  "error": "Unauthorized: invalid or missing API key"
}

CLI endpoint map

Auth & balance

Method	Endpoint	Description
GET	`/api/cli/whoami`	Workspace metadata for the API key
GET	`/api/cli/balance`	Spendable (idle + earning) balance

Bank accounts

Method	Endpoint	Description
GET	`/api/cli/bank-accounts`	List saved bank accounts
POST	`/api/cli/bank-accounts`	Create a bank account

Bank transfers

Method	Endpoint	Description
POST	`/api/cli/bank-transfers/proposals`	Propose a bank transfer
GET	`/api/cli/bank-transfers/proposals`	List proposals (`include_completed=true`)
POST	`/api/cli/bank-transfers/proposals/:id/dismiss`	Dismiss a proposal

Invoices

Method	Endpoint	Description
POST	`/api/cli/invoices`	Create an invoice
GET	`/api/cli/invoices`	List invoices (`status`, `limit`)
GET	`/api/cli/invoices/:id`	Get invoice details
PATCH	`/api/cli/invoices/:id`	Update an invoice
POST	`/api/cli/invoices/:id/send`	Send an invoice

Transactions

Method	Endpoint	Description
GET	`/api/cli/transactions`	List transactions (`status`, `limit`)
GET	`/api/cli/transactions/:id`	Get transaction details

Attachments

Method	Endpoint	Description
POST	`/api/cli/attachments`	Upload an attachment
GET	`/api/cli/attachments`	List attachments (`transaction_id`, `transaction_type`, `limit`)
DELETE	`/api/cli/attachments/:id`	Remove an attachment

Payment details

Method	Endpoint	Description
GET	`/api/cli/payment-details`	Get IBAN/ACH receiving details
POST	`/api/cli/payment-details/share`	Email receiving details

Crypto transfers

Method	Endpoint	Description
POST	`/api/cli/crypto-transfers/proposals`	Propose a crypto transfer
GET	`/api/cli/crypto-transfers/proposals`	List crypto proposals (`include_completed=true`)
POST	`/api/cli/crypto-transfers/proposals/:id/dismiss`	Dismiss a crypto proposal

Savings & vaults

Method	Endpoint	Description
GET	`/api/cli/vaults`	List supported vaults
POST	`/api/cli/savings/deposits`	Propose a vault deposit
POST	`/api/cli/savings/withdrawals`	Propose a vault withdrawal
GET	`/api/cli/savings/proposals`	List savings proposals (`include_completed=true`)
GET	`/api/cli/savings/positions`	Idle/earning balance and vault positions

Admin endpoints

Method	Endpoint	Description
POST	`/api/cli/users`	Provision a user (creates workspace + API key)
GET	`/api/cli/users/:id`	Fetch user + profile by Privy DID
POST	`/api/cli/users/:id/wallets`	Pregenerate wallets for a user
POST	`/api/cli/api-keys`	Create an API key for a workspace

CLI query parameters

Invoices

status: db_pending, pending, paid, canceled
limit: number

Transactions

status: pending, completed, failed
limit: number

Proposals

include_completed: true or false

CLI examples

Check balance

curl https://www.0.finance/api/cli/balance \
  -H "Authorization: Bearer sk_live_xxx"

Response:

{
  "idle_balance": "3200.00",
  "earning_balance": "4220.50",
  "spendable_balance": "7420.50",
  "safe_address": "0x954A329e1e59101DF529CC54A54666A0b36Cae22",
  "chain": "base"
}

Create invoice

curl https://www.0.finance/api/cli/invoices \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "client@example.com",
    "amount": 1000,
    "currency": "USD",
    "description": "Consulting services"
  }'

Propose transfer

curl https://www.0.finance/api/cli/bank-transfers/proposals \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usdc": "1000",
    "destination_currency": "usd",
    "saved_bank_account_id": "ba_xxx",
    "reason": "Contractor payment"
  }'

Transfers create proposals that require dashboard approval before executing.

Dashboard endpoints (session/webhook)

These endpoints are used by the web app and internal services:

Health check: /api/health
Upload: /api/upload (requires a signed-in user session)
Register primary Safe: /api/user/safes/register-primary
Privy webhooks: /api/webhooks/auth (HMAC signed)

See the endpoint pages in the API sidebar for request/response details.

MCP server

The MCP server at /api/mcp wraps the CLI API for AI agents. See MCP Overview for details.

​API surfaces

​CLI API (API keys)

​Base URL

​Authentication

​Admin authentication

​Response format

​CLI endpoint map

​Auth & balance

​Bank accounts

​Bank transfers

​Invoices

​Transactions

​Attachments

​Payment details

​Crypto transfers

​Savings & vaults

​Admin endpoints

​CLI query parameters

​Invoices

​Transactions

​Proposals

​CLI examples

​Check balance

​Create invoice

​Propose transfer

​Dashboard endpoints (session/webhook)

​MCP server

API surfaces

CLI API (API keys)

Base URL

Authentication

Admin authentication

Response format

CLI endpoint map

Auth & balance

Bank accounts

Bank transfers

Invoices

Transactions

Attachments

Payment details

Crypto transfers

Savings & vaults

Admin endpoints

CLI query parameters

Invoices

Transactions

Proposals

CLI examples

Check balance

Create invoice

Propose transfer

Dashboard endpoints (session/webhook)

MCP server