# Monke Agents API gateway (beta)

Base URL:

```
https://api.monkeagents.xyz/v1
```

OpenAI-compatible. Any client that accepts a base URL and a key works:

```
OPENAI_BASE_URL=https://api.monkeagents.xyz/v1
OPENAI_API_KEY=ma-k1-...
```

## Status

Beta, live. Token quota is not enforced yet: calls are metered (usage recorded per key per month) but
no call is rejected for quota. When the paid tier opens, the same endpoint starts enforcing the
allowance.

## Models

| model id | tier | notes |
|---|---|---|
| `monke-a1` | fast | default, lowest latency |
| `monke-a1-pro` | reasoning | slower, better at multi-step questions |
| `monke-a1-max` | frontier | strongest, highest cost |

`GET /v1/models` returns this list. If a model is unavailable, the gateway fails over to another model
and reports the model it actually used.

## Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/models` | none | list models |
| POST | `/v1/chat/completions` | Bearer key | chat completion, metered |
| GET | `/v1/keys/quota` | Bearer key | used tokens this month, beta flag |

## Example

```
curl https://api.monkeagents.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MONKE_KEY" \
  -d '{"model":"monke-a1","messages":[{"role":"user","content":"hi"}]}'
```

Response is the standard OpenAI shape:

```
{"id":"chatcmpl-...","object":"chat.completion","model":"monke-a1",
 "choices":[{"index":0,"message":{"role":"assistant","content":"..."},"finish_reason":"stop"}],
 "usage":{"prompt_tokens":12,"completion_tokens":34,"total_tokens":46,"estimated":false}}
```

## Keys

Keys look like `ma-k1-...`. Self-serve issuance is live:

1. `POST /v1/keys/challenge` with `{"address": "0x..."}` returns `{nonce, message, expires_at}`.
2. Sign `message` with the wallet (plain-text signature, no transaction, no gas).
3. `POST /v1/keys/new` with `{"address", "nonce", "signature"}` returns the key ONCE.
4. `POST /v1/keys/rotate` replaces it; `DELETE /v1/keys/self` revokes it.

Beta rule: the wallet needs **5 monkes** and one `.ai` Agent ID to issue a key. On every call the gateway re-reads
`balanceOf`; a wallet that sold its monke loses the key automatically. Humans can do the same flow at
https://monkeagents.xyz/keys/

Never print a full key in chat, a screenshot, or a commit. If a key leaks, ask for a replacement.

## Errors

OpenAI shape: `{"error":{"message":"...","type":"...","code":"..."}}`

| code | HTTP | meaning |
|---|---|---|
| `invalid_api_key` | 401 | missing, unknown or revoked key |
| `unknown_model` | 400 | model id not in the list above |
| `bad_request` | 400 / 415 | broken JSON or wrong content type |
| `upstream_error` | 502 | model provider failed after failover |
| `quota_exhausted` | 429 | reserved for the paid tier; not returned in beta |
| `rate_limited` | 429 | reserved; not returned in beta |

## Limits in beta

- No token quota, no per-minute request limit.
- Any single message is clipped to 4,000 characters and the last 20 messages are used.
- The public playground at https://monkeagents.xyz/playground/ is a separate, rate-limited toy
  (24 messages per IP every 24h). Use the gateway for real work.