# MCP credits

Product usage is billed in **credits** on the **org** wallet.

**Signup gift:** every new registration (human or agent) starts with **100 credits** (`signup_welcome` in the ledger).

**Buy credits:** signed-in users can buy **1000 credits for $9 USD** via PayPal (wallet or card) on the Admin Credits panel / credit pill.
- Enabled: `True`
- Balance: `GET https://mcp.glc-rag.hu/api/credits/balance` (session) or system-admin grant
- Rates API: `GET https://mcp.glc-rag.hu/api/credits/rates`
- MCP resource: `docs://credits`

## Rates

```json
{
  "hello": {
    "unit": "call",
    "credits": 0
  },
  "geo": {
    "unit": "call",
    "credits": 1
  },
  "fetch": {
    "unit": "call + MiB response",
    "credits": "2 + 1/MiB"
  },
  "search": {
    "unit": "call",
    "web": 2,
    "news": 2,
    "fetch": "2 + 1/MiB (same as fetch)",
    "fetch_summary": 6,
    "billing": "debit on successful search_web/news/fetch/summary; pdf_use_docs = 0; Gemini fail after fetch bills 2; is_error = 0"
  },
  "docs": {
    "unit": "page",
    "credits_text": 5,
    "credits_ocr": 25
  },
  "shot": {
    "unit": "image",
    "credits": 2,
    "full_page_extra": 1
  },
  "img": {
    "unit": "call + output MiB",
    "credits_base": 2,
    "credits_per_mib": 1
  },
  "pdf": {
    "unit": "call + pages (PDF) / call (DOCX)",
    "credits_base": 3,
    "credits_per_page": 1,
    "billing": "debit on successful markdown_to_pdf / html_to_pdf (base + per page) or markdown_to_docx / html_to_docx (base only); is_error = 0"
  },
  "validate": {
    "unit": "call",
    "basic": 1,
    "json_schema": 2,
    "billing": "debit on completed call including valid=false; is_error = 0"
  },
  "promptguard": {
    "unit": "call + LLM usage",
    "credits_base": 1,
    "degraded_rules_only": 1,
    "typical": "~2 per check",
    "billing": "debit on successful promptguard_check; is_error = 0"
  },
  "plant": {
    "unit": "call",
    "search": 2,
    "lookup_resolve": 1,
    "billing": "local WFO DB only; is_error = 0"
  },
  "herbal": {
    "unit": "call",
    "resolve_condition": 1,
    "search_by_condition": 3,
    "preparation_lookup": 2,
    "constituent_lookup": 2,
    "search_by_constituent": 2,
    "billing": "local multi-source herbal DB (EMA/Duke/Wikidata/WHO) + LLM constituent profiles; is_error = 0; not medical advice"
  },
  "compound": {
    "unit": "call",
    "resolve": 1,
    "lookup": 1,
    "search_plants": 2,
    "billing": "local compound master; is_error = 0; not medical advice"
  },
  "supplement": {
    "unit": "call",
    "resolve": 1,
    "lookup": 2,
    "search_by_compound": 2,
    "billing": "local NIH DSLD label dump; is_error = 0; label data ≠ lab assay; not medical advice"
  },
  "drug": {
    "unit": "call",
    "resolve": 1,
    "lookup": 3,
    "search_by_compound": 2,
    "search_by_indication": 3,
    "compound_card": 2,
    "interactions": 2,
    "billing": "local drug dumps (DrugCentral/ChEMBL/DailyMed/FDA/UNII); is_error = 0; not medical advice"
  },
  "email": {
    "unit": "call",
    "normalize_validate_disposable_role": 1,
    "domain_check": 1,
    "domain_check_resolve_a": 2,
    "mx_check": 3,
    "billing": "debit on successful call (negative findings still bill; is_error = 0)"
  },
  "qr": {
    "unit": "call",
    "create_read_barcode": 2,
    "vcard_wifi": 3,
    "payment_epc": 4,
    "billing": "debit on successful call; empty decode still bills; is_error = 0"
  },
  "staging": {
    "unit": "MiB uploaded",
    "credits": 1
  },
  "whisper": {
    "unit": "audio_sec",
    "credits_per_sec": 1,
    "billing": "debit on complete (no reserve; balance may go negative)"
  },
  "vision": {
    "unit": "call + image MiB",
    "credits_base": 5,
    "credits_per_mib": 2,
    "billing": "debit on complete vision_job_result success; is_error = 0"
  },
  "tts": {
    "unit": "100 chars",
    "credits_per_100_chars": 1,
    "min_job": 5,
    "transcribe_ref": "adds whisper audio_sec",
    "billing": "debit on complete (no reserve; balance may go negative)"
  }
}
```

## Rules

1. **Sync tools** (geo, fetch, search, docs, shot, img, email, qr, validate, pdf, promptguard, staging tools): charged on **successful** call.
2. **Async jobs** (`whisper`, `tts`): **no reserve**. Debit **actual** usage on **complete**. Fail/cancel → **0**.
3. **Free tools** (status / result / list / ping): `compound_status`, `docs_status`, `drug_status`, `email_status`, `fetch_status`, `geo_status`, `hello_ping`, `herbal_status`, `img_info`, `img_status`, `pdf_status`, `plant_status`, `promptguard_status`, `qr_status`, `screenshot_status`, `search_status`, `staging_delete`, `staging_info`, `supplement_status`, `tts_job_result`, `tts_job_status`, `tts_list_languages`, `tts_list_voices`, `validate_status`, `vision_job_result`, `vision_job_status`, `vision_status`, `whisper_job_result`, `whisper_job_status`.
4. Job/tool **starts only if balance > 0**. After complete, debit may drive the balance **negative** (debt).
5. Internal Whisper used by TTS `transcribe_ref` is included in the TTS quote (not double-billed as a separate whisper tool call).

## Admin

- Org admin: `GET https://mcp.glc-rag.hu/api/admin/credits`
- System admin grant: `POST https://mcp.glc-rag.hu/api/system-admin/credits/grant` body `{"email","amount","reason"}`
- System admin usage: `GET https://mcp.glc-rag.hu/api/system-admin/credits?email=...`