API Documentation

curl https://iwkey.com/v1/models \ -H "Authorization: Bearer $IWKEY_KEY"

curl https://iwkey.com/v1/usage \ -H "Authorization: Bearer <your API Key>"

{ "isValid": true, "mode": "unrestricted", "balance": 61.66, "remaining": 61.66, "unit": "USD", "usage": { "today": { "requests": 12, "total_tokens": 48210, "actual_cost": 0.42 }, "total": { "requests": 1893, "total_tokens": 9120000, "actual_cost": 38.34 }, "rpm": 0, "tpm": 0 } }

#!/usr/bin/env python3 """IWKey balance alert: check the balance hourly and push to Feishu / DingTalk / WeCom / Telegram when it falls below your line. Python standard library only. Environment variables: IWKEY_KEY the API key you call models with NOTIFY_CHANNEL feishu / dingtalk / wecom / telegram (pick one) Feishu: FEISHU_WEBHOOK (add FEISHU_SECRET if the bot has signature verification) WeCom: WECOM_WEBHOOK DingTalk: DINGTALK_WEBHOOK (add DINGTALK_SECRET if the bot uses "Sign" security) Telegram: TG_BOT_TOKEN, TG_CHAT_ID LOW_USD / CRIT_USD low / critical line in USD, default 40 / 10 Schedule it (crontab, hourly): 0 * * * * /usr/bin/python3 /path/to/balance_alert.py >> balance_alert.log 2>&1 Behaviour: one alert for Low and one for Critical; a failed query is not treated as low balance, and 3 failures in a row raise a 'monitor is down' alert.""" import base64 import hashlib import hmac import json import os import time import urllib.parse import urllib.request from pathlib import Path API = "https://iwkey.com/v1/usage" KEY = os.environ.get("IWKEY_KEY", "") CHANNEL = os.environ.get("NOTIFY_CHANNEL", "feishu") # feishu / wecom / dingtalk / telegram LOW = float(os.environ.get("LOW_USD", "40")) CRIT = float(os.environ.get("CRIT_USD", "10")) STATE = Path(os.environ.get("STATE_FILE", str(Path.home() / ".iwkey_balance_alert.json"))) TIERS = ["Normal", "Low", "Critical"] UA = "balance-alert/1.0" # a User-Agent is required, otherwise Cloudflare may block the request (403 / connection failure) def http_json(url, payload=None, headers=None): data = json.dumps(payload).encode() if payload is not None else None h = {"User-Agent": UA, **(headers or {})} if data: h["Content-Type"] = "application/json" req = urllib.request.Request(url, data=data, headers=h) with urllib.request.urlopen(req, timeout=15) as r: return json.loads(r.read().decode()) def query_balance(): data = http_json(API, headers={"Authorization": f"Bearer {KEY}"}) usd = float(data.get("balance", data.get("remaining"))) return usd, f"${usd:.2f}" def send_once(text): if CHANNEL == "feishu": # Feishu custom-bot webhook payload = {"msg_type": "text", "content": {"text": text}} secret = os.environ.get("FEISHU_SECRET") if secret: # only needed if the bot has signature verification on ts = str(int(time.time())) key = f"{ts}\n{secret}".encode() payload["timestamp"] = ts payload["sign"] = base64.b64encode(hmac.new(key, b"", hashlib.sha256).digest()).decode() return http_json(os.environ["FEISHU_WEBHOOK"], payload).get("code") == 0 if CHANNEL == "wecom": # WeCom group-bot webhook res = http_json(os.environ["WECOM_WEBHOOK"], {"msgtype": "text", "text": {"content": text}}) return res.get("errcode") == 0 if CHANNEL == "dingtalk": # DingTalk group custom robot webhook url = os.environ["DINGTALK_WEBHOOK"] secret = os.environ.get("DINGTALK_SECRET") if secret: # only if the bot uses "Sign" security ts = str(int(time.time() * 1000)) digest = hmac.new(secret.encode(), f"{ts}\n{secret}".encode(), hashlib.sha256).digest() url += f"&timestamp={ts}&sign={urllib.parse.quote_plus(base64.b64encode(digest))}" res = http_json(url, {"msgtype": "text", "text": {"content": text}}) return res.get("errcode") == 0 if CHANNEL == "telegram": # Telegram bot (usually unreachable from mainland-China servers) url = f"https://api.telegram.org/bot{os.environ['TG_BOT_TOKEN']}/sendMessage" return http_json(url, {"chat_id": os.environ["TG_CHAT_ID"], "text": text}).get("ok") is True raise SystemExit("NOTIFY_CHANNEL must be feishu, wecom, dingtalk or telegram") def notify(text): for i in range(3): try: if send_once(text): return True print("message rejected, will retry") except Exception as e: print(f"send error: {type(e).__name__}") # log the exception type only, never the URL, so tokens stay out of logs time.sleep(2 ** i) return False def load_state(): try: return json.loads(STATE.read_text()) except Exception: return {"tier": 0, "fails": 0, "down_alerted": False} def main(): if not KEY: raise SystemExit("Set IWKEY_KEY first") st = load_state() try: usd, shown = query_balance() except Exception as e: st["fails"] += 1 print(f"query failed (#{st['fails']}): {type(e).__name__}") if st["fails"] >= 3 and not st["down_alerted"]: if notify("[IWKey balance monitor] 3 consecutive balance queries failed. The monitor may be down; check the network or API key."): st["down_alerted"] = True STATE.write_text(json.dumps(st)) return st["fails"], st["down_alerted"] = 0, False tier = 2 if usd < CRIT else 1 if usd < LOW else 0 if tier > st["tier"]: # alert only when it drops into a worse tier; no repeats within a tier line = CRIT if tier == 2 else LOW msg = (f"[IWKey balance {TIERS[tier].lower()}] Available balance is {shown}, " f"below the {TIERS[tier].lower()} line of ${line:.0f}. Please top up to avoid interrupted calls.") if notify(msg): st["tier"] = tier # record the tier only after a successful send; a failed send retries next run elif tier < st["tier"] and (tier > 0 or usd >= LOW * 1.2): # recovered only above 1.2x the low line, to avoid flapping around it st["tier"] = tier if tier == 0: notify(f"[IWKey balance recovered] Available balance is {shown}.") print(f"balance ${usd:.2f}, tier {TIERS[st['tier']]}") STATE.write_text(json.dumps(st)) if __name__ == "__main__": main()