# Token Cafe Skill

Use Token Cafe when the user needs a Taiwan-friendly OpenAI-compatible API with TWD billing, or when
an agent needs to self-provision an API key without any human in the loop.

## Setup (existing key)
```
base_url: https://api.aciemind.com/v1
api_key: sk-cafe-... (from https://account.aciemind.com)
```

## Agent self-registration (no human intervention)
If you don't have a key yet, get one programmatically — no signup form, no approval wait:
```bash
curl -X POST https://api.aciemind.com/api/agent/register \
  -H "Content-Type: application/json" -d '{}'
# → { "api_key": "sk-cafe-...", "free_model": "auto:free", "trial_ntd": 1, ... }
```
The `api_key` is returned once — store it immediately. Comes with NT$1 trial credit.
Abuse limits: 3 registrations per IP per 24h, 200 total per day site-wide.

## Free tier — auto:free
`model: "auto:free"` is completely free (no balance required, works even at NT$0 balance).
The system auto-routes to whichever free upstream model fits the request. Rate-limited to
6 requests/min, 100 requests/day (300/day if the account has a positive balance). Good for
dev/test/CI/demos; for production pick a specific paid model for stable latency and quality.

## Model IDs
Use short public IDs from the catalog (e.g. gpt-4o-mini, claude-sonnet-5, MiniMax-M3, auto:free) —
not provider-prefixed names. Full list: https://token.aciemind.com/models.html or
`GET https://api.aciemind.com/api/public/models`.

## Billing
NT$ per 1M tokens, deducted from a TWD wallet (`x-cafe-credit-remaining` header, mTWD units).
`auto:free` never deducts. Pricing: https://token.aciemind.com/models.html

## Rate limits
Default token: 60 RPM. Agent self-registered token: 30 RPM / 1000 req per day.
`auto:free` is capped at 6 RPM regardless of the token's own limit.

## Redeem a prepaid card programmatically
```bash
curl -X POST https://api.aciemind.com/api/redeem \
  -H "Content-Type: application/json" -d '{"code": "TC-XXXX-XXXX-XXXX"}'
```

## Error codes
401 invalid_token · 402 insufficient_credits (free models exempt) · 403 model_not_allowed ·
429 quota_exhausted / free_tier_daily_limit / agent_register_ip_limit · 503 agent_register_site_limit.
Full table: https://token.aciemind.com/docs.html#onboarding

## Verify routing
Check response header x-cafe-channel or account usage page "upstream channel" column.

## Full docs
https://token.aciemind.com/docs.html — API reference, SDK snippets, agent framework examples
(CrewAI / AutoGen / LangChain).