> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# API Reference — Postpaid Wallets

Check accrued postpaid usage and report billable events. Endpoints live on the **Control Plane API** at `https://cp-api.withpaygent.com` and authenticate with your `paygent-api-key` header.

> **Prerequisites**
>
> Postpaid wallets are created in the **dashboard only** (Customer → Wallet → Postpaid). The agent indicator must use **CREDITS** billing with the same credit currency as the wallet. See [Credits & Wallets](/documentation/introduction/credits-and-wallets).

## Authentication

**`Header`**

```bash title="Header"
paygent-api-key: YOUR_API_KEY
```

> **API key in header only**
>
> Pass `paygent-api-key` as an HTTP header, not as a query parameter.

---

## Get postpaid accrual

`GET /api/v1/wallet/balance` returns all wallets for a customer. For postpaid wallets, use `postpaid_used` and `postpaid_limit` only—do not use `available` (it stays 0).

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v1/wallet/balance?customer_id=wallet-post-1' \
--header 'accept: application/json' \
--header 'paygent-api-key: YOUR_API_KEY'
```

### Example response (postpaid)

**`200 OK`**

```json title="200 OK"
{
  "balances": {
    "cx": {
      "available": 0,
      "pending": 0,
      "overage_used": 0,
      "overage_limit": 0,
      "postpaid_used": 30,
      "postpaid_limit": 0
    }
  }
}
```

### Postpaid response fields

| Field            | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `postpaid_used`  | Credits accrued this billing period. Resets after invoice is generated. |
| `postpaid_limit` | Hard stop limit. `0` = no enforced limit.                               |

---

## Send usage (accrue postpaid)

`POST /api/v2/usage` reports usage and accrues credits on the postpaid wallet when the indicator is priced in **CREDITS**. Processing is async via Kafka; balance updates within a few seconds.

**`cURL`**

```bash title="cURL"
curl --location 'https://cp-api.withpaygent.com/api/v2/usage' \
--header 'accept: application/json' \
--header 'paygent-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "agentId": "postpaid_1",
  "customerId": "wallet-post-1",
  "indicator": "per_minute",
  "rawUsage": {
    "provider": "OPENAI",
    "model": "gpt-4o-mini",
    "plan": "default",
    "inputTokens": 120,
    "outputTokens": 80
  }
}'
```

Alternatively use the Python SDK: `client.send_usage(agent_id, customer_id, indicator, usage_data)`. For local testing, set `client.base_url` to your Control Plane host.

---

## Postpaid integration flow

1. `GET /api/v1/wallet/balance` — read `postpaid_used` and `postpaid_limit`.
2. If under the limit (or limit is 0), perform the LLM / API work.
3. `POST /api/v2/usage` — accrue usage on the postpaid wallet.
4. Customer is invoiced at period end; `postpaid_used` resets to 0.

**`Example (Python)`**

```python title="Example (Python)"
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://cp-api.withpaygent.com"
CUSTOMER = "wallet-post-1"
CURRENCY = "cx"

# 1. Check postpaid limit before usage
resp = requests.get(
    f"{BASE}/api/v1/wallet/balance",
    params={"customer_id": CUSTOMER},
    headers={"paygent-api-key": API_KEY},
)
state = resp.json()["balances"].get(CURRENCY, {})
used = state.get("postpaid_used", 0)
limit = state.get("postpaid_limit", 0)
if limit > 0 and used >= limit:
    raise Exception("Postpaid credit limit reached")

# 2. After successful work, send usage
# client.send_usage("postpaid_1", CUSTOMER, "per_minute", usage_data)
```

> **Not supported via API**
>
> Postpaid wallet **creation** and **top-up** are not available on the public API. Use the dashboard to create postpaid wallets.

---

Prepaid wallets: [Prepaid Wallets API](/api-reference/prepaid-wallets-api)