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

# Pool Management

> Monitor and manage your company's treasury pool.

## Get Pool Balance

`GET /pool/balance`

Returns the current USDC balance and status of your company's treasury pool.

### Authentication

Requires a **Secret Key** (`sk_...`) in the `x-api-key` header or Bearer token.

### Response Fields

| Field                    | Type      | Description                                                        |
| :----------------------- | :-------- | :----------------------------------------------------------------- |
| `balance`                | `string`  | Total USDC available in the treasury pool.                         |
| `currency`               | `string`  | Always `USDC`.                                                     |
| `low_threshold`          | `string`  | Configured balance below which a "low balance" alert is triggered. |
| `is_low`                 | `boolean` | `true` if current balance is below the threshold.                  |
| `remaining_before_alert` | `string`  | Amount that can be spent before hitting the threshold.             |
| `auto_top_up_enabled`    | `boolean` | Indicates if automatic funding from a bank/wallet is enabled.      |

### Sample Response

```json theme={null}
{
  "balance": "4950.00",
  "currency": "USDC",
  "low_threshold": "1000.00",
  "is_low": false,
  "remaining_before_alert": "3950.00",
  "auto_top_up_enabled": false
}
```

***

## List Pool Transactions

`GET /pool/transactions`

Retrieve historical movements in your pool, including deposits, payments (debits), and withdrawals.

### Query Parameters

| Parameter | Type     | Default | Description                                                               |
| :-------- | :------- | :------ | :------------------------------------------------------------------------ |
| `type`    | `string` | -       | Filter by: `DEPOSIT`, `DEBIT` (payment), `CREDIT` (refund), `WITHDRAWAL`. |
| `limit`   | `number` | `50`    | Results per page (max 100).                                               |
| `offset`  | `number` | `0`     | Number of results to skip.                                                |

### Response Fields

| Field          | Type     | Description                                           |
| :------------- | :------- | :---------------------------------------------------- |
| `transactions` | `array`  | List of transaction objects.                          |
| `pagination`   | `object` | Metadata including `total` count and `has_more` flag. |

#### Transaction Object

| Field            | Type     | Description                                                          |
| :--------------- | :------- | :------------------------------------------------------------------- |
| `id`             | `string` | Internal transaction ID.                                             |
| `type`           | `string` | Type of movement (e.g., `DEBIT`).                                    |
| `amount`         | `string` | Amount changed (negative for debits/withdrawals).                    |
| `balance_before` | `string` | Pool balance before this transaction.                                |
| `balance_after`  | `string` | Pool balance after this transaction.                                 |
| `status`         | `string` | Status: `PENDING` or `CONFIRMED`.                                    |
| `tx_hash`        | `string` | Blockchain transaction hash (if applicable).                         |
| `description`    | `string` | Human-readable explanation.                                          |
| `payment`        | `object` | Reference to the associated payment (only for `DEBIT` and `CREDIT`). |
| `created_at`     | `string` | ISO 8601 timestamp.                                                  |
| `confirmed_at`   | `string` | Time of transaction finality.                                        |

### Sample Response

```json theme={null}
{
  "transactions": [
    {
      "id": "ptx_abc123",
      "type": "DEBIT",
      "amount": "-15.00",
      "balance_before": "5000.00",
      "balance_after": "4985.00",
      "status": "CONFIRMED",
      "tx_hash": "0xabcd...",
      "description": "Payment for Merchant: Organic Coffee",
      "payment": {
        "payment_id": "pay_999",
        "amount": "15.00",
        "merchant_name": "Organic Coffee"
      },
      "created_at": "2026-03-31T01:50:00Z",
      "confirmed_at": "2026-03-31T01:50:05Z"
    }
  ],
  "pagination": {
    "total": 542,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}
```