---
name: natural-check-balance
description: Check wallet balance on the Natural platform. Use when you need to verify available funds before sending a payment or to display balance information.
metadata:
  author: Natural
  version: "1.0"
---

# Check Balance

Check wallet balance on the Natural platform.

## Prerequisites

- A valid API key (`sk_*`) is configured
- For CLI usage, check the authenticated party's wallet or a wallet ID visible to that party
- For delegated customer lookup by `customerPartyId` (`pty_xxx`), use the MCP adapter

## Workflow

### 1. Choose lookup method

The current CLI exposes wallet balance through `natural wallet list` and `natural wallet get`. It does not expose a `--customer-party-id` balance lookup. Use MCP when the only identifier you have is a delegated customer's `customerPartyId`.

### 2. Retrieve balance

Fetch the wallet and read `attributes.balance`.

### 3. Interpret results

| Field                                 | Description                                |
| ------------------------------------- | ------------------------------------------ |
| `data[].attributes.balance.available` | Spendable balance in minor units (cents)   |
| `data[].attributes.balance.total`     | Total wallet ledger balance in minor units |
| `data[].attributes.balance.currency`  | Currency code                              |
| `data[].relationships.party.data.id`  | Party that owns the wallet                 |

**Amounts are always in minor units (cents).** `5000` = $50.00.
Payment claims are not wallet balance. Use the payment claims summary API when you need claimable payment totals.

## Error handling

- **Auth error:** API key is missing, invalid, or lacks permission for this wallet — check credentials
- **Wallet not accessible:** The wallet is not visible to the authenticated party
- **Network/server error:** Retry the request

---

## CLI Adapter

Execute the check-balance workflow using the `natural` CLI. All commands should use `--format json` for structured output that agents can parse.

### Command

```bash
natural wallet list --format json
```

To fetch one known wallet, use `natural wallet get --wallet-id wal_xxx --format json`.

Response shape:

```json
{
  "data": [
    {
      "type": "wallet",
      "id": "wal_xxx",
      "attributes": {
        "status": "active",
        "balance": {
          "available": 5000,
          "total": 7500,
          "currency": "USD"
        },
        "claims": {
          "amount": 0,
          "count": 0
        },
        "depositInstructions": null
      },
      "relationships": {
        "party": {
          "data": {
            "type": "party",
            "id": "pty_xxx"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": false,
      "nextCursor": null
    }
  }
}
```

### Exit codes

| Code | Meaning                                    | Action                           |
| ---- | ------------------------------------------ | -------------------------------- |
| 0    | Success                                    | Parse JSON response              |
| 1    | Business error (wallet not accessible)     | Read error message, do not retry |
| 3    | Auth error (missing or invalid API key)    | Check credentials                |
| 4    | Network/server error (timeout, rate limit) | Retry                            |

### Notes

- Always pass `--format json` — human-formatted output is not designed for agent parsing
- Amounts are always minor units (cents) in both input and output
- Pass the format flag explicitly for clarity, even when stdout is piped

---

## MCP Adapter

Execute delegated customer balance lookup using Natural MCP server tools. The MCP server authenticates via Bearer token in the session.

### Tool

Tool: `get_account_balance`

```json
{
  "customerPartyId": "pty_xxx"
}
```

Returns the customer's wallet balance for the provided `customerPartyId`.

### Error handling

MCP tool errors are returned as tool call failures with an error message. Categorize by the message content:

- Authentication errors: API key issues
- Business errors: wallet not accessible
- Server errors: retry the request