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(providers): add catalog-managed LLMTR integration (#1366)

Tashfeen076315a855ed
diff --git a/client/src/components/keys/shared.tsx b/client/src/components/keys/shared.tsx
index c9d737e3..ac1ee5c6 100644
--- a/client/src/components/keys/shared.tsx
+++ b/client/src/components/keys/shared.tsx
@@ -29,6 +29,7 @@ export function GetKeyLink({ url }: { url: string }) {
export const PLATFORMS: { value: Platform; label: string; url: string; keyless?: boolean }[] = [
{ value: 'aclide', label: 'ACLIDE (shared monthly credits)', url: 'https://aclide.com/en/dashboard/api-keys' },
{ value: 'speka', label: 'Speka ($1 shared monthly credits)', url: 'https://speka.me/dashboard/keys' },
+ { value: 'llmtr', label: 'LLMTR (daily free-model quotas)', url: 'https://llmtr.com' },
{ value: 'moondream', label: 'Moondream ($5 shared monthly credits)', url: 'https://moondream.ai/c/cloud/api-keys' },
{ value: 'google', label: 'Google AI Studio', url: 'https://aistudio.google.com/apikey' },
{ value: 'groq', label: 'Groq', url: 'https://console.groq.com/keys' },
diff --git a/client/src/lib/routing.ts b/client/src/lib/routing.ts
index a9622536..38cc0ae4 100644
--- a/client/src/lib/routing.ts
+++ b/client/src/lib/routing.ts
@@ -405,6 +405,7 @@ export const platformColors: Record<string, string> = {
sail: '#0ea5e9',
aclide: '#6366f1',
speka: '#0d9488',
+ llmtr: '#0f766e',
moondream: '#6d5dfc',
electronhub: '#6366f1',
experiential: '#14b8a6',
diff --git a/docs/providers/llmtr.md b/docs/providers/llmtr.md
new file mode 100644
index 00000000..3341ab97
--- /dev/null
+++ b/docs/providers/llmtr.md
@@ -0,0 +1,46 @@
+# LLMTR
+
+LLMTR exposes an OpenAI-compatible API at `https://llmtr.com/v1`. Create an account,
+verify email, and create a dashboard API key. Add it under **Keys → LLMTR**, or
+import `LLMTR_API_KEY` from an environment file. Never commit the key.
+
+Selected routes are zero-priced with daily or rolling quotas, not monthly cash
+credits. The [migration guide](https://llmtr.com/docs/en/migration/openai-openrouter/)
+documents free requests at zero balance. Account caps can vary; this integration
+does not invent numeric quotas or make the whole provider roster free.
+New accounts have a reduced free allowance that increases automatically once
+the account is 24 hours old. A quota response observed during testing confirmed
+this waiting option; no top-up is required. A streaming smoke test reached that
+quota, so only non-streaming inference was live-verified in this publication.
+
+## Catalog and release timing
+
+Model rows are supplied only by the hosted signed catalog. There are no bundled
+seeds or automatic discovery of LLMTR's paid models. Existing Premium-immediate
+and Free-after-30-days release logic is unchanged.
+Older app versions need an update to recognize the new provider.
+
+Five routes returned matching model IDs and valid text completions on 2026-09-29:
+
+- `qwen/qwen3.8-27b-free`
+- `nvidia/nemotron-3-ultra-550b-a55b`
+- `nvidia/nemotron-3-super-120b-a12b`
+- `motif/motif-3`
+- `inclusionai/ling-3.0-flash-fin`
+
+These checks are not independent proof of the underlying model weights. Tools,
+vision and context limits require separate verification before catalog flags are
+enabled. Motif's [quota](https://llmtr.com/docs/en/gateway/motif-3/) replenishes each
+request after 24 hours. Expiring promotions and EVREN BYOK routes are excluded.
+
+## Authentication and errors
+
+The public `/v1/models` endpoint cannot validate a key. Dashboard `/api/usage`
+rejected API-key authentication during testing. Instead, key validation submits
+a deliberately nonexistent model without generating tokens. Live valid/invalid
+controls returned `404/model_not_found` and `401/auth_error`, respectively.
+Other errors remain inconclusive; quota exhaustion does not mark a key invalid.
+
+Chat and streaming use the shared OpenAI-compatible transport, preserve usage and
+backoff, and reject mismatched response model IDs rather than silently accepting
+substitutions. No automatic paid fallback is introduced by this adapter.
diff --git a/server/src/__tests__/providers/llmtr.test.ts b/server/src/__tests__/providers/llmtr.test.ts
new file mode 100644
index 00000000..8657649f
--- /dev/null
+++ b/server/src/__tests__/providers/llmtr.test.ts
@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ChatCompletionChunk } from '@freellmapi/shared/types.js';
+import { LlmtrProvider } from '../../providers/llmtr.js';
+import { getProvider } from '../../providers/index.js';
+import { AUTH_JSON_PROVIDER_MAP, detectPlatform, parseKeysFromFile } from '../../lib/key-parser.js';
+import { BUILTIN_DISCOVERY_PLATFORMS } from '../../services/builtin-model-discovery.js';
+
+const model = 'qwen/qwen3.8-27b-free';
+const completion = { id: 'llmtr-test', object: 'chat.completion', created: 1, model,
+ choices: [{ index: 0, message: { role: 'assistant', content: 'OK' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 4, completion_tokens: 2, total_tokens: 6 } };
+const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers });
+const sse = (returnedModel: string) => new Response([
+ { id: 's', object: 'chat.completion.chunk', created: 1, model: returnedModel, choices: [{ index: 0, delta: { content: 'OK' }, finish_reason: 'stop' }] },
+ { id: 's', object: 'chat.completion.chunk', created: 1, model: returnedModel, choices: [], usage: completion.usage },
+].map(c => `data: ${JSON.stringify(c)}\n\n`).join('') + 'data: [DONE]\n\n', { headers: { 'Content-Type': 'text/event-stream' } });
+
+describe('LLMTR provider', () => {
+ afterEach(() => vi.restoreAllMocks());
+
+ it('registers, imports keys and leaves model discovery to the signed catalog', () => {
+ expect(getProvider('llmtr')).toBeInstanceOf(LlmtrProvider);
+ expect(detectPlatform('LLMTR_')).toBe('llmtr');
+ expect(AUTH_JSON_PROVIDER_MAP.llmtr).toBe('llmtr');
+ expect(parseKeysFromFile('LLMTR_API_KEY=llmtr-test-not-a-real-key', 'keys.env').keys[0].platform).toBe('llmtr');
+ expect(BUILTIN_DISCOVERY_PLATFORMS).not.toContain('llmtr');
+ });
+
+ it('preserves auth, exact model, options, usage and routing attribution', async () => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json(completion));
+ const response = await getProvider('llmtr')!.chatCompletion('test-key', [{ role: 'user', content: 'OK' }], model,
+ { max_tokens: 128, temperature: 0.2, response_format: { type: 'json_object' } });
+ expect(fetch.mock.calls[0][0]).toBe('https://llmtr.com/v1/chat/completions');
+ expect(new Headers(fetch.mock.calls[0][1]?.headers).get('authorization')).toBe('Bearer test-key');
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toMatchObject({ model, max_tokens: 128, temperature: 0.2, response_format: { type: 'json_object' } });
+ expect(response.choices[0].message.content).toBe('OK');
+ expect(response.usage).toEqual(completion.usage);
+ expect(response._routed_via).toEqual({ platform: 'llmtr', model });
+ });
+
+ it('streams content and usage with the requested model', async () => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(sse(model));
+ const chunks: ChatCompletionChunk[] = [];
+ for await (const chunk of getProvider('llmtr')!.streamChatCompletion('test-key', [], model)) chunks.push(chunk);
+ expect(chunks.flatMap(c => c.choices).map(c => c.delta.content ?? '').join('')).toBe('OK');
+ expect(chunks.some(c => c.usage?.total_tokens === 6)).toBe(true);
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body)).stream).toBe(true);
+ });
+
+ it.each(['other-model', undefined])('rejects mismatched or missing completion model (%s)', async returnedModel => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ ...completion, model: returnedModel }));
+ await expect(getProvider('llmtr')!.chatCompletion('test-key', [], model)).rejects.toMatchObject({ status: 502 });
+ });
+
+ it('rejects a substituted stream before yielding its content', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(sse('other-model'));
+ const stream = getProvider('llmtr')!.streamChatCompletion('test-key', [], model);
+ await expect(stream.next()).rejects.toMatchObject({ status: 502 });
+ });
+
+ it('validates via authenticated model resolution, not the public roster', async () => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'model_not_found', message: 'Model not found' } }, 404));
+ await expect(getProvider('llmtr')!.validateKey('test-key')).resolves.toBe(true);
+ expect(fetch).toHaveBeenCalledTimes(1);
+ expect(fetch.mock.calls[0][0]).toBe('https://llmtr.com/v1/chat/completions');
+ expect(JSON.parse(String(fetch.mock.calls[0][1]?.body))).toMatchObject({ model: '__freellmapi_key_validation__', max_tokens: 1, stream: false });
+ });
+
+ it.each([401, 403])('rejects invalid credentials (%s)', async status => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'auth_error', message: 'Invalid API key' } }, status));
+ await expect(getProvider('llmtr')!.validateKey('bad-key')).resolves.toMatchObject({ valid: false });
+ });
+
+ it.each([200, 400, 402, 404, 429, 500])('keeps inconclusive validation errors inconclusive (%s)', async status => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { type: 'other' } }, status, { 'Retry-After': '17' }));
+ await expect(getProvider('llmtr')!.validateKey('test-key')).rejects.toMatchObject({ status, retryAfterMs: 17_000 });
+ });
+
+ it('does not accept an HTML 404', async () => {
+ vi.spyOn(global, 'fetch').mockResolvedValue(new Response('not JSON', { status: 404 }));
+ await expect(getProvider('llmtr')!.validateKey('test-key')).rejects.toMatchObject({ status: 404 });
+ });
+
+ it.each([402, 429])('preserves upstream quota status and backoff without retry (%s)', async status => {
+ const fetch = vi.spyOn(global, 'fetch').mockResolvedValue(json({ error: { message: 'Quota exhausted' } }, status, { 'Retry-After': '30' }));
+ await expect(getProvider('llmtr')!.chatCompletion('test-key', [], model)).rejects.toMatchObject({ status, retryAfterMs: 30_000 });
+ expect(fetch).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/server/src/__tests__/routes/keys-providers-checklist.test.ts b/server/src/__tests__/routes/keys-providers-checklist.test.ts
index 48b68979..77673d3c 100644
--- a/server/src/__tests__/routes/keys-providers-checklist.test.ts
+++ b/server/src/__tests__/routes/keys-providers-checklist.test.ts
@@ -55,6 +55,8 @@ describe('GET /api/keys/providers — provider checklist (#543)', () => {
expect(typeof groq.keyless).toBe('boolean');
expect(body.providers.find((p: { platform: string }) => p.platform === 'moondream'))
.toMatchObject({ platform: 'moondream', name: 'Moondream', configured: false, keyless: false });
+ expect(body.providers.find((p: { platform: string }) => p.platform === 'llmtr'))
+ .toMatchObject({ platform: 'llmtr', name: 'LLMTR', configured: false, keyless: false });
expect(body.summary).toEqual({
total: body.providers.length,
configured: 0,
diff --git a/server/src/lib/key-parser.ts b/server/src/lib/key-parser.ts
index 7eee2536..15e02c76 100644
--- a/server/src/lib/key-parser.ts
+++ b/server/src/lib/key-parser.ts
@@ -46,6 +46,7 @@ export interface ParseResult {
export const PREFIX_MAP: Record<string, string> = {
ACLIDE_: 'aclide',
SPEKA_: 'speka',
+ LLMTR_: 'llmtr',
MOONDREAM_: 'moondream',
GOOGLE_: 'google',
GEMINI_: 'google',
@@ -142,6 +143,7 @@ export const AUTH_JSON_PROVIDER_MAP: Record<string, string> = {
sail: 'sail',
aclide: 'aclide',
speka: 'speka',
+ llmtr: 'llmtr',
moondream: 'moondream',
'sail-research': 'sail',
sailresearch: 'sail',
diff --git a/server/src/providers/index.ts b/server/src/providers/index.ts
index 354145a7..4e055b3b 100644
--- a/server/src/providers/index.ts
+++ b/server/src/providers/index.ts
@@ -11,6 +11,7 @@ import { ZhipuProvider } from './zhipu.js';
import { SailProvider } from './sail.js';
import { AclideProvider } from './aclide.js';
import { SpekaProvider } from './speka.js';
+import { LlmtrProvider } from './llmtr.js';
import { MoondreamProvider } from './moondream.js';
import { ElectronHubProvider } from './electronhub.js';
import { ExperientialProvider } from './experiential.js';
@@ -59,6 +60,7 @@ register(new OpenAICompatProvider({
register(new SailProvider());
register(new AclideProvider());
register(new SpekaProvider());
+register(new LlmtrProvider());
register(new MoondreamProvider());
// Free-plan grants are shared wallets, not free credits per model. Eligibility
diff --git a/server/src/providers/llmtr.ts b/server/src/providers/llmtr.ts
new file mode 100644
index 00000000..5f975de5
--- /dev/null
+++ b/server/src/providers/llmtr.ts
@@ -0,0 +1,57 @@
+import type { ChatCompletionChunk, ChatCompletionResponse, ChatMessage } from '@freellmapi/shared/types.js';
+import { providerHttpError, type CompletionOptions, type KeyValidationResult } from './base.js';
+import { OpenAICompatProvider } from './openai-compat.js';
+import { providerTimeoutMs } from '../lib/provider-timeout.js';
+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
+
+export const LLMTR_BASE_URL = 'https://llmtr.com/v1';
+const VALIDATION_MODEL = '__freellmapi_key_validation__';
+
+function checkModel(requested: string, returned: string): void {
+ if (returned !== requested) {
+ throw Object.assign(new Error('LLMTR returned a different or missing model identity'), { status: 502 });
+ }
+}
+
+/** Selected zero-priced routes have renewable daily/rolling quotas, not a
+ * monthly cash grant. Only the signed catalog supplies model rows: the public
+ * roster also contains paid models, expiring promotions and BYOK-only rows. */
+export class LlmtrProvider extends OpenAICompatProvider {
+ constructor() {
+ super({ platform: 'llmtr', name: 'LLMTR', baseUrl: LLMTR_BASE_URL });
+ }
+
+ override async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult> {
+ // /models is public; /api/usage expects a dashboard token. This nonexistent
+ // model checks authentication without generating tokens: live controls on
+ // 2026-09-29 returned 401/auth_error for an invalid key and
+ // 404/model_not_found for the valid key. Do not accept generic 404s.
+ const res = await this.fetchWithTimeout(`${LLMTR_BASE_URL}/chat/completions`, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+ body: JSON.stringify({ model: VALIDATION_MODEL, messages: [{ role: 'user', content: 'key validation' }], max_tokens: 1, stream: false }),
+ }, providerTimeoutMs(this.platform, 30_000), { timeoutBounds: 'request' });
+ recordQuotaObservationsFromResponse(res, { ...quotaContext, platform: this.platform, endpoint: 'key-validation' });
+ if ([401, 403].includes(res.status)) return this.validationResult(res);
+ if (res.status === 404) {
+ const body = await res.clone().json().catch(() => null) as { error?: { type?: string } } | null;
+ if (body?.error?.type === 'model_not_found') return true;
+ }
+ throw providerHttpError(res, 'LLMTR key validation is temporarily inconclusive');
+ }
+
+ override async chatCompletion(apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext): Promise<ChatCompletionResponse> {
+ const response = await super.chatCompletion(apiKey, messages, modelId, options, quotaContext);
+ checkModel(modelId, response.model);
+ return response;
+ }
+
+ override async *streamChatCompletion(apiKey: string, messages: ChatMessage[], modelId: string,
+ options?: CompletionOptions, quotaContext?: QuotaObservationContext): AsyncGenerator<ChatCompletionChunk> {
+ for await (const chunk of super.streamChatCompletion(apiKey, messages, modelId, options, quotaContext)) {
+ checkModel(modelId, chunk.model);
+ yield chunk;
+ }
+ }
+}
diff --git a/server/src/routes/keys.ts b/server/src/routes/keys.ts
index 47af0573..b0bacbd9 100644
--- a/server/src/routes/keys.ts
+++ b/server/src/routes/keys.ts
@@ -44,6 +44,7 @@ export const keysRouter = Router();
const PLATFORMS = [
'aclide',
'speka',
+ 'llmtr',
'moondream',
'google', 'groq', 'cerebras', 'sail', 'electronhub', 'experiential', 'router9', 'septor', 'clod', 'speechify', 'blaze', 'lucidity', 'airforce', 'dreamprompting', 'waterfall', 'logfare', 'bai', 'radeon', 'nvidia', 'mistral',
'openrouter', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama',
diff --git a/shared/types.ts b/shared/types.ts
index cebb5b3d..44045391 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -72,6 +72,9 @@ export type Platform =
| 'aclide'
// OpenAI-compatible chat and embeddings; one shared $1 monthly allowance.
| 'speka'
+ // Selected zero-priced routes have daily/rolling quotas without a top-up;
+ // signed catalog only. The public roster also includes paid/promotional IDs.
+ | 'llmtr'
// Hosted vision API: $5/workspace in recurring monthly credits, shared
// across models. Signed catalog only; no bundled model seeds.
| 'moondream'