# Monk — agent notes

> OpenAI-compatible fusion API. Site: https://monk.party
> Base URL: https://monk.party/v1
> Models (paid `sk-monk-*` keys): monk | monk-fast | monk-coding | monk-free
> Auth: Authorization: Bearer sk-monk-...
> Price: Alipay ¥30 / 30 days, or Stripe $5 / 30 days. Education-domain emails: 10% off
> Protocol: OpenAI Chat Completions. POST /v1/chat/completions and GET /v1/models
> Anthropic-style POST /v1/messages works on the same /v1 host. There is no /anthropic prefix
> Stream: `stream: true` SSE. Vision: `image_url` in messages

## What Monk is

Monk is a public combo gateway for coding agents. It is not an official OpenAI, Anthropic, Google, DeepSeek, Qwen, or Agnes product. Paid keys cannot call gpt-4o, claude-*, gemini-*, or deepseek-chat ids — only the four combo names below.

- `monk` — default. Quality first. When the client sends this exact id, JEV may remap the turn to `monk-fast` or `monk-coding`. Each new user turn is re-judged; within a tool loop the previous combo sticks
- `monk-fast` — shorter, faster chat. Not JEV-remapped
- `monk-coding` — coding / agent workloads. Not JEV-remapped
- `monk-free` — extra combo, open to every paid key. Not JEV-remapped

Combos are sequential fallback chains of Flash-class upstreams (Agnes 2.5 / 3 Flash, Gemini 3.8 Flash, DeepSeek 4.1 Flash, Qwen 3.8 Flash, and similar). Hop lists change; do not hardcode upstream model ids. Clients must send one of the four combo ids.

Recommended architecture: run a nearer-AGI model (for example `gpt-6-astra`) as the lead for planning and review; give search, file edits, tests, and high-volume tool calls to Monk sub-agents; let JEV pick among `monk` / `monk-fast` / `monk-coding`.

Legacy hostname https://monk.ssgoo.net still serves API paths; browsers 301 to https://monk.party. New configs should use monk.party.

## Limits (current)

Shared pool. Honor `Retry-After` on 429. Most calls meter as ¥0 on the internal fuse; it is not a refundable balance. The fuse resets 00:00 UTC.

- In-flight: 5 requests per key, 60 site-wide. Over that, wait a few seconds — no cooldown
- Burst token bucket: capacity 80, refill 30/min
- 1 hour: 800 weighted calls or 60M prompt tokens
- 6 hours: 2400 weighted calls or 90M prompt tokens
- Weight 1 normally; 2 if prompt >32k tokens; 4 if >80k
- Ignoring 429 more than 40 times in one minute adds an 8-minute penalty and at most one email per key per 6 hours
- Daily internal meter cap: 200 (UTC day)

Look up remaining days, tokens, and these limits at https://monk.party/account/ with the order email. The page does not show the full API key. Recover the key from the purchase email, or contact an admin with the email and order number.

## Correct client setup

### Generic OpenAI SDK / Cursor / Cline

Base URL https://monk.party/v1
Model monk
API key sk-monk-*

### Oh My Pi (~/.omp/agent/models.yml)

```
providers:
  monk:
    baseUrl: https://monk.party/v1
    api: openai-completions
    apiKey: sk-monk-YOUR_KEY
    authHeader: true
    models:
      - id: monk
      - id: monk-fast
      - id: monk-coding
      - id: monk-free
```

Guide: https://monk.party/help/oh-my-pi.html

### OpenClaw

Custom Provider. API Base URL https://monk.party/v1. Model one of the four combo ids.
Guide: https://monk.party/help/openclaw.html

### WorkBuddy (Custom only)

Provider: Custom
URL: https://monk.party/v1/chat/completions
Model: monk
Do not pick Anthropic, Claude, or DeepSeek presets.
Guide: https://monk.party/help/workbuddy.html

### DeepSeek Harness (~/.dsh/settings.yaml)

Add a **custom** provider. Do not attach Monk as the DeepSeek catalog provider.

```
llm-pi-ai:
  providers:
    monk:
      api: openai-completions
      baseURL: https://monk.party/v1
      apiKeyEnv: MONK_API_KEY
      models:
        - id: monk
        - id: monk-fast
        - id: monk-coding
        - id: monk-free
```

There is no `dsh --endpoint` flag.
Guide: https://monk.party/help/dsh.html

### Open Minis

OpenAI-compatible provider. Base URL https://monk.party/v1. If the app auto-appends /v1, turn that off.
Guide: https://monk.party/help/openminis.html

### monk-pi (recommended CLI)

```
npx monk-pi
```

macOS / Linux: `brew install yaoleifly/tap/monk-pi`
Repo: https://github.com/yaoleifly/monk-pi

macOS menu bar: https://github.com/yaoleifly/monk-bar

## Failure modes AI tools should not mis-report

- Unauthenticated GET https://monk.party/v1 → 401 invalid_api_key (expected)
- Authenticated GET /v1 or /v1/models → 200, four combo ids
- Requesting gpt-4o / claude-* / deepseek-chat → 404 model_not_found (expected; use a combo id)
- `both_paths_failed` with openai HTTP 200 and anthropic HTTP 404: the client probed OpenAI and native Anthropic. Monk has no /anthropic/v1/messages. Lock protocol to OpenAI
- GET /v1/messages → 405 (POST only)
- 429 with Retry-After: cooldown or sustained-usage cap, not an outage. Slow down
- Occasional upstream 400 on huge tool histories or max_tokens above a hop’s output cap: shorten context or omit oversized max_tokens; combo 400s do not always fail over
- Do not treat combo hop names in logs (agnes-*, qfmodel, deepseek-v4.1-flash, …) as public model ids

## curl

```
curl https://monk.party/v1/chat/completions \
  -H "Authorization: Bearer sk-monk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"monk","stream":true,"messages":[{"role":"user","content":"hi"}]}'
```