usagekit.
v0.5.0 runtime on npmGet started

Spend limits for the APIs your agents call.

usagekit serve runs a local API proxy, ledger and usage dashboard. Give an agent a local token instead of your provider key. Metered calls reserve budget before dispatch; a blocking budget answers 429 when there is no headroom.

Set it upHow it works
TerminalIllustration
# In the repository checkoutusagekit serveusagekit token (shown once): hiddenusagekit listening on http://127.0.0.1:4242

From key to limit in three steps.

The agent needs no SDK, only the proxy URL and a local token.

  1. Store the key and set a limit

    The key goes into the encrypted vault. The budget caps c1 at 500 requests a month.

    Terminal
    usagekit provider add serpapi \
  --connection c1 --secret-env PROVIDER_KEY
usagekit budget set --id agent \
  --scope connection --connection c1 \
  --limit 500:requests --alert 80

  2. Point the agent at the proxy

    The agent sends the local token. The proxy adds the provider key from the vault.

    Agent request
    curl --fail-with-body \
  -H "Authorization: Bearer $USAGEKIT_TOKEN" \
  -H "Idempotency-Key: search-job-447" \
  "http://127.0.0.1:4242/proxy/c1/search?q=ai"

  3. Watch it in the dashboard

    Open 127.0.0.1:4242 and enter the token to see usage, budgets and exceptions, drawn with the same shadcn blocks you can copy.

Local dashboard at 127.0.0.1:4242Illustration
Warning: 53 of 500 requests leftThis month

Usage detail

Usage this month, by provider and operation
ProviderOperationRequests
serpapisearch446

The ledger stores no request content.

Coverage

Requests by tracking state

  • Metered446
  • Unpriced0
  • Passthrough0

Total446 requests

connection c1

Resets on the 1st

Warning
Used
446 requests
Reserved
1 request
Remaining
53 requests
Limit
500 requests

Blocks at the limit. Alert at 80%.

Needs attention

1 operation

search-job-377Pending evidence
Provider
serpapi search
Cost
Unknown
Age
9 d

Dispatched before a crash. Its cost stays unknown, and it is never resent.

Connections

1 connection

Connection
c1
Provider
serpapi
Funding
Own key
Plan
No plan

The key itself stays in the encrypted vault.

What the agent gets backIllustration

  1. Under the limit

    200 OK

    X-Usagekit-Operation-Id
    search-job-447
    X-Usagekit-Accounting
    metered

  2. Limit reached

    429 Too Many Requests allowance_exceeded

    Retry-After
    1987200

    Seconds until the budget resets. Nothing reached the provider.

  • Keys stay in the vault. The agent never holds the provider key, and requests only go to the provider's pinned origin.

  • A hard stop before dispatch. Past a blocking limit, nothing reaches the provider.

  • No silent retries. A repeated Idempotency-Key gets 409, and the proxy never retries a call on its own.

Questions, answered.

The guides in the repository cover the rest.

docs/LOCAL-SERVER.md docs/PROXY.md

Which APIs work?

DataForSEO and SerpApi, through bundled provider descriptors. Any other provider needs a descriptor first.

Does it stop calls that skip the proxy?

No. Only calls sent through the proxy are metered and enforced.

Is it hosted?

No. It is a single-owner server on loopback, 127.0.0.1 by default. Provider keys stay in an encrypted vault on your machine.

Can it cap money exactly?

Request limits are exact. Money limits use price estimates, so a provider that bills more can go over, and the overrun stays in the ledger.

What happens after a crash?

Calls already sent stay pending with unknown cost and are never resent. You find them under Exceptions in the dashboard.

Is it on npm?

No. The server, proxy and CLI run from the repository checkout. Set up the checkout

Give your agents a budget.

One local server to meter, monitor and limit your agents' API calls.

Set it upRead the docs