# Transfers API

The Transfers API enables internal fund movements between accounts within the FluxiQ platform.

## Overview

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/transfers` | POST | Create a transfer |
| `/api/v1/transfers/:id` | GET | Get transfer details |
| `/api/v1/transfers` | GET | List transfers |

## Create Transfer

Move funds between two accounts:

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

{
  "source_account_id": "acc_01HQGX...",
  "destination_account_id": "acc_01HQGY...",
  "amount": 10000,
  "description": "Settlement transfer",
  "idempotency_key": "xfer_20260203_001",
  "metadata": {
    "settlement_date": "2026-02-03",
    "batch_id": "batch_456"
  }
}
```

**Response:**

```json
{
  "data": {
    "id": "xfer_01HQGX...",
    "status": "completed",
    "source_account_id": "acc_01HQGX...",
    "destination_account_id": "acc_01HQGY...",
    "amount": 10000,
    "description": "Settlement transfer",
    "ledger_entry_id": "tb_01HQGX...",
    "idempotency_key": "xfer_20260203_001",
    "created_at": "2026-02-03T12:00:00Z",
    "completed_at": "2026-02-03T12:00:00Z"
  }
}
```

::: info
Internal transfers are processed synchronously through TigerBeetle and complete in under 10ms.
:::

## List Transfers

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

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | integer | Page number (default: 1) |
| `per_page` | integer | Items per page (default: 20, max: 100) |
| `account_id` | string | Filter by source or destination account |
| `status` | string | Filter: `completed`, `failed`, `pending` |
| `start_date` | date | Start date (YYYY-MM-DD) |
| `end_date` | date | End date (YYYY-MM-DD) |

## Transfer Statuses

| Status | Description |
|--------|-------------|
| `completed` | Transfer successfully executed |
| `failed` | Transfer failed (insufficient funds, account blocked) |
| `pending` | Transfer awaiting approval (for large amounts) |

## Double-Entry Ledger

Every transfer creates a balanced double-entry record in TigerBeetle:

```
Transfer: acc_source -> acc_destination (R$ 100.00)

  Debit:  acc_source        10000
  Credit: acc_destination    10000
  ────────────────────────────────
  Balance:                       0  (always zero)
```

This ensures:
- Total debits always equal total credits
- No funds are created or destroyed
- Complete audit trail for every movement

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INSUFFICIENT_FUNDS` | 422 | Source account has insufficient available balance |
| `SAME_ACCOUNT` | 422 | Source and destination cannot be the same |
| `ACCOUNT_NOT_FOUND` | 404 | Source or destination account not found |
| `ACCOUNT_BLOCKED` | 422 | One of the accounts is blocked |
| `AMOUNT_TOO_LOW` | 422 | Amount must be greater than zero |
| `DUPLICATE_TRANSFER` | 409 | Idempotency key already used |
| `APPROVAL_REQUIRED` | 202 | Transfer requires manual approval |