hermes - 💡(How to fix) Fix Feature Request: Nous Portal credit balance API endpoint for CLI usage monitoring [4 comments, 1 participants]

🔧 Feature Request: Nous Portal Credit Balance API

Problem

Hermes Agent supports credit balance monitoring for OpenRouter (/credits), Anthropic (/api/oauth/usage), and OpenAI Codex via account_usage.py. However, Nous Portal users have no programmatic way to check their remaining credits or daily usage from the CLI or via automation (cron jobs, Telegram alerts, etc.).

Currently, Nous Portal users must:

1. Open a browser
2. Navigate to portal.nousresearch.com/usage
3. Manually check credit balance

This is a pain point for headless/Telegram workflows where browser access is inconvenient or impossible.

Comparison with Other Providers

Suggested API Design

A simple REST endpoint following the existing /api/ pattern used by /api/oauth/agent-key:

GET /api/account/credits
Authorization: Bearer <access_token>

Response:
{
  "balance_usd": 42.50,
  "subscription_tier": "Plus",
  "monthly_limit_usd": 50.00,
  "used_this_month_usd": 7.50,
  "usage_history": [
    {"date": "2026-05-13", "cost_usd": 1.20, "model": "qwen3.6-plus"},
    {"date": "2026-05-12", "cost_usd": 3.10, "model": "claude-sonnet-4"}
  ],
  "resets_at": "2026-06-01T00:00:00Z"
}

Alternatively, even a minimal endpoint returning just balance_usd and subscription_tier would be a huge improvement.

Impact

• Every Nous Portal subscriber would benefit
• Enables cron-based balance alerts (Telegram, Discord, etc.)
• Enables account_usage.py to add _fetch_nous_account_usage()
• Aligns Hermes with its "transparent usage monitoring" mission

Context

This issue was discovered during research for integrating Nous credit monitoring into Hermes Agent via Telegram. Community search (GitHub Issues, Reddit r/hermesagent, X/Twitter) shows no existing discussion about this gap.

Thank you for building an amazing platform.