Put a Free 30M Token Quota Behind a Ledger, Not a Shared Key

A 30M token allowance looks generous on paper and disappears in a week when three teammates point the same key at the same retry loop. The first failure is not model quality; it is the absence of per-request attribution and a quota guard in the application path. This article builds a small provider seam, records every completion in SQLite, and rejects over-budget jobs before they spend shared quota.

MonkeyCode is described by the operator as an open-source project with free model access and a free server option. Those are availability claims, not a production guarantee. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Verify current quotas and server limits before you depend on them; the workflow works with any compatible route.

Identify the layer that fails first

The first breakage is not the model. It is the handoff between an ad-hoc teammate script and a shared API key. A free quota usually dies from one of four failure modes:

Failure mode	First visible signal	Cheap guard
Quota drained by one ad-hoc job	429 for every caller	per-job token budget
Retry loop multiplies spend	usage rises while success count stays flat	idempotent job id plus ledger
No cost per task	someone asks why the key is empty	token ledger
Provider outage hidden	fallback silently dropped	fallback route returns an explicit status

The guard should sit at the seam, not in the prompt. If you add instructions to 'spend less', you are only changing output, not protecting the budget.

Wrap the route instead of calling the SDK directly

Create a narrow interface and wrap it with a ledger. The inner route can be MonkeyCode's free model access or any OpenAI-compatible endpoint; the wrapper stays identical.

import sqlite3
from dataclasses import dataclass
from typing import Protocol

@dataclass
class RouteResult:
    ok: bool
    tokens: int
    latency_ms: int
    status: int
    provider: str

class ModelRoute(Protocol):
    def complete(self, prompt: str, job: str) -> RouteResult:
        ...

class LedgerRoute:
    def __init__(self, inner: ModelRoute, db: sqlite3.Connection, job_budget: int):
        self.inner = inner
        self.db = db
        self.job_budget = job_budget

    def _used_for_job(self, job: str) -> int:
        row = self.db.execute(
            'SELECT COALESCE(SUM(tokens), 0) FROM usage WHERE job = ?',
            (job,),
        ).fetchone()
        return int(row[0])

    def complete(self, prompt: str, job: str) -> RouteResult:
        if self._used_for_job(job) >= self.job_budget:
            return RouteResult(False, 0, 0, 429, 'ledger')
        result = self.inner.complete(prompt, job)
        with self.db:
            self.db.execute(
                'INSERT INTO usage(job, provider, tokens, status) VALUES (?, ?, ?, ?)',
                (job, result.provider, result.tokens, result.status),
            )
        return result

The schema is deliberately small:

CREATE TABLE IF NOT EXISTS usage (
  id INTEGER PRIMARY KEY,
  job TEXT NOT NULL,
  provider TEXT NOT NULL,
  tokens INTEGER NOT NULL,
  status INTEGER NOT NULL,
  created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

The useful artifact is the row, not the generated text. After a failed job, you can query which job spent what instead of guessing.

Expose a read-only view before any write path

Deploy a small visibility endpoint on MonkeyCode's free server option if available. Do not add write endpoints yet.

from fastapi import FastAPI

app = FastAPI()

@app.get('/eval/remaining')
def remaining(job: str):
    used = ledger._used_for_job(job)
    return {'job': job, 'used': used, 'budget': ledger.job_budget}

This gives teammates a budget check without handing out a shared key. It also forces the team to treat the free server as a read-only slice first, which is the correct order before any shared write authority.

Decide when a free route is the right call

A free route is appropriate for read-only, batch-oriented, non-sensitive work. It is wrong when latency, privacy, or retry cost is the critical requirement.

Decision factor	Free route is appropriate	Use a paid or gated route
Read-only evaluation	yes	no
PII in payload	no	yes
p95 latency SLO	no	yes
Interactive retry loop	no	yes
Teammate batch experiment	yes	no

Run three failure tests before sharing the key

Do not trust the integration until these three cases pass against a stub route.

# Test 1: the ledger records usage
def test_ledger_records_usage():
    stub = StubRoute()
    stub.result = RouteResult(True, 412, 210, 200, 'free')
    ledger = LedgerRoute(stub, db, 1000)
    ledger.complete('summarize', 'job-1')
    assert 'job-1' in used_by_job('job-1', 412)

# Test 2: a job cannot exceed its budget
def test_budget_rejects_overage():
    stub = StubRoute()
    stub.result = RouteResult(True, 120, 210, 200, 'free')
    ledger = LedgerRoute(stub, db, 100)
    result = ledger.complete('rewrite', 'job-2')
    assert result.status == 429
    assert stub.calls == 0

# Test 3: provider failure falls back and is recorded
def test_fallback_on_provider_failure():
    failing = FailingRoute()
    fallback = StubRoute()
    fallback.result = RouteResult(True, 80, 190, 200, 'fallback')
    route = FallbackRoute(failing, fallback, db)
    result = route.complete('classify', 'job-3')
    assert result.provider == 'fallback'
    assert failure_row_exists()

These are not model-quality tests. They are budget-preservation tests. They tell you whether the free 30M token route survives uncontrolled reuse before a real teammate reruns a failed job.

Limitations and who should not use this

• The 30M token figure and free server option are operator-supplied; revisit the current quota before relying on it.
• SQLite write-per-request fits small teams, not high-concurrency traffic.
• The seam does not evaluate output quality; pair it with a golden set before switching routes.
• Do not use this for regulated data or user-facing writes.
• The free server option may have cold starts or sleep behavior, so it is not a latency SLO target.

If you want to see whether a free quota survives uncontrolled reuse, point this seam at MonkeyCode's free model access and free server option, then run the three tests before handing out the key. The metric that matters is not the demo output; it is whether the ledger shows attributed usage after a teammate reruns a failed job.