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:

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:

{
  "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

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