# KeepBal

> KeepBal is Digidai’s agent capability layer: one dgk_live_ key for OpenAI-compatible models and priced tools, settled in a wallet you can audit. KeepRouter is a sister product, not this API.

Canonical URL: https://keepbal.com
Current upstream mode: monid_validation

Hard lock: upstream modes `aisa_validation` and `monid_validation` are temporary validation adapters only. They are not the permanent backend and not a white-label. Direct adapters fail closed (HTTP 503, not billed) when a capability is not configured.

## When to use KeepBal

- You want Digidai-owned identity, keys, wallet, and usage — not a white-label of another gateway.
- You need OpenAI-compatible `/v1` plus `/apis/v1` tools behind `Authorization: Bearer dgk_live_...`.

## When not to

- You need a live MCP/A2A transport, x402 payments, or self-service card top-ups today. Those are not available.
- You need a guarantee that every catalog model is available. Catalogs are candidates, not SLAs.

## Start

1. Open https://keepbal.com/sign-up
2. Create a key at https://keepbal.com/console/keys
3. `GET https://keepbal.com/healthz` then `GET https://keepbal.com/v1/models` with your key

## Machine-readable

- Agent Card: https://keepbal.com/.well-known/agent-card.json
- MCP discovery stub (HTTP tools; no MCP transport yet): https://keepbal.com/.well-known/mcp.json
- OpenAPI 3.1: https://keepbal.com/openapi.yaml
- Skill: https://keepbal.com/SKILL.md
- This file: https://keepbal.com/llms.txt
- Health: https://keepbal.com/healthz

## Models

OpenAI-compatible base: https://keepbal.com/v1

- `gpt-5.4` (openai, chat/completions) — input 3000000 / output 12000000 micro-USD per 1M tokens
- `gpt-5.4-mini` (openai, chat/completions) — input 600000 / output 2400000 micro-USD per 1M tokens
- `claude-sonnet-4.5` (anthropic, chat/completions) — input 3600000 / output 18000000 micro-USD per 1M tokens
- `claude-haiku-4.5` (anthropic, chat/completions) — input 1200000 / output 6000000 micro-USD per 1M tokens
- `gemini-2.5-pro` (google, chat/completions) — input 1500000 / output 12000000 micro-USD per 1M tokens
- `gemini-2.5-flash` (google, chat/completions) — input 360000 / output 3000000 micro-USD per 1M tokens
- `deepseek-v3.2` (deepseek, chat/completions) — input 336000 / output 504000 micro-USD per 1M tokens
- `qwen3-max` (alibaba, chat/completions) — input 1440000 / output 7200000 micro-USD per 1M tokens
- `jina-embeddings-v3` (jina, embeddings) — input 60000 / output 0 micro-USD per 1M tokens

Unknown ids may be forwarded in `aisa_validation` and are billed at input 2400000 / output 9600000 micro-USD per 1M tokens. `direct` model routes currently return 503.

## Tools

- `POST https://keepbal.com/apis/v1/tavily/search` — Web search with extracted page text (Tavily) (12000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/tavily/extract` — Extract content from known URLs (Tavily) (6000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/exa/search` — Neural semantic web search (Exa) (12000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/exa/contents` — Fetch full page contents (Exa) (6000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/firecrawl/scrape` — Scrape a page to clean markdown (Firecrawl) (6000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/firecrawl/search` — Web search returning scraped content (Firecrawl) (12000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/scholar/search/scholar` — Academic paper search with citations (Scholar) (12000 micro-USD / 2xx call)
- `POST https://keepbal.com/apis/v1/scholar/search/web` — Research-oriented web search (Scholar) (12000 micro-USD / 2xx call)

In the temporary validation mode reported by /healthz, catalog tool paths may be forwarded. A 2xx call is billed at the catalog price. direct implements Tavily search/extract only; other direct routes return 503 and are not billed.
A path not in this list is 15000 micro-USD on a 2xx response, except `monid_validation` discover/inspect/run/runs which use the Digidai-facing routes below.

When /healthz reports `monid_validation` (temporary adapter, not a white-label):
- `POST https://keepbal.com/apis/v1/discover` — not billed
- `POST https://keepbal.com/apis/v1/inspect` — not billed
- `POST https://keepbal.com/apis/v1/run` — Digidai debit = upstream quoted USD (pass-through + documented markup_bps, default 0) only on completed provider-success. Provider 4xx/5xx, FAILED, BLOCKED, TIMED_OUT, and 202-in-flight are $0.
- `GET https://keepbal.com/apis/v1/runs` and `GET https://keepbal.com/apis/v1/runs/:runId` — list/poll; a previously unpaid successful run settles once
- `POST https://keepbal.com/apis/v1/runs/:runId/stop` — not billed at request time
- `GET https://keepbal.com/apis/v1/wallet/balance` — Digidai wallet, not an upstream provider wallet
Static catalog paths such as tavily/search return 503 in this mode and are not billed. Model /v1 inference also returns 503.

## Wallet

- Balance: `GET https://keepbal.com/v1/credits/balance`
- Usage: `GET https://keepbal.com/v1/usage`
- Signup grants $1 promotional credit; extra credit is an operator grant from /admin. No self-serve card or crypto payment yet.
- No email verification, password recovery, OAuth or MFA yet. Save your password.
- Model tokens are billed when the provider returns usage; settlement is asynchronous.
- A 2xx model response with no extractable token usage costs 0. Image pricing and non-OpenAI streaming usage are not implemented.
- Money is integer micro-USD (1 USD = 1,000,000)
- `402 insufficient_credits` — wallet below the configured floor
- `503 provider_unavailable` — no upstream for that route; never billed
- `501 not_implemented` — `/apis/v2/*` x402 is not available.

Always send `Authorization: Bearer dgk_live_...`. Errors use the OpenAI envelope `{"error":{"message","type","code","param","request_id"}}`. `request_id` matches the `x-digidai-request-id` header. Successful and rate-limited `/v1` and `/apis` responses include approximate `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` (KV window, not an exact RPM counter). Those headers are listed in `Access-Control-Expose-Headers`.