Credits API

Check your credit balance and use credits for free AI chat completions

Credits API

Check your credit balance and spend credits on AI chat completions through the credits gateway.

Credits gateway

POST /api/v1/credits

Send an AI chat completion request using your credits. Each call costs 1 credit, debited from your referral credits balance. If the upstream AI gateway is unavailable or returns an error, the credit is automatically refunded.

Only free-tier models are available through this endpoint:

• openrouter/xiaomi/mimo-v2-pro (default)
• openrouter/google/gemini-2.0-flash-001
• openrouter/openai/gpt-4o-mini

If you request a model not in this list, the gateway falls back to openrouter/xiaomi/mimo-v2-pro.

Request body

The request body follows the OpenAI chat completions format. You can include any standard chat completion parameters.

Field	Type	Required	Description
messages	array	Yes	Array of message objects with role and content
model	string	No	One of the allowed models listed above. Defaults to openrouter/xiaomi/mimo-v2-pro if omitted or not in the allowed list.
stream	boolean	No	Set to true to receive a streaming response (SSE)

{
  "messages": [
    { "role": "user", "content": "Explain quantum computing in one paragraph" }
  ],
  "model": "openrouter/xiaomi/mimo-v2-pro"
}

Response

On success, the response contains the AI completion along with a _credits object showing the cost and remaining balance.

{
  "id": "chatcmpl-abc123",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses qubits..."
      }
    }
  ],
  "_credits": {
    "cost": 1,
    "remaining": 49
  }
}

The response also includes an X-Credits-Remaining header with your updated balance.

When stream is true, the response is a server-sent event stream with Content-Type: text/event-stream. The X-Credits-Remaining header is still included.

Response fields

Field	Type	Description
_credits.cost	number	Credits consumed by this call (always 1)
_credits.remaining	number	Credits remaining after this call

Response headers

Header	Description
X-Credits-Remaining	Updated credit balance after the call
X-Credits-Refunded	Set to 1 when the credit was refunded due to an upstream gateway error. Only present on error responses where a refund occurred.

Errors

Code	Description
401	Unauthorized — no valid session
402	Insufficient credits. The response includes error: "insufficient_credits" and your current credits balance.
404	User not found
4xx/5xx	Upstream gateway error. When the AI gateway returns a non-success status, the credit is automatically refunded. The upstream response body and status code are forwarded to the caller. The X-Credits-Refunded: 1 and X-Credits-Remaining headers are included.
502	AI gateway unavailable (connection failure). The credit is automatically refunded.
500	Internal server error. If a credit was already debited, it is refunded on a best-effort basis.

Credits are debited before the AI call is made to prevent double-spend. If the call fails for any reason — connection error, upstream 4xx/5xx, or internal error — credits are refunded automatically. Check the X-Credits-Refunded header to determine whether a refund occurred.

---

Check balance (v1)

GET /api/v1/credits

Returns your current credit balance, plan, cost per call, and the list of models available through the credits gateway.

Response

{
  "credits": 50,
  "plan": "solo",
  "costPerCall": 1,
  "allowedModels": [
    "openrouter/xiaomi/mimo-v2-pro",
    "openrouter/google/gemini-2.0-flash-001",
    "openrouter/openai/gpt-4o-mini"
  ]
}

Response fields

Field	Type	Description
credits	number	Available credits balance
plan	string	Current subscription plan (e.g. free, solo, collective, label, network)
costPerCall	number	Credits consumed per gateway call (currently 1)
allowedModels	string[]	Models available through the credits gateway

Errors

Code	Description
401	Unauthorized — no valid session

---

Get credit balance

GET /api/credits

Returns the authenticated user’s credit balance, referral code, referral count, and current plan. Requires session authentication.

Response

{
  "credits": 50,
  "referralCode": "abc123",
  "referralCount": 3,
  "plan": "solo"
}

Response fields

Field	Type	Description
credits	number	Total available credits (includes referral credits and claimed credits)
referralCode	string | null	Your referral code, or null if not set
referralCount	number	Number of successful referrals
plan	string	Current subscription plan (e.g. free, solo, collective, label, network)

Errors

Code	Description
401	Unauthorized — no valid session
500	Internal server error. Returns { "credits": 0 } as a fallback.

Credits from token holder claims (see Claim API) are added to the same credits balance returned by these endpoints. Use the Referrals API for a detailed breakdown of referral-specific statistics.