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

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:

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

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:

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

Response:

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

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:

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