Documentation

API reference

Base URL https://api.metronium.xyz/v1. The surface is OpenAI-compatible, so an existing client needs no changes beyond the base URL and the key.

Endpoints

Method	Path	Auth	Purpose
GET	/models	none	Catalogue and per-token pricing.
POST	/chat/completions	key	Relay. Streaming and non-streaming.
GET	/key	key	Balance, active grant policy, rate limits.
GET	/auth/key	key	The same, in OpenRouter's response shape.
GET	/grants	key	Grants visible to this address, with remaining value.
GET	/health	none	Gateway, database and indexer lag.

Response headers

Header	Meaning
X-Metron-Cost	What this request cost, in USD. Absent on streamed responses, where the cost is not known until the last token.
X-Metron-Remaining	Value left on the active grant. On a stream this is the figure the request started from.
X-Metron-Request-Id	Quote this when reporting a problem. It is also the ledger reference.
X-Metron-Overhead-Ms	Milliseconds Metronium added, measured on this request, excluding the provider.
X-Metron-Grant	The grant id this request drew from.

Errors

Error bodies follow OpenAI's shape, so existing error handling keeps working.

{
  "error": {
    "message": "Grant 41 allows only anthropic/claude-sonnet-5.",
    "type": "invalid_request_error",
    "code": "model_not_allowed",
    "param": null
  }
}

Status	Code	When
401	invalid_api_key	Missing header, bad signature, or a rotated epoch.
402	insufficient_balance	The grant cannot cover the worst case for this request.
402	grant_expired	Past `expiresAt`. The remainder has returned to the grantor.
403	model_not_allowed	The model is not in this grant's allowlist.
403	grant_revoked	The grantor reclaimed the unactivated remainder.
429	rate_cap_exceeded	`ratePerHour` reached. Retry after the window moves.
429	rate_limit_exceeded	Requests per minute exceeded for this key.
502	upstream_error	The provider failed. No value is charged when no tokens were produced.
503	indexer_lagging	Chain state is too stale to serve safely. Nothing is charged.

What sits behind us

Requests are relayed through OpenRouter today. Direct provider contracts come later, once there is volume to negotiate with — so we are one hop behind a reseller, and we would rather say that than let you discover it. Our differentiator is the grant, not the hop count, and we do not advertise latency or uptime as an advantage.

One thing this buys you: upstream reports the real cost of every request, so what you are charged is that figure plus our spread. It is not derived from a price table we maintain and might get wrong.

Checking a budget

curl https://api.metronium.xyz/v1/key \
  -H "Authorization: Bearer $METRONIUM_API_KEY"

{
  "object": "key",
  "address": "0x71C…",
  "balance": { "currency": "USD", "available": "41.882300", "used": "8.117700" },
  "grant": {
    "id": 41,
    "models": ["anthropic/claude-sonnet-5"],
    "expires_at": "2026-09-23T00:00:00Z",
    "rate_per_hour": "5.000000",
    "rate_used_this_hour": "1.240000",
    "revocable": true
  },
  "rate_limit": { "requests_per_minute": 120 }
}

Money is always an exact decimal string. A charge lands after the response it pays for, so read this after a request to see what it cost.