> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Direct HTTP access to 0 Finance

<Info>
  Most users should use the [CLI](/cli/installation) or [MCP
  server](/mcp/overview) instead of calling the API directly.
</Info>

## API surfaces

0 Finance exposes two API surfaces:

1. **CLI API** — API-key authenticated endpoints at `/api/cli`
2. **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:

```bash theme={null}
curl https://www.0.finance/api/cli/balance \
  -H "Authorization: Bearer sk_live_xxx"
```

Get your API key from [Settings → API Keys](https://www.0.finance/settings).

### Admin authentication

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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl https://www.0.finance/api/cli/balance \
  -H "Authorization: Bearer sk_live_xxx"
```

Response:

```json theme={null}
{
  "idle_balance": "3200.00",
  "earning_balance": "4220.50",
  "spendable_balance": "7420.50",
  "safe_address": "0x954A329e1e59101DF529CC54A54666A0b36Cae22",
  "chain": "base"
}
```

### Create invoice

```bash theme={null}
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

```bash theme={null}
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"
  }'
```

<Warning>
  Transfers create proposals that require dashboard approval before executing.
</Warning>

***

## 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](/mcp/overview) for details.