# Balance Policies

Balance policies control whether an account's balance is allowed to go positive, negative, or both. They are a key safety mechanism to prevent invalid financial states.

## Available Policies

| Policy            | Rule                      | Example Use Case                 |
| ----------------- | ------------------------- | -------------------------------- |
| `ALWAYS_POSITIVE` | Balance cannot go below 0 | Customer payment accounts        |
| `ALWAYS_NEGATIVE` | Balance cannot go above 0 | SPI/Central Bank mirror accounts |
| `NONE`            | No restriction on balance | Fee accounts, revenue accounts   |

## How Policies are Applied

Balance policies are specified **per journal entry side** (debit or credit), not per account. This means the same account can have different policies applied in different transactions.

```json
{
  "journal_entries": [
    {
      "sequence": 1,
      "type": "PIX_OUT",
      "asset": "BRL",
      "amount": 1000,
      "debit": {
        "account_id": "uuid-customer",
        "balance_policy": "ALWAYS_POSITIVE"
      },
      "credit": {
        "account_id": "uuid-pix-asset",
        "balance_policy": "ALWAYS_NEGATIVE"
      }
    }
  ]
}
```

In this example:

* The **debit account** (customer) must maintain a positive balance after the debit
* The **credit account** (PIX asset) must maintain a negative balance after the credit

## Policy Evaluation

Policies are evaluated **after** calculating the post-balance for each journal entry. If any policy is violated, the entire transaction is rejected — no partial execution.

### ALWAYS\_POSITIVE

The account balance after the operation must be >= 0.

**Example:** An account with balance `500` debited by `600`:

* Post-balance would be `-100`
* **Rejected** with error code `INSUFFICIENT_FUNDS` (HTTP 422)

### ALWAYS\_NEGATIVE

The account balance after the operation must be <= 0.

**Example:** An account with balance `-1000` credited by `1500`:

* Post-balance would be `500`
* **Rejected** with error code `INVALID_BALANCE` (HTTP 422)

### NONE

No restriction. The balance can go to any value.

## Sequential Evaluation in Multi-Entry Transactions

When a transaction has multiple journal entries, balance policies are evaluated **sequentially** in journal entry order. Each journal entry's post-balance is calculated based on the balance left by the previous journal entry.

**Example:** Account A has balance `1000`.

| Journal Entry | Operation | Amount | Post-Balance | Policy           | Result |
| ------------- | --------- | ------ | ------------ | ---------------- | ------ |
| 1             | Debit     | 800    | 200          | ALWAYS\_POSITIVE | OK     |
| 2             | Debit     | 300    | -100         | ALWAYS\_POSITIVE | FAIL   |

Journal entry 2 fails because the balance would go negative. The **entire transaction** (both journal entries) is rejected.

## Choosing the Right Policy

| Account Purpose          | Debit Policy     | Credit Policy    |
| ------------------------ | ---------------- | ---------------- |
| Customer wallet          | ALWAYS\_POSITIVE | NONE             |
| Central Bank mirror      | NONE             | ALWAYS\_NEGATIVE |
| Fee revenue              | NONE             | NONE             |
| Escrow / holding account | ALWAYS\_POSITIVE | NONE             |
| Internal clearing        | NONE             | NONE             |

{% hint style="info" %}
The policy is declared on the transaction request, not on the account itself. This gives you flexibility to apply different policies for different business scenarios on the same account.
{% endhint %}


---

# 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/balance-policies.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.