> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic Liquidity

> Monitor nostro account balances and configure automatic liquidity transfers between nostro accounts.

## How It Works

Each clearing system connection (BIC) maintains separate nostro accounts for SCT (SEPA Credit Transfer) and INST (SEPA Instant). The liquidity engine periodically checks these balances against your configured minimums and takes action when needed.

```mermaid actions={true} theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TD
    A[Balance Check] --> B{Below absolute min?}
    B -->|Yes| C[Critical alert]
    B -->|No| D{Below warning min?}
    D -->|Yes| E[Low balance alert]
    D -->|No| G{SCT or INST below min?}
    E --> G
    G -->|No| H[Balances healthy]
    G -->|Yes| I{Can cover transfer?}
    I -->|Yes| J{Auto-liquidity on?}
    J -->|Yes| K[Auto transfer]
    J -->|No| L[Notify]
    I -->|No| M[Notify - no funds]
```

## Balance Thresholds

You configure four values that control the engine's behavior:

| Setting              | Description                                                                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SCT Minimum**      | Minimum balance for the SCT nostro account                                                                                                         |
| **INST Minimum**     | Minimum balance for the INST nostro account                                                                                                        |
| **Transfer Amount**  | Amount moved between accounts during an automatic transfer                                                                                         |
| **Critical Minimum** | Calculated as SCT Minimum + INST Minimum + Transfer Amount. Below this, the system won't rebalance                                                 |
| **Warning Balance**  | Target minimum balance across both accounts. Breaching it sends a notification, but transfers still work. Must be at or above the Critical Minimum |

## Configuration

Configure liquidity settings through the Dashboard under **Settings > Liquidity**.

### Enable Auto-Liquidity

1. Navigate to **Settings > Liquidity**
2. Enable **Auto-Liquidity**
3. Set **SCT Minimum**, **INST Minimum**, and **Transfer Amount**
4. Optionally set a **Warning Balance** above the critical minimum
5. Save the configuration

### What-If Calculator

The settings page includes a what-if calculator. Enter hypothetical SCT and INST balances to see what the engine would do - which alerts fire, whether a transfer is triggered, and in which direction. Use the sliders to explore thresholds.

## Automatic Transfers

When auto-liquidity is enabled and a scheme balance drops below its minimum, the engine:

1. Checks if the opposite scheme account has enough surplus (its own minimum + transfer amount)
2. If yes, initiates a transfer of the configured amount from the surplus account to the deficit account
3. The transfer is sent to the clearing system as a dedicated liquidity transfer instruction, not a regular customer payment - it is recorded as an Adjustment transaction and cannot be cancelled or returned

<Warning>
  Transfers only execute during the clearing system's operating window. For SEPA via CENTROlink, this is typically 08:00-18:40 EET on business days.
</Warning>

## Notifications

Configure webhook URLs to receive alerts when balance thresholds are breached or when automatic transfers occur.

| Webhook                      | Fires when                                                                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Low balance notification** | Total balance drops below the Warning Balance or Critical Minimum, or a scheme balance is below its minimum and funds cannot be transferred |
| **Transfer notification**    | An automatic liquidity transfer is initiated or changes status                                                                              |

### Low Balance Notification

```json Payload theme={null}
{
  "alertType": "RECOMMENDED_TOTAL_MINIMUM_BREACHED",
  "ibans": ["LT123456789", "LT987654321"],
  "minimumBalance": 100,
  "currentBalance": 99
}
```

<ResponseField name="alertType" type="string" required>
  Which limit was breached. One of: `RECOMMENDED_TOTAL_MINIMUM_BREACHED`, `ABSOLUTE_TOTAL_MINIMUM_BREACHED`, `SCT_MINIMUM_BREACHED_NO_TRANSFER`, `INST_MINIMUM_BREACHED_NO_TRANSFER`
</ResponseField>

<ResponseField name="ibans" type="array" required>
  IBANs of the impacted nostro accounts
</ResponseField>

<ResponseField name="minimumBalance" type="number" required>
  The configured limit that was breached
</ResponseField>

<ResponseField name="currentBalance" type="number" required>
  The balance at the time of the alert
</ResponseField>

### Liquidity Transfer Notification

```json Payload theme={null}
{
  "transferId": 1,
  "sepaMessageId": "sepa-message-id",
  "debtorAccount": "LT123456789",
  "creditorAccount": "LT987654321",
  "amount": 10,
  "currency": "EUR",
  "status": "CREATED"
}
```

<ResponseField name="transferId" type="integer" required>
  Liquidity transfer identifier
</ResponseField>

<ResponseField name="sepaMessageId" type="string">
  Identifier of the SEPA message carrying the transfer
</ResponseField>

<ResponseField name="debtorAccount" type="string" required>
  Source nostro account IBAN
</ResponseField>

<ResponseField name="creditorAccount" type="string" required>
  Destination nostro account IBAN
</ResponseField>

<ResponseField name="amount" type="number" required>
  Transfer amount
</ResponseField>

<ResponseField name="currency" type="string" required>
  Currency code (ISO 4217)
</ResponseField>

<ResponseField name="status" type="string" required>
  Transfer status. One of: `CREATED`, `SENT_TO_CLEAR`, `ACCEPTED`, `REJECTED`, `COMPLETED`
</ResponseField>

Set the **Minutes between notifications** value to control how often repeated alerts are sent for the same condition. This prevents notification floods when balances remain low.

<Tip>
  Test your webhook URLs using the **Test** button next to each URL field in the settings page before saving.
</Tip>

## API Reference

<CardGroup cols={2}>
  <Card title="Get Nostro Balances" icon="scale-balanced" href="/payments/api/nostro/nostro-account-balances/get-nostro-account-balances">
    View current nostro account balances
  </Card>

  <Card title="Initiate Transfer" icon="arrow-right-arrow-left" href="/payments/api/nostro/initiate-nostro-account-liquidity-transfer">
    Manually transfer funds between nostro accounts
  </Card>

  <Card title="Transfer History" icon="clock-rotate-left" href="/payments/api/nostro/get-nostro-account-liquidity-transfer-list">
    View past liquidity transfers
  </Card>

  <Card title="Account Statements" icon="file-lines" href="/payments/api/nostro/nostro-account-statements/get-nostro-account-statement-page">
    View nostro account statements
  </Card>
</CardGroup>