---
name: billing-monitor
description: "Monitor for API billing errors and alert the owner and admin immediately. Use when: an API billing error is detected, a peer PA reports a billing error, or during routine health checks. Handles detection, notification, and fallback model switching. Model-agnostic: works with any LLM provider (Anthropic, OpenAI, Google, etc.)."
---

# Billing Monitor Skill

## Minimum Model
Any model. Detection and alerting are rule-based. No reasoning required.

---

## When to Run This Skill

Run when you see ANY of these in an API response:
```
your API key has run out of credits
insufficient balance
billing_error
payment_required
exceeded your current quota
HTTP 402
"type": "billing_error"
```

## When NOT to Alert the Owner

- Routine billing check completed with no errors → **silent, no message**
- HTTP 200 / all clear → **silent, no message**
- ElevenLabs 401 (auth, not billing) → **silent unless TTS is actively needed**

**Only alert the owner if:**
1. HTTP 402 detected (out of credits)
2. LLM is unreachable and the agent cannot function
3. A peer PA reports a billing error

Routine health checks run silently. The owner does not need a "billing OK" message.

---

## Response Steps (Run in Order)

### Step 1 — Notify Owner

Send via WhatsApp (or preferred channel):

```
⚠️ Billing issue — I can't respond normally.
My API key ran out of credits (or was rate-limited).
Please top up or switch my API key in agent settings.
```

### Step 2 — Notify Admin

```
[PA Name] has a billing error.
Owner: [Owner Name]
Action: top up API credits or reassign key.
Time: [current timestamp]
```

### Step 3 — Switch to Fallback Model

1. Check if `config/billing-fallback.json` exists
2. If yes → read the `fallback_model` field
3. Run: `openclaw config set model "$FALLBACK_MODEL"`
4. If the command fails → tell owner: "Auto-switch failed — please update model manually in agent settings"
5. Notify owner: "Switched to [Fallback Model] temporarily while primary key is resolved"

If `billing-fallback.json` doesn't exist → skip this step and tell admin to configure it.

### Step 4 — Log the Incident

```bash
LOG_DIR="$HOME/.openclaw/workspace/logs"
mkdir -p "$LOG_DIR"

# Append one line to the log file
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) BILLING_ERROR api_key_exhausted" \
  >> "$LOG_DIR/billing-incidents.log"
```

---

## Health Check Script

Run this during heartbeat to catch billing issues before they cause failures:

```bash
#!/bin/bash
# billing-check.sh
# Checks the LLM provider API key configured in env vars

set -e

LOG_DIR="$HOME/.openclaw/workspace/logs"
mkdir -p "$LOG_DIR"
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# Detect provider from env vars (check in order)
if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  PROVIDER="Anthropic"
  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "x-api-key: ${ANTHROPIC_API_KEY}" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "{\"model\":\"claude-haiku-20240307\",\"max_tokens\":1,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}" \
    https://api.anthropic.com/v1/messages 2>/dev/null)

elif [ -n "${OPENAI_API_KEY:-}" ]; then
  PROVIDER="OpenAI"
  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "Authorization: Bearer ${OPENAI_API_KEY}" \
    -H "content-type: application/json" \
    -d "{\"model\":\"gpt-4o-mini\",\"max_tokens\":1,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}" \
    https://api.openai.com/v1/chat/completions 2>/dev/null)

elif [ -n "${GOOGLE_API_KEY:-}" ]; then
  PROVIDER="Google"
  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    "https://generativelanguage.googleapis.com/v1beta/models?key=${GOOGLE_API_KEY}" 2>/dev/null)

else
  echo "$TIMESTAMP SKIP no API key env var found" >> "$LOG_DIR/billing-incidents.log"
  exit 0
fi

# Act on the HTTP status code
case "$HTTP_STATUS" in
  200)
    echo "$TIMESTAMP OK $PROVIDER" >> "$LOG_DIR/billing-incidents.log"
    ;;
  402)
    echo "$TIMESTAMP BILLING_ERROR $PROVIDER HTTP_402" >> "$LOG_DIR/billing-incidents.log"
    echo "BILLING ERROR — run the 4-step response protocol above"
    exit 1
    ;;
  401)
    echo "$TIMESTAMP AUTH_ERROR $PROVIDER HTTP_401" >> "$LOG_DIR/billing-incidents.log"
    echo "AUTH ERROR — invalid API key, notify admin"
    exit 1
    ;;
  429)
    echo "$TIMESTAMP RATE_LIMITED $PROVIDER HTTP_429" >> "$LOG_DIR/billing-incidents.log"
    echo "RATE LIMITED — wait 60 seconds and retry. Not a billing issue."
    exit 2
    ;;
  *)
    echo "$TIMESTAMP UNKNOWN $PROVIDER HTTP_$HTTP_STATUS" >> "$LOG_DIR/billing-incidents.log"
    echo "UNKNOWN ERROR HTTP $HTTP_STATUS"
    exit 1
    ;;
esac
```

**HTTP status meanings:**
- `200` → OK
- `402` → Billing error → run 4-step protocol
- `401` → Invalid key → notify admin
- `429` → Rate limit (temporary) → wait and retry, do NOT trigger billing protocol

---

## Fallback Config File

Create `config/billing-fallback.json` in your workspace:

```json
{
  "primary_provider": "your-primary-provider",
  "primary_model": "your-primary-model",
  "fallback_provider": "your-fallback-provider",
  "fallback_model": "your-fallback-model",
  "admin_phone": "+1XXXXXXXXXX",
  "alert_channel": "whatsapp"
}
```

Replace placeholders with real values. Examples:
- Anthropic → OpenAI: `"primary_provider": "anthropic"`, `"primary_model": "claude-haiku-20240307"`, `"fallback_provider": "openai"`, `"fallback_model": "gpt-4o-mini"`

---

## Recovery (After Credits Restored)

1. Owner confirms credits are topped up.
2. Read the primary model name from config:
   ```bash
   PRIMARY=$(python3 -c "
   import json
   with open('config/billing-fallback.json') as f:
       print(json.load(f)['primary_model'])
   ")
   ```
3. Switch back to primary:
   ```bash
   openclaw config set model "$PRIMARY"
   ```
4. Log the recovery:
   ```bash
   echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) BILLING_RESTORED" \
     >> ~/.openclaw/workspace/logs/billing-incidents.log
   ```
5. Notify owner: "✅ Primary model restored. Normal service resumed."

---

## Edge Cases

| Scenario | Action |
|---|---|
| 429 rate limit | Wait 60s, retry. Do NOT trigger billing protocol. |
| 5xx server error | Retry 2x with 10s delay. If persists → notify owner. |
| Both primary AND fallback billing errors | Escalate to admin immediately. Agent cannot function. |
| No API key env var set | Log as config issue. Notify admin. |
| Peer PA reports billing error | Log it. Notify admin if you are the network coordinator. |

---

## Cost Tips

- **Cheap:** Health checks with `curl` — no LLM cost at all
- **Expensive:** Running health checks too frequently wastes money. Every 2 hours is enough.
- **Batch:** Combine billing check with other heartbeat checks in one script run
- **Small model OK:** This skill needs no reasoning — any model can send a notification message

---

## Running via Cron (Recommended)

Instead of a plugin, run billing-monitor as a scheduled skill via cron:

```json
{
  "id": "billing-health-check",
  "schedule": { "kind": "cron", "expr": "0 * * * *", "tz": "UTC" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Run the billing-monitor skill: check all configured API keys for billing errors. If any provider returns 402, send an alert to the admin phone and update billing-status.json. Reply HEARTBEAT_OK if all clear."
  },
  "delivery": { "mode": "silent" }
}
```

This runs every hour and alerts automatically — no plugin required.


---
Source attribution: netanel-abergel
Original project: https://github.com/netanel-abergel/pa-skills/blob/ca4344f33175b78797352bb9e8cdec864eff492d/skills/billing-monitor/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 Netanel Abergel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: netanel-abergel
Original project: https://github.com/netanel-abergel/pa-skills/blob/ca4344f33175b78797352bb9e8cdec864eff492d/skills/billing-monitor/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Customer Support
Roles: DevOps / SRE, ML / AI Engineer, Technical Support
Specialties: API
Tools: WhatsApp
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 91f342da71345945676c30db3c483e1192f648ee6b8d5678a1461b24230debc7