# Accounts API

The Accounts API manages financial accounts, balances, and account products.

## Overview

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/accounts` | GET | List all accounts |
| `/api/v1/accounts` | POST | Create a new account |
| `/api/v1/accounts/:id` | GET | Get account details |
| `/api/v1/accounts/:id/balance` | GET | Get account balance |
| `/api/v1/accounts/:id/statement` | GET | Get account statement |

## List Accounts

```http
GET /api/v1/accounts
Authorization: Bearer {token}
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Items per page (default: 20, max: 100) |
| `status` | string | Filter by status: `active`, `inactive`, `blocked` |
| `product_id` | string | Filter by account product |

**Response:**

```json
{
  "data": [
    {
      "id": "acc_01HQGX...",
      "name": "Main Operating Account",
      "product": {
        "id": "prod_pix_merchant",
        "name": "PIX Merchant Account"
      },
      "status": "active",
      "balance": {
        "available": 76824,
        "pending": 5000,
        "blocked": 0
      },
      "currency": "BRL",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 4,
    "total_pages": 1
  }
}
```

::: tip
Balances are in **centavos**. R$ 768.24 = `76824`.
:::

## Create Account

```http
POST /api/v1/accounts
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Settlement Account",
  "product_id": "prod_pix_settlement",
  "metadata": {
    "purpose": "Daily PIX settlements"
  }
}
```

## Get Account Balance

Returns the real-time balance from TigerBeetle:

```http
GET /api/v1/accounts/acc_01HQGX.../balance
Authorization: Bearer {token}
```

**Response:**

```json
{
  "data": {
    "account_id": "acc_01HQGX...",
    "available": 76824,
    "pending": 5000,
    "blocked": 0,
    "total": 81824,
    "currency": "BRL",
    "updated_at": "2026-02-03T12:00:00Z"
  }
}
```

### Balance Types

| Type | Description |
|------|-------------|
| `available` | Funds available for immediate use |
| `pending` | Funds in processing (PIX payouts, settlements) |
| `blocked` | Funds blocked by compliance or disputes |
| `total` | Sum of available + pending + blocked |

## Get Account Statement

```http
GET /api/v1/accounts/acc_01HQGX.../statement?start_date=2026-02-01&end_date=2026-02-03
Authorization: Bearer {token}
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `start_date` | date | Start date (YYYY-MM-DD) |
| `end_date` | date | End date (YYYY-MM-DD) |
| `page` | integer | Page number |
| `per_page` | integer | Items per page (max: 100) |
| `type` | string | Filter: `credit`, `debit`, `all` |

**Response:**

```json
{
  "data": {
    "account_id": "acc_01HQGX...",
    "opening_balance": 50000,
    "closing_balance": 76824,
    "entries": [
      {
        "id": "txn_01HQGX...",
        "type": "credit",
        "amount": 15000,
        "balance_after": 65000,
        "description": "PIX received - Maria Silva",
        "category": "pix_in",
        "end_to_end_id": "E12345678202602031200...",
        "created_at": "2026-02-01T10:30:00Z"
      }
    ]
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 89,
    "total_pages": 5
  }
}
```

## Account Products

| Product ID | Name | Description |
|------------|------|-------------|
| `prod_pix_merchant` | PIX Merchant | Main operating account for merchants |
| `prod_pix_settlement` | PIX Settlement | Settlement holding account |
| `prod_pix_escrow` | PIX Escrow | Escrow for disputed transactions |
| `prod_pix_fee` | PIX Fee | Platform fee collection |
| `prod_pix_transit` | PIX Transit | In-flight transaction holding |
| `prod_pix_provider` | PIX Provider | Provider integration account |
| `prod_pix_reserve` | PIX Reserve | Regulatory reserve account |
| `prod_pix_revenue` | PIX Revenue | Revenue recognition account |

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `ACCOUNT_NOT_FOUND` | 404 | Account does not exist |
| `ACCOUNT_INACTIVE` | 422 | Account is not active |
| `ACCOUNT_BLOCKED` | 422 | Account is blocked by compliance |
| `INVALID_PRODUCT` | 422 | Unknown account product |
| `DUPLICATE_ACCOUNT` | 409 | Account with same parameters exists |