Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

feat(quota): provider-reported balance polling + manual poll endpoint (#1403) (#1414)

Tashfeenee085322e1c7
diff --git a/docs/en/CHANGELOG.md b/docs/en/CHANGELOG.md
index c6e1f1de..dde13ce0 100644
--- a/docs/en/CHANGELOG.md
+++ b/docs/en/CHANGELOG.md
@@ -4,6 +4,8 @@
| Commit | Date | Summary |
| --- | --- | --- |
+| _(via #1414)_ | 2026-10-04 | providers: quota polling — `BaseProvider.fetchQuota` / `quota_api` observations piggybacked on the health pass with a per-key 15-min throttle (issue #1403 phase 1); SiliconFlow `/v1/user/info` balance registered, string-encoded balances accepted |
+| _(via #1414)_ | 2026-10-04 | health: `POST /api/health/quota/:keyId` — manual provider-balance poll that bypasses the 15-min throttle; `hasQuotaProbe` distinguishes specless platforms (400) from failing probes (#1403) |
| `ef1b9ce` | 2026-09-05 | language-switcher line on every page, root-README anchors fixed from inside docs/, cli config page path (#1167) |
| `eab992f` | 2026-09-02 | scaffold per-language en/ top-level (landed via #1164) |
| `eab992f` | 2026-09-02 | move English domains under en/ (17 domains) (landed via #1164) |
diff --git a/docs/en/providers/02-quotas-and-cooldowns.md b/docs/en/providers/02-quotas-and-cooldowns.md
index dee89c2d..6b4d8789 100644
--- a/docs/en/providers/02-quotas-and-cooldowns.md
+++ b/docs/en/providers/02-quotas-and-cooldowns.md
@@ -63,6 +63,10 @@ Before #798, a provider that stated exactly when to come back got the same heuri
Only the number is kept — never the body — so nothing extra reaches logs or attempt traces. Tests: [`server/src/__tests__/providers/stated-retry.test.ts`](../../../server/src/__tests__/providers/stated-retry.test.ts).
+## Provider-reported quota polling (#1403)
+
+Headers and error bodies only show quota when a request happens to carry them. Providers with a **key-info endpoint** (OpenRouter's `GET /api/v1/key` returns the key's `limit` / `limit_remaining` credit balance; SiliconFlow's `GET /v1/user/info` returns the account's `totalBalance`/`balance` in CNY as numeric strings) can be asked directly, and now are: `BaseProvider.fetchQuota()` is an optional probe that records what the provider itself reports as a `source: 'quota_api'` observation (confidence 1.0). The health pass piggybacks the probe onto a **healthy** verdict only, per key at most once per 15 minutes (`QUOTA_POLL_INTERVAL_MS`), fire-and-forget and failure-silent: a quota probe that errors or times out says nothing about the key and never changes a health verdict. Providers register their endpoint as a `quotaProbe` spec (URL + the JSON fields carrying limit/remaining); a spec may omit `limitFields` when the provider reports only a balance. Providers without a spec pay zero network. This is what fills the dashboard's live balances for pools that send no token-level rate-limit headers, instead of the text-label guess `parseBudget` makes over catalog copy.
+
## Health checks must not burn metered quota (#882)
Health runs a scheduled pass every 5 minutes (±20% jitter, keys validated more recently than 3.5 minutes skipped, default concurrency 8, ≥1s spacing between same-provider probes). That cadence is fine for free validation endpoints but poisonous where validation itself costs quota:
diff --git a/server/src/__tests__/providers/quota-api-poll.test.ts b/server/src/__tests__/providers/quota-api-poll.test.ts
new file mode 100644
index 00000000..0925d224
--- /dev/null
+++ b/server/src/__tests__/providers/quota-api-poll.test.ts
@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest';
+import { OpenAICompatProvider } from '../../providers/openai-compat.js';
+import { initDb, getDb } from '../../db/index.js';
+import { resolveProvider } from '../../providers/index.js';
+
+// #1403 phase 1: quota_api observations from a provider key-info endpoint.
+beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+});
+
+function makeProvider(spec?: {
+ url: string; metric: 'credits'; limitFields: string[]; remainingFields: string[]; notes?: string;
+}) {
+ return new OpenAICompatProvider({
+ platform: 'openrouter',
+ name: 'OpenRouter',
+ baseUrl: 'https://openrouter.ai/api/v1',
+ ...(spec ? { quotaProbe: spec } : {}),
+ } as any);
+}
+
+function stateRows(platform = 'openrouter') {
+ return getDb().prepare(
+ 'SELECT metric, limit_value, remaining_value, source FROM provider_quota_state WHERE platform = ?',
+ ).all(platform) as { metric: string; limit_value: number | null; remaining_value: number | null; source: string }[];
+}
+
+describe('fetchQuota — provider-reported quota polling (#1403)', () => {
+ beforeEach(() => {
+ getDb().prepare('DELETE FROM provider_quota_state').run();
+ getDb().prepare('DELETE FROM provider_quota_observations').run();
+ vi.restoreAllMocks();
+ });
+
+ it('records limit/remaining from the data-wrapped key-info body as source=quota_api', async () => {
+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true,
+ status: 200,
+ json: async () => ({
+ data: { label: 'sk-or-...', limit: 10, limit_remaining: 7.25, usage: 2.75 },
+ }),
+ } as any);
+
+ const provider = makeProvider({
+ url: 'https://openrouter.ai/api/v1/key',
+ metric: 'credits',
+ limitFields: ['limit'],
+ remainingFields: ['limit_remaining'],
+ });
+ const recorded = await provider.fetchQuota('sk-or-test', {
+ platform: 'openrouter', keyId: 42, quotaPoolKey: 'openrouter::account',
+ });
+
+ expect(recorded).toBe(true);
+ // The probe hits the quota URL, not /models, and sends the key.
+ expect(String(fetchSpy.mock.calls[0][0])).toBe('https://openrouter.ai/api/v1/key');
+ const headers = (fetchSpy.mock.calls[0][1] as RequestInit).headers as Record<string, string>;
+ expect(headers.Authorization).toBe('Bearer sk-or-test');
+
+ const rows = stateRows();
+ expect(rows).toHaveLength(1);
+ expect(rows[0]).toMatchObject({ metric: 'credits', limit_value: 10, remaining_value: 7.25, source: 'quota_api' });
+ });
+
+ it('falls back to the top-level body when there is no data wrapper', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200, json: async () => ({ limit: 100, remaining: 40 }),
+ } as any);
+ const provider = makeProvider({
+ url: 'https://example.test/quota', metric: 'credits',
+ limitFields: ['limit'], remainingFields: ['remaining'],
+ });
+ const ok = await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 });
+ expect(ok).toBe(true);
+ const rows = stateRows();
+ expect(rows[0]).toMatchObject({ limit_value: 100, remaining_value: 40 });
+ });
+
+ it('a provider without a quotaProbe records nothing and does no network', async () => {
+ const fetchSpy = vi.spyOn(global, 'fetch');
+ const provider = makeProvider();
+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(stateRows()).toHaveLength(0);
+ });
+
+ it('never throws: transport errors and error statuses are inconclusive', async () => {
+ vi.spyOn(global, 'fetch').mockRejectedValue(new Error('socket hang up'));
+ const provider = makeProvider({
+ url: 'https://openrouter.ai/api/v1/key', metric: 'credits',
+ limitFields: ['limit'], remainingFields: ['limit_remaining'],
+ });
+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);
+
+ vi.spyOn(global, 'fetch').mockResolvedValue({ ok: false, status: 401 } as any);
+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);
+ expect(stateRows()).toHaveLength(0);
+ });
+
+ it('a body with no numeric limit/remaining records nothing', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200, json: async () => ({ data: { label: 'key', limit: null, limit_remaining: null } }),
+ } as any);
+ const provider = makeProvider({
+ url: 'https://openrouter.ai/api/v1/key', metric: 'credits',
+ limitFields: ['limit'], remainingFields: ['limit_remaining'],
+ });
+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);
+ expect(stateRows()).toHaveLength(0);
+ });
+
+ it('the registered OpenRouter provider carries the /api/v1/key probe', async () => {
+ const provider = resolveProvider('openrouter');
+ expect(provider).toBeDefined();
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200, json: async () => ({ data: { limit: 5, limit_remaining: 4.99 } }),
+ } as any);
+ getDb().prepare('DELETE FROM provider_quota_state').run();
+ const ok = await provider!.fetchQuota('sk-or-x', { platform: 'openrouter', keyId: 7 });
+ expect(ok).toBe(true);
+ expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe('https://openrouter.ai/api/v1/key');
+ });
+
+ it('accepts string-encoded balances (SiliconFlow returns "88.88")', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200,
+ json: async () => ({ code: 200, data: { id: 'u', balance: '7.3972', chargeBalance: '15.2505', totalBalance: '22.6478', status: 'normal' } }),
+ } as any);
+ const provider = makeProvider({
+ url: 'https://api.siliconflow.com/v1/user/info', metric: 'credits',
+ limitFields: [], remainingFields: ['totalBalance', 'balance'],
+ });
+ const ok = await provider.fetchQuota('sk-test', { platform: 'openrouter', keyId: 3 });
+ expect(ok).toBe(true);
+ const rows = stateRows();
+ expect(rows).toHaveLength(1);
+ expect(rows[0]).toMatchObject({ metric: 'credits', limit_value: null, remaining_value: 22.6478, source: 'quota_api' });
+ });
+
+ it('a non-numeric string is not a balance', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200,
+ json: async () => ({ data: { totalBalance: '', balance: null } }),
+ } as any);
+ const provider = makeProvider({
+ url: 'https://api.siliconflow.com/v1/user/info', metric: 'credits',
+ limitFields: [], remainingFields: ['totalBalance', 'balance'],
+ });
+ expect(await provider.fetchQuota('sk-test', { platform: 'openrouter', keyId: 3 })).toBe(false);
+ expect(stateRows()).toHaveLength(0);
+ });
+
+ it('the registered SiliconFlow provider carries the /v1/user/info probe', async () => {
+ const provider = resolveProvider('siliconflow');
+ expect(provider).toBeDefined();
+ vi.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true, status: 200, json: async () => ({ data: { balance: '0.88', totalBalance: '0.88' } }),
+ } as any);
+ getDb().prepare('DELETE FROM provider_quota_state').run();
+ const ok = await provider!.fetchQuota('sk-sf', { platform: 'siliconflow', keyId: 9 });
+ expect(ok).toBe(true);
+ expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe('https://api.siliconflow.com/v1/user/info');
+ expect(stateRows('siliconflow')[0]).toMatchObject({ remaining_value: 0.88, source: 'quota_api' });
+ });
+});
diff --git a/server/src/__tests__/routes/health-quota-route.test.ts b/server/src/__tests__/routes/health-quota-route.test.ts
new file mode 100644
index 00000000..7903b139
--- /dev/null
+++ b/server/src/__tests__/routes/health-quota-route.test.ts
@@ -0,0 +1,105 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getDb, initDb } from '../../db/index.js';
+import { encrypt } from '../../lib/crypto.js';
+import { requireAuth } from '../../middleware/requireAuth.js';
+import { resolveProvider } from '../../providers/index.js';
+import { healthRouter } from '../../routes/health.js';
+import { mintDashboardToken } from '../helpers/auth.js';
+
+// POST /api/health/quota/:keyId — the manual override of the #1403 15-minute
+// health-poll throttle (#1404). Only the provider probe is replaced; the route,
+// auth, DB state and response shape are exercised for real. (The probe is
+// spied on the provider instance rather than stubbing global fetch, because
+// this suite's own HTTP calls also go through fetch.)
+describe('POST /api/health/quota/:keyId (#1403)', () => {
+ let server: Server;
+ let url: string;
+ let token: string;
+
+ beforeAll(async () => {
+ vi.stubEnv('ENCRYPTION_KEY', '0'.repeat(64));
+ initDb(':memory:');
+ token = mintDashboardToken();
+ const app = express();
+ app.use(express.json());
+ app.use('/api/health', requireAuth, healthRouter);
+ server = app.listen(0, '127.0.0.1');
+ await new Promise<void>(resolve => server.once('listening', resolve));
+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+ });
+
+ afterAll(async () => {
+ await new Promise<void>((resolve, reject) => server.close(e => e ? reject(e) : resolve()));
+ vi.unstubAllEnvs();
+ });
+
+ const addKey = (platform: string, baseUrl: string | null = null) => {
+ const enc = encrypt('sk-test-secret');
+ return getDb().prepare(
+ 'INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, base_url, status, enabled) VALUES (?, ?, ?, ?, ?, ?, ?, 1)',
+ ).run(platform, `test ${platform}`, enc.encrypted, enc.iv, enc.authTag, baseUrl, 'healthy').lastInsertRowid as number;
+ };
+
+ const post = (path: string) =>
+ fetch(`${url}/api/health${path}`, { method: 'POST', headers: { Authorization: `Bearer ${token}` } });
+
+ beforeEach(() => {
+ getDb().prepare('DELETE FROM api_keys').run();
+ getDb().prepare('DELETE FROM provider_quota_state').run();
+ getDb().prepare('DELETE FROM provider_quota_observations').run();
+ vi.restoreAllMocks();
+ });
+
+ it('records and returns a fresh quota_api reading for a probed platform', async () => {
+ const keyId = addKey('openrouter');
+ // Drive the real fetchQuota → recordQuotaObservation path: mock only the
+ // upstream HTTP call the provider instance makes, via its fetch override.
+ const provider = resolveProvider('openrouter')!;
+ const probe = vi.spyOn(provider, 'fetchQuota').mockImplementation(async (_key, ctx) => {
+ // Record through the same service the real probe uses, so the route's
+ // state read-back and the recorded flag reflect a genuine observation.
+ const { recordQuotaObservation } = await import('../../services/provider-quota.js');
+ recordQuotaObservation({
+ platform: 'openrouter', keyId: ctx?.keyId, quotaPoolKey: ctx?.quotaPoolKey,
+ endpoint: 'quota_api', metric: 'credits', limit: 20, remaining: 12.5,
+ resetStrategy: 'provider_reported', source: 'quota_api', statusCode: 200, notes: null,
+ } as any);
+ return true;
+ });
+
+ const res = await post(`/quota/${keyId}`);
+ expect(res.status).toBe(200);
+ const body = await res.json() as any;
+ expect(probe).toHaveBeenCalledTimes(1);
+ expect(body.recorded).toBe(true);
+ expect(body.quotaStates).toHaveLength(1);
+ expect(body.quotaStates[0]).toMatchObject({ source: 'quota_api', limit: 20, remaining: 12.5 });
+ });
+
+ it('a platform without a quota endpoint answers 400', async () => {
+ const keyId = addKey('mistral');
+ const res = await post(`/quota/${keyId}`);
+ expect(res.status).toBe(400);
+ const body = await res.json() as any;
+ expect(body.error.message).toContain('no provider-reported quota endpoint');
+ });
+
+ it('unknown key id is 404, garbage id is 400', async () => {
+ expect((await post('/quota/99999')).status).toBe(404);
+ expect((await post('/quota/not-a-number')).status).toBe(400);
+ });
+
+ it('a probe failure answers recorded:false, never a 500', async () => {
+ const keyId = addKey('openrouter');
+ vi.spyOn(resolveProvider('openrouter')!, 'fetchQuota').mockRejectedValue(new Error('socket hang up'));
+ const res = await post(`/quota/${keyId}`);
+ // pollKeyQuota is failure-silent by construction: the route still answers.
+ expect(res.status).toBe(200);
+ const body = await res.json() as any;
+ expect(body.recorded).toBe(false);
+ expect(body.quotaStates).toHaveLength(0);
+ });
+});
diff --git a/server/src/__tests__/services/health-quota-poll.test.ts b/server/src/__tests__/services/health-quota-poll.test.ts
new file mode 100644
index 00000000..054dbb25
--- /dev/null
+++ b/server/src/__tests__/services/health-quota-poll.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+import { encrypt } from '../../lib/crypto.js';
+import { getDb, initDb } from '../../db/index.js';
+
+// #1403: the health pass piggybacks provider-reported quota polling on a
+// healthy verdict, throttled per key, and a quota failure must never bend the
+// health verdict itself.
+const fetchQuota = vi.hoisted(() => vi.fn());
+const validateKey = vi.hoisted(() => vi.fn());
+
+vi.mock('../../providers/index.js', () => ({
+ resolveProvider: () => ({
+ name: 'OpenRouter',
+ validateKey,
+ // Stands in for the OpenAICompatProvider override (hasQuotaProbe true, so
+ // supportsQuotaPolling passes it).
+ hasQuotaProbe: true,
+ fetchQuota,
+ }),
+}));
+
+const { checkKeyHealth, maybePollKeyQuota, QUOTA_POLL_INTERVAL_MS } = await import('../../services/health.js');
+
+beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+});
+
+let nextId = 9100;
+function seedKey(): number {
+ const id = ++nextId;
+ const key = encrypt('sk-or-health-test');
+ getDb().prepare(`
+ INSERT INTO api_keys (id, platform, label, encrypted_key, iv, auth_tag, enabled, status)
+ VALUES (?, 'openrouter', 'quota-poll-test', ?, ?, ?, 1, 'unknown')
+ `).run(id, key.encrypted, key.iv, key.authTag);
+ return id;
+}
+
+function seedQuotaApiObservation(keyId: number, ageMs: number): void {
+ const seen = new Date(Date.now() - ageMs).toISOString().replace('T', ' ').replace('Z', '');
+ getDb().prepare(`
+ INSERT INTO provider_quota_observations
+ (id, platform, key_id, quota_pool_key, metric, source, created_at, observed_at)
+ VALUES (?, 'openrouter', ?, 'openrouter::account', 'credits', 'quota_api', ?, ?)
+ `).run(`qpo-${keyId}-${ageMs}`, keyId, seen, seen);
+}
+
+beforeEach(() => {
+ fetchQuota.mockReset();
+ validateKey.mockReset();
+ vi.useRealTimers();
+});
+
+describe('health-pass quota polling (#1403)', () => {
+ it('polls quota after a healthy check and records nothing on failure without changing the verdict', async () => {
+ const keyId = seedKey();
+ validateKey.mockResolvedValue(true);
+ fetchQuota.mockResolvedValue(false); // quota endpoint down
+
+ const status = await checkKeyHealth(keyId);
+ expect(status).toBe('healthy');
+ // Give the fire-and-forget poll a tick to run.
+ await new Promise(r => setImmediate(r));
+ expect(fetchQuota).toHaveBeenCalledTimes(1);
+ const row = getDb().prepare('SELECT status FROM api_keys WHERE id = ?').get(keyId) as { status: string };
+ expect(row.status).toBe('healthy');
+ });
+
+ it('fetchQuota throwing does not demote the key', async () => {
+ const keyId = seedKey();
+ validateKey.mockResolvedValue(true);
+ fetchQuota.mockRejectedValue(new Error('socket hang up'));
+ const status = await checkKeyHealth(keyId);
+ expect(status).toBe('healthy');
+ await new Promise(r => setImmediate(r));
+ const row = getDb().prepare('SELECT status FROM api_keys WHERE id = ?').get(keyId) as { status: string };
+ expect(row.status).toBe('healthy');
+ });
+
+ it('does not poll after an invalid verdict', async () => {
+ const keyId = seedKey();
+ validateKey.mockResolvedValue({ valid: false, error: 'bad key' });
+ const status = await checkKeyHealth(keyId);
+ expect(status).toBe('invalid');
+ await new Promise(r => setImmediate(r));
+ expect(fetchQuota).not.toHaveBeenCalled();
+ });
+
+ it('maybePollKeyQuota throttles to one poll per interval per key', async () => {
+ const keyId = seedKey();
+ fetchQuota.mockResolvedValue(true);
+
+ // Fresh observation: too soon, must skip.
+ seedQuotaApiObservation(keyId, 60_000);
+ expect(await maybePollKeyQuota(keyId)).toBe(false);
+ expect(fetchQuota).not.toHaveBeenCalled();
+
+ // Only an old observation remains: poll runs.
+ getDb().prepare("DELETE FROM provider_quota_observations WHERE key_id = ? AND created_at > datetime('now', '-1 hour')").run(keyId);
+ seedQuotaApiObservation(keyId, QUOTA_POLL_INTERVAL_MS + 60_000);
+ expect(await maybePollKeyQuota(keyId)).toBe(true);
+ expect(fetchQuota).toHaveBeenCalledTimes(1);
+ });
+
+ it('maybePollKeyQuota polls immediately when the key has no quota_api history', async () => {
+ const keyId = seedKey();
+ fetchQuota.mockResolvedValue(true);
+ expect(await maybePollKeyQuota(keyId)).toBe(true);
+ expect(fetchQuota).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/server/src/providers/base.ts b/server/src/providers/base.ts
index 6ea89f04..d4efd92d 100644
--- a/server/src/providers/base.ts
+++ b/server/src/providers/base.ts
@@ -246,6 +246,28 @@ export abstract class BaseProvider {
abstract validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult>;
+ /**
+ * Optional quota/balance probe (#1403). Providers whose API exposes a
+ * key-info/quota endpoint override this to fetch the provider-reported
+ * limit/remaining and persist them as a `source: 'quota_api'` observation,
+ * so the dashboard shows a real balance instead of a text-label guess.
+ * Must never throw into the caller: the default implementation does no
+ * network at all and returns false; implementations catch transport errors
+ * and return false so a quota probe can never change a health verdict.
+ * Returns true when an observation was recorded.
+ */
+ async fetchQuota(_apiKey: string, _quotaContext?: QuotaObservationContext): Promise<boolean> {
+ return false;
+ }
+
+ /** Whether this provider actually has a quota endpoint to probe (#1403).
+ * fetchQuota alone can't answer it: OpenAICompatProvider overrides the
+ * method for every instance, spec or not. Routes that owe the operator a
+ * "this platform has no quota endpoint" answer must use this instead. */
+ get hasQuotaProbe(): boolean {
+ return false;
+ }
+
/**
* Turn a conventional 401/403 validation response into a diagnostic result.
* Providers still return a simple boolean when no useful error body exists,
diff --git a/server/src/providers/index.ts b/server/src/providers/index.ts
index 06a9a0ee..c2d60d33 100644
--- a/server/src/providers/index.ts
+++ b/server/src/providers/index.ts
@@ -166,6 +166,17 @@ register(new OpenAICompatProvider({
'HTTP-Referer': 'http://localhost:3001',
'X-Title': 'FreeLLMAPI',
},
+ // #1403: OpenRouter reports the key's real credit balance and hard limit on
+ // its key-info endpoint (outside /api/v1). limit/remaining are USD amounts
+ // when set; null means the key is on the free tier with no credit cap, so
+ // the probe records whatever pair the endpoint actually fills.
+ quotaProbe: {
+ url: 'https://openrouter.ai/api/v1/key',
+ metric: 'credits',
+ limitFields: ['limit'],
+ remainingFields: ['limit_remaining'],
+ notes: 'openrouter key-info: USD credit (limit/limit_remaining)',
+ },
}));
// GitHub Models — OpenAI-compatible. Catalog uses `<publisher>/<model>` ids
@@ -345,6 +356,18 @@ register(new OpenAICompatProvider({
platform: 'siliconflow',
name: 'SiliconFlow',
baseUrl: 'https://api.siliconflow.com/v1',
+ // #1403: SiliconFlow reports the account's credit balance on
+ // GET /v1/user/info (data.balance = gift credit, data.totalBalance = gift +
+ // charge; values arrive as numeric strings in CNY). There is no limit field,
+ // so the probe records remaining only — a real number beats parseBudget's 0
+ // for this pool.
+ quotaProbe: {
+ url: 'https://api.siliconflow.com/v1/user/info',
+ metric: 'credits',
+ limitFields: [],
+ remainingFields: ['totalBalance', 'balance'],
+ notes: 'siliconflow user-info: CNY credit balance (totalBalance)',
+ },
}));
// Routeway — OpenAI-compatible aggregator (api.routeway.ai/v1). Free models
diff --git a/server/src/providers/openai-compat.ts b/server/src/providers/openai-compat.ts
index 53640ccc..0088aa40 100644
--- a/server/src/providers/openai-compat.ts
+++ b/server/src/providers/openai-compat.ts
@@ -11,7 +11,8 @@ import { rescueInlineToolCalls } from '../lib/tool-call-rescue.js';
import { extractThinkFromMessage } from '../lib/think-tags.js';
import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';
import { invalidToolCallReasons, isToolArgumentValidationEnabled } from '../lib/tool-validate.js';
-import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
+import { recordQuotaObservation, recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
+import type { QuotaMetric } from '@freellmapi/shared/types.js';
import { providerTimeoutMs } from '../lib/provider-timeout.js';
import { isAbortLikeError } from '../lib/error-classify.js';
import { contentToString } from '../lib/content.js';
@@ -69,6 +70,19 @@ export function inBandCreditsError(text: string | null | undefined): string | nu
* Covers: Groq, Cerebras, NVIDIA NIM, Mistral, OpenRouter,
* GitHub Models, Fireworks AI.
*/
+/** A provider's key-info/quota endpoint (#1403): the GET URL and the JSON
+ * field names carrying the limit and the remaining balance. Fields are looked
+ * up first under a `data` wrapper (OpenRouter style), then at the top level.
+ * `credits` are in the provider's own currency (OpenRouter USD, SiliconFlow
+ * CNY); `notes` names it. Only a reading with a limit feeds routing headroom. */
+export interface QuotaProbeSpec {
+ url: string;
+ metric: QuotaMetric;
+ limitFields: string[];
+ remainingFields: string[];
+ notes?: string;
+}
+
export class OpenAICompatProvider extends BaseProvider {
readonly platform: Platform;
readonly name: string;
@@ -86,6 +100,8 @@ export class OpenAICompatProvider extends BaseProvider {
/** True only for a custom endpoint whose host is Moonshot's own API; see
* isMoonshotEndpoint(). Gates the assistant `partial` prefill flag (#1038). */
private readonly forwardsPartial: boolean;
+ /** Optional provider-reported quota endpoint (#1403). */
+ private readonly quotaProbe?: QuotaProbeSpec;
constructor(opts: {
platform: Platform;
@@ -96,6 +112,7 @@ export class OpenAICompatProvider extends BaseProvider {
timeoutMs?: number;
keyless?: boolean;
forceSingleToolCall?: boolean;
+ quotaProbe?: QuotaProbeSpec;
}) {
super();
this.platform = opts.platform;
@@ -108,6 +125,7 @@ export class OpenAICompatProvider extends BaseProvider {
this.keyless = opts.keyless ?? false;
this.forceSingleToolCall = opts.forceSingleToolCall ?? false;
this.forwardsPartial = opts.platform === 'custom' && isMoonshotEndpoint(opts.baseUrl);
+ this.quotaProbe = opts.quotaProbe;
}
/** Resolve the parallel_tool_calls flag to send upstream. For providers that
@@ -553,6 +571,75 @@ export class OpenAICompatProvider extends BaseProvider {
const res = await this.fetchCatalogEndpoint(this.validateUrl ?? this.modelsUrl, apiKey, quotaContext);
return this.validationResult(res);
}
+
+ /**
+ * Provider-reported balance via the registered quotaProbe endpoint (#1403).
+ * GETs the key-info URL (e.g. OpenRouter's `GET /api/v1/key`), pulls the
+ * limit/remaining numbers out of the JSON (checking the `data` wrapper and
+ * the top level), and records them as a `source: 'quota_api'` observation.
+ * Never throws: a quota probe that fails says nothing about the key, and
+ * the caller's health verdict must stay about the key.
+ */
+ get hasQuotaProbe(): boolean {
+ return this.quotaProbe !== undefined;
+ }
+
+ async fetchQuota(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {
+ const spec = this.quotaProbe;
+ if (!spec) return false;
+ try {
+ const res = await this.fetchWithTimeout(spec.url, {
+ method: 'GET',
+ headers: {
+ ...this.authHeader(apiKey),
+ ...this.extraHeaders,
+ },
+ }, 10_000, { timeoutBounds: 'request' });
+ if (!res.ok) return false;
+ const body: any = await res.json().catch(() => null);
+ const scope = (body && typeof body === 'object' && body.data && typeof body.data === 'object')
+ ? [body.data, body]
+ : [body];
+ const pick = (fields: string[]): number | null => {
+ for (const obj of scope) {
+ if (!obj || typeof obj !== 'object') continue;
+ for (const f of fields) {
+ const v = (obj as Record<string, unknown>)[f];
+ if (typeof v === 'number' && Number.isFinite(v)) return v;
+ // Some providers serialize balances as strings ("88.88", SiliconFlow
+ // /v1/user/info). Accept a numeric string; "", null and prose never
+ // parse to a finite number.
+ if (typeof v === 'string' && v.trim() !== '') {
+ const n = Number(v);
+ if (Number.isFinite(n)) return n;
+ }
+ }
+ }
+ return null;
+ };
+ const limit = pick(spec.limitFields);
+ const remaining = pick(spec.remainingFields);
+ if (limit === null && remaining === null) return false;
+ const record = recordQuotaObservation({
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'quota_api',
+ metric: spec.metric,
+ limit,
+ remaining,
+ resetStrategy: 'provider_reported',
+ source: 'quota_api',
+ statusCode: res.status,
+ notes: spec.notes ?? null,
+ });
+ return record !== null;
+ } catch {
+ // Transport/parse failure: inconclusive, never a key verdict (#1403).
+ return false;
+ }
+ }
}
/**
diff --git a/server/src/routes/health.ts b/server/src/routes/health.ts
index 1791fa25..0daea61e 100644
--- a/server/src/routes/health.ts
+++ b/server/src/routes/health.ts
@@ -1,10 +1,11 @@
import { Router } from 'express';
import type { Request, Response } from 'express';
import { getDb } from '../db/index.js';
-import { checkKeyHealth, checkAllKeys } from '../services/health.js';
+import { checkKeyHealth, checkAllKeys, pollKeyQuota, supportsQuotaPolling } from '../services/health.js';
import { getDegradationStatus } from '../services/degradation.js';
-import { hasProvider } from '../providers/index.js';
+import { hasProvider, resolveProvider } from '../providers/index.js';
import { getQuotaStateForKeys } from '../services/provider-quota.js';
+import type { Platform } from '@freellmapi/shared/types.js';
export const healthRouter = Router();
@@ -78,3 +79,35 @@ healthRouter.post('/check-all', async (_req: Request, res: Response) => {
await checkAllKeys({ force: true });
res.json({ success: true });
});
+
+// Poll one key's provider-reported balance now (#1403). The health pass only
+// piggybacks the quota probe at most once per 15 minutes; this is the manual
+// override — an operator adding a key wants the balance immediately instead
+// of waiting for the next healthy pass after the throttle. Returns what the
+// probe recorded (or the fresh state when the provider reported nothing, so
+// the caller can tell "no quota endpoint / probe failed" from "fresh number").
+healthRouter.post('/quota/:keyId', async (req: Request, res: Response) => {
+ const keyId = parseInt(req.params.keyId as string, 10);
+ if (isNaN(keyId)) {
+ res.status(400).json({ error: { message: 'Invalid key ID' } });
+ return;
+ }
+ const db = getDb();
+ const row = db.prepare('SELECT * FROM api_keys WHERE id = ?').get(keyId) as any;
+ if (!row) {
+ res.status(404).json({ error: { message: 'Key not found' } });
+ return;
+ }
+ const provider = resolveProvider(row.platform as Platform, row.base_url);
+ if (!provider || !supportsQuotaPolling(provider)) {
+ res.status(400).json({ error: { message: `${row.platform} has no provider-reported quota endpoint` } });
+ return;
+ }
+ // pollKeyQuota is failure-silent by design; its boolean tells us whether a
+ // quota_api row was written, and the state query returns the fresh reading.
+ const recorded = await pollKeyQuota(keyId, row, provider);
+ const state = getQuotaStateForKeys().filter(
+ q => q.keyId === keyId && q.source === 'quota_api',
+ );
+ res.json({ keyId, recorded, quotaStates: state });
+});
diff --git a/server/src/services/health.ts b/server/src/services/health.ts
index f0346205..f65f6560 100644
--- a/server/src/services/health.ts
+++ b/server/src/services/health.ts
@@ -1,5 +1,6 @@
import { getDb } from '../db/index.js';
import { resolveProvider } from '../providers/index.js';
+import { BaseProvider } from '../providers/base.js';
import { decrypt } from '../lib/crypto.js';
import { decryptProxyUrl } from '../lib/key-proxy.js';
import { withKeyProxy } from '../lib/proxy.js';
@@ -81,6 +82,76 @@ function recordInvalidFailure(keyId: number, platform?: string): void {
}
}
+/**
+ * Provider-reported quota polling (#1403 phase 1). Providers with a key-info
+ * endpoint (see BaseProvider.fetchQuota) get polled right after a health pass
+ * confirms the key works, so the dashboard shows the provider's own balance
+ * instead of a regex guess over catalog text. Throttled per key: a poll is
+ * only worth taking when the last quota_api observation is older than
+ * QUOTA_POLL_INTERVAL_MS (or none exists). Fire-and-forget and failure-silent:
+ * a quota probe says nothing about key validity and must never bend a health
+ * verdict or the pass budget.
+ */
+export const QUOTA_POLL_INTERVAL_MS = 15 * 60 * 1000;
+
+function quotaPollDue(keyId: number, now = Date.now()): boolean {
+ const row = getDb().prepare(`
+ SELECT created_at AS seenAt FROM provider_quota_observations
+ WHERE key_id = ? AND source = 'quota_api'
+ ORDER BY created_at DESC LIMIT 1
+ `).get(keyId) as { seenAt: string | null } | undefined;
+ if (!row?.seenAt) return true;
+ const seen = Date.parse(row.seenAt.includes('T') ? row.seenAt : row.seenAt.replace(' ', 'T') + 'Z');
+ if (!Number.isFinite(seen)) return true;
+ return now - seen >= QUOTA_POLL_INTERVAL_MS;
+}
+
+export async function pollKeyQuota(
+ keyId: number,
+ // The api_keys row as stored (encrypted key columns + the proxy columns
+ // decryptProxyUrl reads). `any` mirrors how checkKeyHealth carries it.
+ row: any,
+ provider: BaseProvider,
+): Promise<boolean> {
+ try {
+ const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
+ return await withKeyProxy(decryptProxyUrl(row), () => provider.fetchQuota(apiKey, {
+ platform: row.platform as Platform,
+ keyId,
+ quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),
+ endpoint: 'quota_api',
+ origin: 'health',
+ }));
+ } catch {
+ // Inconclusive by construction: never throws into the health pass.
+ return false;
+ }
+}
+
+/** True when this provider actually has a quota endpoint to probe (#1403).
+ * Uses the provider's own hasQuotaProbe getter: OpenAICompatProvider
+ * overrides fetchQuota for every instance, spec or not, so a method-identity
+ * check would claim quota support for specless platforms. */
+export function supportsQuotaPolling(provider: BaseProvider): boolean {
+ return provider.hasQuotaProbe;
+}
+
+/** Throttled, self-contained quota poll for one key — the entry point other
+ * services (or a future scheduler) can use without duplicating the gate. */
+export async function maybePollKeyQuota(keyId: number): Promise<boolean> {
+ try {
+ const db = getDb();
+ const row = db.prepare('SELECT * FROM api_keys WHERE id = ? AND enabled = 1').get(keyId) as any;
+ if (!row) return false;
+ const provider = resolveProvider(row.platform as Platform, row.base_url);
+ if (!provider || !supportsQuotaPolling(provider)) return false;
+ if (!quotaPollDue(keyId)) return false;
+ return await pollKeyQuota(keyId, row, provider);
+ } catch {
+ return false;
+ }
+}
+
export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {
const db = getDb();
const row = db.prepare('SELECT * FROM api_keys WHERE id = ?').get(keyId) as any;
@@ -122,6 +193,12 @@ export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {
// serves nothing until its models are discovered. Fire-and-forget; the
// trigger is a no-op for every other platform, and throttled.
triggerBuiltinModelDiscovery(db, row.platform, 'healthy');
+ // #1403: piggyback provider-reported quota polling on the healthy
+ // verdict — but only for providers with a quota endpoint, and at most
+ // once per QUOTA_POLL_INTERVAL_MS per key. Fire-and-forget, silent.
+ if (supportsQuotaPolling(provider) && quotaPollDue(keyId)) {
+ void pollKeyQuota(keyId, row, provider).catch(() => {});
+ }
} else {
providerLog(
'warn',