Feature Request: Add Zen balance API endpoint

Summary

Add a public API endpoint to query the current Zen account balance programmatically.

Use Case

I'd like to display my Zen balance in my system status bar (waybar on Linux). Currently, the only way to check balance is through the web dashboard, which makes automation impossible.

A simple endpoint like GET /zen/v1/balance (authenticated with the existing API key) would enable:

Status bar widgets showing remaining credits
Alerts when balance drops below a threshold
Integration with budgeting/monitoring tools
CI pipelines that check balance before expensive runs

Proposed API

GET https://opencode.ai/zen/v1/balance
Authorization: Bearer <api-key>

Response:
{
  "balance": 42.50,
  "currency": "USD",
  "auto_reload": {
    "enabled": true,
    "threshold": 5.00,
    "amount": 20.00
  }
}

Workaround

Currently using opencode stats to track local spending, but this doesn't reflect the actual account balance.

Additional Context

The auto-reload feature suggests the infrastructure to query balance already exists server-side. Exposing it via API would be a small addition with high utility for power users.

Thanks for building such a great tool! 🙏

This issue might be a duplicate of existing issues. Please check:

Feature Request: Add Zen balance API endpoint #10447: Feature Request: Add Zen balance API endpoint

Feel free to ignore if this doesn't address your specific case.

+1, I'm also trying to build a centralized monitoring tool for model usage across different subscription/API providers, and this would be very helpful

Same need here. I'm trying to build a macOS menu bar app to display the current balance so I don't have to navigate to the web dashboard.

feat(opencode-go): add dashboard-scrape usage provider

Also could unlock usage monitoring for OpenChamber: openchamber/openchamber#1357

Fix opencode-go limit judgment: tunable thresholds + zen credit detec…

feat(opencode_go_usage): new plugin for OpenCode Go subscription quota

Cross-linking a downstream integration affected by the missing Zen/Go quota API: OmniRoute issue cheaper-inference/OmniRoute#3844 and diagnostic PR cheaper-inference/OmniRoute#3838 . We verified that a real OpenCode Go key works for chat completions, but quota-style endpoints return either 404 or non-JSON fallback responses. OmniRoute can only show diagnostics until OpenCode exposes a supported public endpoint.

Is there a better place to report this upstream? Seems to be quite a common and obvious requirement, needed by a lot of people, but it would need to be implemented server-side by the Anomaly team, not here in this repo.

Extending this request: monthly window + last top-up anchor

#41981 (closed as dup of this) asked for balance + monthly usage/limit + reset timestamps on the usage API. Folding that scope in here:

The existing GET /zen/go/v1/usage (#16513) returns plan-window percentages only — no monetary amounts. For Zen balance-billing workspaces, quota tools (opencode-quota, etc.) still scrape the billing page HTML. Proposal: sibling endpoint GET /zen/v1/workspace/usage returning:

{
  "generatedAt": "...",
  "currency": "USD",
  "balance": {
    "amount": 12.34,
    "updatedAt": "...",
    "percentOfLastTopUp": 61.7,
    "lastTopUp": { "amount": 20.00, "at": "..." }
  },
  "usage": {
    "monthly": {
      "status": "ok",
      "used": 42.10,
      "limit": 100.00,
      "remaining": 57.90,
      "percent": 42.1,
      "resetsAt": "..."
    }
  }
}

Key points:

percentOfLastTopUp = balance / lastTopUp.amount * 100 — "of what I last paid, X% remains"; server-computed, null when no anchor
Monthly window mirrors the go endpoint's shape but with absolute USD values (server owns the math, kills the 100M-units conversion clients hardcode)
status server-derived: ok / near_limit / rate_limited / blocked

feat(opencode-zen): pay-as-you-go balance via billing-page scrape

docs: TODO for zen balance display pending upstream API

Docs: align privacy network-call list and roadmap with 0.4.34

feat(desktop): 模型池端点化改造 + 端点额度监听

Correct what OpenCode exposes: Go's limits are open to its key

feat(opencode-usage): OpenCode Go plan windows + local Zen usage panel

Use case: at-a-glance usage in a status bar

+1 from a waybar integration. I'm hitting the same problem as several people above — I want a small status-bar widget that shows me my rolling / weekly / monthly usage percentages and my Zen balance, so I know whether I'm on track for the month without opening the dashboard.

A GET /zen/v1/workspace/usage (or equivalent Bearer-friendly endpoint) that returns the workspace's balance in USD plus the existing plan-window percentages would unblock this and the other status-bar / menu-bar / monitoring-tool integrations people have mentioned (OmniRoute, OpenChamber, etc.).

Concrete fields that would cover the common case:

{
  "currency": "USD",
  "balance": { "amount": 12.34, "updatedAt": "..." },
  "usage": {
    "rolling": { "used": 0.43,  "limit": 12.00, "percent": 4,  "resetsAt": "..." },
    "weekly":  { "used": 6.74,  "limit": 30.00, "percent": 22, "resetsAt": "..." },
    "monthly": { "used": 11.24, "limit": 60.00, "percent": 19, "resetsAt": "..." }
  }
}

I've already wrapped /console/api/go/status (it works for a service-account key) and it returns the three windows in roughly this shape. The blocker on my side is just the balance — /console/api/billing/status returns 403 for service-account Bearer tokens, so the balance is only reachable via browser session cookies, which doesn't fit a long-running status-bar poll. If billing returned the same shape as the proposed endpoint above but rejected service-account keys by design, that's fine to know — I can fall back to omitting balance from the widget until a non-cookie path exists.

This isn't a complaint, just a data point: every status-bar / monitoring / dashboard integration I've seen wants the same small surface, and consolidating it into a single Bearer-friendly endpoint would save us all from scraping /console HTML.

@uwagz

Thanks for the clear write-up, @uwagz!

To restate the request: you'd like a public API endpoint, authenticated with your existing Zen API key (e.g. GET /zen/v1/balance), that returns your current Zen balance and auto-reload settings. That way you could show the balance in a status bar like waybar, get low-balance alerts, or check it from CI before expensive runs.

Right now the balance is only available in the web console. This needs a new endpoint on the Zen service, so it can't be added with an OpenCode plugin. The maintainers will consider it. If anyone else would find this useful, a 👍 on the issue helps show demand.

Navigation Menu

Repository navigation

Feature Request: Add Zen balance API endpoint #10448

Summary

Use Case

Proposed API

Workaround

Additional Context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: Add Zen balance API endpoint #10448

Description

Summary

Use Case

Proposed API

Workaround

Additional Context

Activity

github-actions commented on Jan 24, 2026

emmaneugene commented on Feb 14, 2026

aaesalamanca commented on Mar 4, 2026

mderazon commented on May 22, 2026

adivekar-utexas commented on Jun 14, 2026

rossigee commented on Jul 12, 2026

vmvarela commented on Aug 12, 2026

joeskeen commented on Sep 20, 2026

opencodejr commented on Oct 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions