# Accounts

An account is the fundamental unit of the ledger. It holds a balance in a specific asset (currency) and tracks every movement through its ledger.

## Account Fields

| Field        | Type      | Description                                                 |
| ------------ | --------- | ----------------------------------------------------------- |
| `id`         | UUID      | Unique identifier (UUID v7, sequential by time)             |
| `category`   | String    | Free-form label (e.g., `PAYMENT_ACCOUNT`, `PIX_ASSET`)      |
| `asset`      | String    | Currency code (e.g., `BRL`, `USD`)                          |
| `balance`    | Integer   | Current balance — client controls decimal places            |
| `version`    | Integer   | Incremented on every balance change — used as ledger cursor |
| `created_at` | Timestamp | When the account was created (millisecond precision)        |

## Creating an Account

```bash
curl -X POST http://<host>:8080/account \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..." \
  -d '{
    "category": "PAYMENT_ACCOUNT",
    "asset": "BRL"
  }'
```

**Response:**

```json
{
  "id": "019702a0-1234-7abc-8def-000000000001"
}
```

The account starts with `balance = 0` and `version = 0`.

## Querying an Account

```bash
curl http://<host>:8080/account/<id> \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```

**Response:**

```json
{
  "id": "019702a0-1234-7abc-8def-000000000001",
  "category": "PAYMENT_ACCOUNT",
  "asset": "BRL",
  "balance": 15000,
  "version": 12,
  "created_at": "2026-01-15T10:30:00.123Z"
}
```

## Balance Summary by Asset

Query the total balance grouped by category for a specific asset:

```bash
curl http://<host>:8080/account/asset/BRL \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```

This returns the aggregate balances of all accounts with the specified asset, grouped by category.

## Field Validation Rules

| Field      | Rule                                                          |
| ---------- | ------------------------------------------------------------- |
| `category` | Only `A-Z`, `0-9`, `_` — automatically converted to uppercase |
| `asset`    | Only `A-Z`, `0-9`, `_` — automatically converted to uppercase |

{% hint style="info" %}
You can use lowercase in your requests — the system normalizes all string fields to uppercase automatically.
{% endhint %}

## Account Version

The `version` field starts at 0 and increments by 1 every time the account's balance changes (i.e., every time the account participates in a transaction as either debit or credit).

The version is used as:

* **Ledger cursor** — paginate through account history using version-based cursors
* **Consistency check** — version must be sequential with no gaps in the ledger
* **Integrity seal** — included in the row-level hash computation

## Important Notes

* Accounts cannot be deleted. Once created, they persist forever.
* An account's `asset` is set at creation and never changes.
* An account's `category` is set at creation and never changes.
* The `balance` can be positive, negative, or zero depending on the balance policies applied in transactions.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/concepts/accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.