# JoinGonka Gateway documentation

> Every JoinGonka Gateway documentation page in English, one after another. Index: https://gate.joingonka.ai/llms.txt

---

Source: <https://gate.joingonka.ai/docs.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Connect Gonka models to your tool

OpenAI- and Anthropic-compatible API. Pick your tool — get the install command, an agent prompt, and a verification step.

## Quick facts

- Base URL for OpenAI API clients: `https://gate.joingonka.ai/v1`
- Base URL for Anthropic API clients, without `/v1`: `https://gate.joingonka.ai`
- The key is passed in the `Authorization: Bearer jg-…` or `x-api-key: jg-…` header
- List of available models: `GET https://gate.joingonka.ai/v1/models`
- Recommended model: `MiniMaxAI/MiniMax-M2.7`

## Connect a tool

Pick your tool — below are three steps tailored to it. The installer configures the tools in the table below (25 of them) with a single command; the rest are connected via a guide.

### Key

Sign up at [gate.joingonka.ai](https://gate.joingonka.ai/register) and create a key in your dashboard. Right after signing up, 3M free tokens land in your account.

### Connection

The installer configures the tool on its own: it prompts for the key with hidden input, writes the config, and verifies the connection. The value for `--tool` is in the tool table below.

```bash
npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7
```

Or delegate the setup to an AI agent — send it this prompt:

```text
Connect your tool to JoinGonka Gateway — the OpenAI- and Anthropic-compatible API of the Gonka network — following the instructions at https://gate.joingonka.ai/docs/agents.md. I'll provide the key myself: don't save it in repository files and don't modify global environment variables. At the end, verify the connection with a short request and report the result.
```

Step-by-step guides for each tool are linked in the table below.

### Verification

Account balance — this request doesn't spend tokens:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

A short request to the model — a 200 response means everything is set up:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

### All tools

| Tool | Type | Installer |
| --- | --- | --- |
| [Cursor](https://joingonka.ai/en/knowledge/cursor/) | IDE | `--tool cursor` |
| [Claude Code](https://joingonka.ai/en/knowledge/claude-code/) | CLI agent | `--tool claude-code` |
| [OpenClaw](https://joingonka.ai/en/knowledge/openclaw/) | CLI agent | `--tool openclaw` |
| [OpenCode](https://joingonka.ai/en/knowledge/opencode/) | CLI agent | `--tool opencode` |
| [Continue](https://joingonka.ai/en/knowledge/continue-dev/) | IDE | `--tool continue` |
| [Cline](https://joingonka.ai/en/knowledge/cline/) | IDE | `--tool cline` |
| [Aider](https://joingonka.ai/en/knowledge/aider/) | CLI agent | `--tool aider` |
| [LangChain](https://joingonka.ai/en/knowledge/langchain/) | Framework | — |
| [n8n](https://joingonka.ai/en/knowledge/n8n/) | Framework | — |
| [Open WebUI](https://joingonka.ai/en/knowledge/open-webui/) | Chat | — |
| [LibreChat](https://joingonka.ai/en/knowledge/librechat/) | Chat | — |
| [Hermes](https://joingonka.ai/en/knowledge/hermes/) | CLI agent | `--tool hermes` |
| [Kilo Code](https://joingonka.ai/en/knowledge/kilo-code/) | IDE | `--tool kilo` |
| [Roo Code](https://joingonka.ai/en/knowledge/roo-code/) | IDE | `--tool roo` |
| [LlamaIndex](https://joingonka.ai/en/knowledge/llamaindex/) | Framework | — |
| [PydanticAI](https://joingonka.ai/en/knowledge/pydantic-ai/) | Framework | — |
| [Vercel AI SDK](https://joingonka.ai/en/knowledge/vercel-ai-sdk/) | Framework | — |
| [TanStack AI](https://joingonka.ai/en/knowledge/tanstack-ai/) | Framework | — |
| [ZCode](https://joingonka.ai/en/knowledge/zcode/) | CLI agent | `--tool zcode` |
| [JetBrains](https://joingonka.ai/en/knowledge/jetbrains/) | IDE | `--tool jetbrains` |
| [Copilot BYOK](https://joingonka.ai/en/knowledge/copilot-byok/) | IDE | `--tool copilot-byok` |
| [Zed](https://joingonka.ai/en/knowledge/zed/) | IDE | `--tool zed` |
| [Pi](https://joingonka.ai/en/knowledge/pi/) | CLI agent | `--tool pi` |
| [Codex CLI](https://joingonka.ai/en/knowledge/codex/) | CLI agent | `--tool codex` |
| [DeepSeek Harness](https://joingonka.ai/en/knowledge/deepseek-harness/) | CLI agent | — |
| [MiniMax Code](https://joingonka.ai/en/knowledge/minimax-code/) | CLI agent | `--tool minimax-code` |
| [Warp](https://joingonka.ai/en/knowledge/warp/) | CLI agent | — |
| [Trae](https://joingonka.ai/en/knowledge/trae/) | IDE | — |
| [Cherry Studio](https://joingonka.ai/en/knowledge/cherry-studio/) | Chat | — |
| [omp (Oh My Pi)](https://joingonka.ai/en/knowledge/omp/) | CLI agent | `--tool omp` |
| [OpenHands](https://joingonka.ai/en/knowledge/openhands/) | CLI agent | — |
| [Qwen Code](https://joingonka.ai/en/knowledge/qwen-code/) | CLI agent | `--tool qwen-code` |
| [Goose](https://joingonka.ai/en/knowledge/goose/) | CLI agent | `--tool goose` |
| [Crush](https://joingonka.ai/en/knowledge/crush/) | CLI agent | `--tool crush` |
| [Zoo Code](https://joingonka.ai/en/knowledge/zoo-code/) | IDE | `--tool zoo` |
| [Kimi Code](https://joingonka.ai/en/knowledge/kimi-code/) | CLI agent | `--tool kimi-code` |
| [Factory Droid](https://joingonka.ai/en/knowledge/factory-droid/) | CLI agent | `--tool droid` |
| [MiMo Code](https://joingonka.ai/en/knowledge/mimo-code/) | CLI agent | `--tool mimo-code` |

## Code examples

The same request via the OpenAI SDK, cURL, and the Anthropic SDK. The key is read from the `JOINGONKA_API_KEY` environment variable.

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gate.joingonka.ai/v1",
  apiKey: process.env.JOINGONKA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
});
console.log(response.choices[0].message.content);
```

### cURL

```bash
curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'
```

### Anthropic SDK

```python
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

message = client.messages.create(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(message.content[0].text)
```

## Documentation sections

- [API](https://gate.joingonka.ai/docs/api) — Reference for the OpenAI- and Anthropic-compatible API to Gonka network models: keys, parameters, streaming, tools, plugins. Free tokens when you sign up.
- [Models](https://gate.joingonka.ai/docs/models) — Gonka network models in a single API: id for the model field, context, output limit, pricing, and status. The same open models at a fraction of the cost.
- [Errors & Rate Limits](https://gate.joingonka.ai/docs/errors) — Gateway error codes, request limits, and timeouts: what each response means and when to retry your request.
- [Pricing & Account](https://gate.joingonka.ai/docs/billing) — Gonka network models priced per token: free tokens to start, top up with GNK, USDT, or a card, all fees out in the open, and an account API to track your spending.
- [For Agents](https://gate.joingonka.ai/docs/agents) — Hand the link to your AI agent and it will connect Claude Code, Cursor, or Codex to Gonka network models on its own: ready-made prompt, guide, and skill.

---

Source: <https://gate.joingonka.ai/docs/api.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# API reference

Everything about requests to the gateway: protocols, endpoints, keys, and parameters. Below — streaming, tool calling, reasoning, plugins, and the cost of a request in the response.

## Protocols and endpoints

The gateway accepts OpenAI and Anthropic formats. The base URL for the OpenAI SDK is `https://gate.joingonka.ai/v1`, for the Anthropic SDK — `https://gate.joingonka.ai`. All protocols run on the same key and the same balance: a request in any format follows the same path.

| Method and path | Format | Use case | Notes |
| --- | --- | --- | --- |
| `POST /v1/chat/completions` | OpenAI Chat Completions | Chat, agents, tool calling | The primary path: the gateway converts other formats into it. |
| `POST /v1/messages` | Anthropic Messages | Claude Code and the Anthropic SDK | Base URL without `/v1`; `claude-*` models are replaced with the recommended one; the `max_tokens` field is required. |
| `POST /v1/responses` | OpenAI Responses | Codex CLI and the new OpenAI SDKs | Stateless: send the full history with every request. |
| `POST /v1/completions` | OpenAI Completions (legacy) | Autocomplete and code editing in editors | `suffix` is passed to the model as a hint; the response includes `logprobs: null`. |
| `POST /v1/embeddings` | OpenAI Embeddings | Vector representations of text | Response `501`: the network has no embedding models. |

### Discovery endpoints

They respond without a key. A table of models with context and status is in the [Models](https://gate.joingonka.ai/docs/models) section.

| Method and path | Description |
| --- | --- |
| `GET /v1/models` | Model list: context, prices, supported parameters — fields in OpenRouter format. |
| `GET /v1/models/{model}` | A single model's card; a slash in the id works as-is or as `%2F`. A hidden or unknown model returns `404 model_not_found`. |
| `GET /v1/capabilities` | Gateway capabilities: parameters, protocols, plugins, cost fields, and limits (`limits`). |
| `GET /v1/plugins` | Plugins: id and name. |
| `GET /v1/network-status` | Status of network models: availability, latency, uptime. |
| `GET /v1/nodes` | Node pool summary: total, active, and quarantined. |
| `GET /v1/web-search/engines` | Whether web search is enabled and the state of its engines. |

### Anthropic Messages

- Base URL — `https://gate.joingonka.ai`: the SDK will append `/v1/messages` itself.
- The key goes in the `x-api-key` header (that's how the Anthropic SDK sends it) or in `Authorization: Bearer`.
- `claude-*` models are replaced by the gateway with the recommended one (`MiniMaxAI/MiniMax-M2.7`); the `model` field in the response keeps the name the client sent.
- `max_tokens` is required, as in the Anthropic API; above the model's ceiling it gets trimmed.
- Streaming uses Anthropic events; during pauses the gateway sends `event: ping`, and a failure arrives as an `event: error` event.
- The model's reasoning doesn't appear in the response: there are no `thinking` blocks.
- The built-in `web_search` is executed by the gateway's web search plugin — see the [Plugins](https://gate.joingonka.ai/docs/api#plugins) section.
- There's no token counting (`/v1/messages/count_tokens`) — response `404`.

The easiest way to set up Claude Code is with the installer — [connecting tools](https://gate.joingonka.ai/docs#connect). Manually, use environment variables; `ANTHROPIC_MODEL` pins the network model.

#### Claude Code

```bash
export ANTHROPIC_BASE_URL=https://gate.joingonka.ai
export ANTHROPIC_AUTH_TOKEN=$JOINGONKA_API_KEY
export ANTHROPIC_MODEL=MiniMaxAI/MiniMax-M2.7
claude
```

#### cURL

```bash
curl https://gate.joingonka.ai/v1/messages \
  -H "x-api-key: $JOINGONKA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'
```

### OpenAI Responses

- The gateway doesn't store responses: send the full history in `input`. The `previous_response_id` and `conversation` fields return error `400` with a code.
- `store` is accepted and changes nothing.
- Tools: `function` and `web_search` — the latter is executed by the web search plugin. Other built-in tools are skipped by the gateway and the request runs without them; requiring such a tool via `tool_choice` returns error `400`.
- The `input_image` and `input_file` parts return error `400`: network models work with text.
- State endpoints (`GET /v1/responses/{id}`, `DELETE /v1/responses/{id}`, `GET /v1/responses/{id}/input_items`, `POST /v1/responses/{id}/cancel`, `POST /v1/responses/compact`) respond `404` with a code — the gateway doesn't store responses.
- Codex CLI: set your own provider id in `model_provider` (not openai) — then Codex compresses history itself, without `/v1/responses/compact`.

### Legacy Completions

- `prompt` is a string or an array of one string; the response is in `choices[].text`. Multiple prompts or tokens instead of text return error `400`.
- `suffix` is passed to the model as a hint in the prompt: the network has no true middle-fill.
- The response includes `logprobs: null`; `best_of` is ignored; `echo` works.

## Keys and authorization

The key is passed in the `Authorization: Bearer jg-…` or `x-api-key: jg-…` header — on all endpoints. A key is created after signing up on the [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) page.

| Prefix | Key | Model requests |
| --- | --- | --- |
| `jg-` | Regular account key | yes |
| `gc-` | Child key: its own limits, spend comes from the owner's balance | yes |
| `gm-` | Management key: manages children only | no — `403 forbidden` |

- In the dashboard you can set a spend limit per key for day, month, and total; exceeding it returns `402 child_key_limit_exceeded`.
- The number of requests per minute per key is limited — see the [Limits](https://gate.joingonka.ai/docs/errors#limits) section for values.
- Only the demo chat on the website works without a key: a request without a key from your own code will get `402` with `is_demo`.
- Keys can only be managed in the dashboard: `/api/keys` with an API key is unavailable. Balance and spend per key — [Account API](https://gate.joingonka.ai/docs/billing#account-api).

> Your key is a secret: don't keep it in your repo or frontend code — pass it via environment variables.

## Examples

The same request across four SDKs. The model is the recommended one (`MiniMaxAI/MiniMax-M2.7`), and the key comes from the environment variable `JOINGONKA_API_KEY`.

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gate.joingonka.ai/v1",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(response.choices[0].message.content)
```

### TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gate.joingonka.ai/v1",
  apiKey: process.env.JOINGONKA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
});
console.log(response.choices[0].message.content);
```

### cURL

```bash
curl https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}]
  }'
```

### Anthropic SDK

```python
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gate.joingonka.ai",
    api_key=os.environ["JOINGONKA_API_KEY"],
)

message = client.messages.create(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
)
print(message.content[0].text)
```

### Streaming response

#### Python

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://gate.joingonka.ai/v1", api_key=os.environ["JOINGONKA_API_KEY"])

stream = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M2.7",
    messages=[{"role": "user", "content": "What is Gonka?"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

#### TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gate.joingonka.ai/v1", apiKey: process.env.JOINGONKA_API_KEY });

const stream = await client.chat.completions.create({
  model: "MiniMaxAI/MiniMax-M2.7",
  messages: [{ role: "user", content: "What is Gonka?" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

#### cURL

```bash
curl -N https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M2.7",
    "messages": [{"role": "user", "content": "What is Gonka?"}],
    "stream": true
  }'
```

#### Anthropic SDK

```python
import os
import anthropic

client = anthropic.Anthropic(base_url="https://gate.joingonka.ai", api_key=os.environ["JOINGONKA_API_KEY"])

with client.messages.stream(
    model="MiniMaxAI/MiniMax-M2.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is Gonka?"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

## Request parameters

The `POST /v1/chat/completions` parameters that the gateway guarantees itself are listed in the `supported_parameters` array of the capabilities response:

| Parameter | Description |
| --- | --- |
| `temperature` | Response randomness: the higher the value, the more varied the output. |
| `top_p` | Token selection by cumulative probability. |
| `top_k` | Selection from the k most likely tokens. |
| `min_p` | Cuts off unlikely tokens relative to the most likely one. |
| `frequency_penalty` | Penalty for frequent repetitions. |
| `presence_penalty` | Penalty for tokens already seen. |
| `repetition_penalty` | Multiplier against repetitions. |
| `stop` | Strings at which generation stops. |
| `seed` | Seed for reproducibility. |
| `max_tokens` | Response token limit; anything above the model ceiling is clipped to the ceiling. |
| `max_completion_tokens` | Another name for `max_tokens`: the gateway moves the value into it. |
| `tools` | Functions the model can call, in OpenAI format. |
| `tool_choice` | Whether to call a function: model's choice, never, required, or a specific one. |
| `response_format` | Structured response: `json_object` or `json_schema`. |

- Without `temperature`, the gateway substitutes `0.7`.
- Without `max_tokens`, the gateway substitutes the model default: shorter without streaming, the model ceiling when streaming. Per-model numbers are in the [Limits](https://gate.joingonka.ai/docs/errors#limits) section.

### Passed through to the network as-is

`reasoning_effort`, `reasoning`, `enable_thinking`, `chat_template_kwargs`, `thinking_token_budget`, `min_tokens`, `logit_bias`, `n`, `parallel_tool_calls`, `extra_body`. The gateway doesn't validate them: a value outside the network's list returns a `400` error of type `api_error`.

### Not passed through to the network

All other fields are accepted by the gateway but not passed to the network — for example, `user`, `metadata`, `store`, `logprobs`, `top_logprobs`, `thinking`, `stream_options`, `web_search_options`. `usage` always arrives in the stream.

## Streaming

- `stream: true` is a response of SSE events; the last event is `data: [DONE]`.
- Before finishing, a chunk with `usage` arrives — always, even without `stream_options`.
- During pauses, the gateway sends the comment `: keep-alive` every 15 s — SSE clients skip it.
- Before the stream is opened, a failure comes back as a regular response code; after it's opened, as a chunk with `joingonka-error`.
- In `delta.tool_calls`, one call per chunk: the gateway splits calls that the network glued together.

```text
data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":2,"total_tokens":14}}

data: [DONE]
```

### Gateway service chunks

You can recognize them by the `id` field:

| `id` | When and what's inside |
| --- | --- |
| `joingonka-error` | Failure after the stream opened: the `error` field, then a break without `[DONE]`. |
| `joingonka-stream-stalled` | The network went silent longer than the allowed pause: the stream closes with `finish_reason: stop`. |
| `joingonka-stream-unfinished` | The network interrupted generation: `finish_reason: length` — continue with the next request. |
| `joingonka-citations` | Web search sources in `delta.annotations` — before finishing. |
| `joingonka-meta` | Cost and timings — only with the `x-joingonka-meta: 1` header. |

### Streaming in other protocols

- Anthropic Messages: events from `message_start` to `message_stop`, `event: ping` during pauses, failure as `event: error`.
- OpenAI Responses: `response.*` events, failure as `response.failed`.
- Legacy Completions: on failure, `data: {"error": …}`, then `[DONE]`.

## Tool calling

- OpenAI format: `tools` and `tool_choice`. The older `functions` and `function_call` format is also accepted — and the response comes back in it too.
- In streaming, one call per chunk: clients that only read the first element don't lose calls.
- The gateway repairs history that the network would reject with a `400` error: the `developer` role becomes `system`, empty and duplicate call ids get unique ones, an object `arguments` becomes a JSON string, a missing `type` is filled in, and a call without a name is removed along with its result.
- A call the model wrote as markup in the text is moved by the gateway into `tool_calls`; false calls in a response to a request without tools are removed.
- Generation broke off mid-arguments — you'll get `finish_reason: length`, not `tool_calls`: increase the response limit.

```json
{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
```

### JSON-Schema restrictions

Tool schemas and `response_format` are compiled by the network into a grammar; regular expressions use the RE2 engine. The gateway normalizes the schema into a form the network accepts:

- `$ref` are expanded in place, the `$defs` and `definitions` sections are removed; a recursive reference becomes an unconstrained schema.
- `pattern` with constructs not supported in RE2 (lookahead and lookbehind, backreferences, atomic groups, possessive quantifiers) is dropped; repetitions above 1000 are reduced to 1000.
- `anyOf` and `oneOf` of constants are collapsed into `enum`; if there are more than 16 non-collapsible branches, the union is dropped.

> The schema may end up looser than the original — validate call arguments on your side.

## Structured response

`response_format`: `{"type": "json_object"}` returns valid JSON, `{"type": "json_schema", "json_schema": {"name": …, "schema": …}}` follows your schema with the restrictions above. Truncated JSON without streaming is fixed by the `response-healing` plugin.

```json
{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "Name three planets."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "planets",
      "schema": {
        "type": "object",
        "properties": {"planets": {"type": "array", "items": {"type": "string"}}},
        "required": ["planets"]
      }
    }
  }
}
```

## Reasoning

- The model's reasoning arrives separately from the response: `message.reasoning_content`, and in streaming, `delta.reasoning_content`. The gateway renames the `reasoning` field into this format.
- Reasoning spends `max_tokens`: with a small limit, the response cuts off (`finish_reason: length`) before any text.
- If there's no response text but there is reasoning, the gateway moves it into `content` — except for responses with a tool call.
- `reasoning_effort` and `reasoning.effort` are passed to the network. If the model has only two modes, the gateway maps the value to them: `none` and `minimal` → `low`, higher ones → default reasoning.
- If a node rejects the value, the gateway downgrades it (`max` and `xhigh` → `high`, `minimal` → `low`, otherwise drops the field) and retries the request.
- In `/v1/messages`, reasoning is not passed — there are no `thinking` blocks.

## Plugins

Plugins are enabled via the `plugins` field — an array of strings or objects with options. The list is `GET /v1/plugins`.

| Plugin | Description | Conditions |
| --- | --- | --- |
| `response-healing` | Fixes truncated JSON in the model's response. | Only without streaming, and only if the response starts with `{` or `[`. |
| `privacy-sanitization` | Masks emails, IPv4 addresses, card numbers, JWTs, 64-character hex keys, and keys of the form `sk-…`, `gw_…`, `gm-…`, `Bearer …` in text messages. | The mode is the `privacy_mode` field: `redact` (default) or `tokenize`. |
| `file-parser` | Extracts text from PDFs. | When the message text is entirely a base64 PDF: `data:application/pdf;base64,…` or without a prefix. |
| `web` | Web search: results are mixed into the request, and the response gets source links. | Together with `privacy-sanitization` — a `400` error. |

### Web search

- Options: `max_results` — from 1 to 10, default 5; `engine` — engine hint; `search_prompt` — custom text before results; `enabled: false` — disable search.
- Sources are in `message.annotations[].url_citation`; in streaming, in a `joingonka-citations` chunk before finishing.
- `mode: "agent"` — the model decides for itself whether and what to search; `max_searches` — from 1 to 5, default 3.
- Billing: in standard mode, tokens only (search results count as input tokens); in agent mode, tokens for every step plus 1000 nGNK per search performed (`x_joingonka.web_search_surcharge_ngonka`).
- In Anthropic Messages and OpenAI Responses, the built-in `web_search` tool runs this same plugin in agent mode.

#### plugins: web

```json
{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "max_results": 5}]
}
```

#### mode: agent

```json
{
  "model": "MiniMaxAI/MiniMax-M2.7",
  "messages": [{"role": "user", "content": "What is new in the Gonka network?"}],
  "plugins": [{"id": "web", "mode": "agent", "max_searches": 3}]
}
```

## Cost and service fields

A non-streaming response carries the request cost in `usage`:

| Field | Description |
| --- | --- |
| `usage.cost_gnk` | Request cost in GNK |
| `usage.platform_fee_gnk` | Of which platform markup, GNK |
| `usage.total_cost_gnk` | Total to be charged in GNK |
| `usage.total_cost_usd` | Total in dollars at the current GNK rate |

- In a stream, `usage` contains tokens only; the cost is in the `joingonka-meta` chunk.
- With the `x-joingonka-meta: 1` header, the `POST /v1/chat/completions` response gets a `x_joingonka` block: cost (`cost_ngonka`), balance after charging (`balance_ngonka`, non-streaming only) and timings (`ttft_ms`). Other protocols don't return this block.
- `x-request-id` is the request ID: include it when contacting support.
- `Retry-After` comes with `429`: wait this many seconds before retrying.
- The `X-Title` and `HTTP-Referer` headers (like OpenRouter's) help the gateway identify your app; their contents are not stored.

## Limits

- Images: `image_url` parts are replaced with a text placeholder — the model cannot see the picture (`vision: false` in capabilities).
- From a browser, the API is accessible only from JoinGonka domains (`Origin` check): call it from your own server, never put the key in the frontend.
- Embeddings: `POST /v1/embeddings` returns `501` — there are no embedding models on the network.
- Error codes, limits and timeouts are in the [Errors & Rate Limits](https://gate.joingonka.ai/docs/errors) section.

---

Source: <https://gate.joingonka.ai/docs/models.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Models

Gonka network models available through the gateway: the ID for the `model` field, context window, output limit, price and status.

## Models and pricing

The model lineup changes through Gonka network votes, so the table is built from live gateway data. Prices are in dollars per 1M tokens at the current GNK rate; charges are in GNK — see the [Pricing & Account](https://gate.joingonka.ai/docs/billing) section for details.

| Model | Context | Output | Input, `$/1M` | Output, `$/1M` | Status |
| --- | ---: | ---: | ---: | ---: | --- |
| **MiniMax** `MiniMaxAI/MiniMax-M2.7` | 200K | 8K | $0.0083 | $0.025 | Degraded |
| **DeepSeek** `deepseek-ai/DeepSeek-V4-Flash-0731` | 380K | 33K | $0.0083 | $0.025 | Degraded |
| **Z.ai** `zai-org/GLM-5.3-Flash` | 390K | 8K | $0.0083 | $0.025 | Operational |

Paste the ID into the `model` field; letter case doesn't matter. Status is based on the share of successfully processed requests, as on the [Network status](https://gate.joingonka.ai/status) page.

## How to choose a model

- Not sure where to start? Go with `MiniMaxAI/MiniMax-M2.7`: the documentation examples and installer commands are built around it.
- The longest context — `zai-org/GLM-5.3-Flash`: 390K tokens. For large codebases and long documents.
- The longest output — `deepseek-ai/DeepSeek-V4-Flash-0731`: up to 33K tokens at a time. For generating large files in one go.

If the network stops serving a model, it disappears from `GET /v1/models`, and requests to it get a 503 response with the error type `model_unavailable`. The error text will name a model you can switch to.

## Output length

Output length is set by `max_tokens` — or `max_completion_tokens`, the gateway understands both fields. Each model has a cap: a larger `max_tokens` is silently trimmed to it. If `max_tokens` is not set, with `stream: true` the cap is used, and without streaming a smaller default applies.

Reasoning models spend part of `max_tokens` thinking before answering — leave some headroom.

| `model` | Cap | Default, `stream: true` | Default, no stream |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 8192 | 1500 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 32768 | 1500 |
| `zai-org/GLM-5.3-Flash` | 8192 | 8192 | 3000 |

The same numbers in machine-readable form are in the `GET /v1/capabilities` response, `limits.models` field.

## Default model

A request without the `model` field is sent by the gateway to the default model — currently `MiniMaxAI/MiniMax-M2.7`.

Claude Code and the Anthropic SDK send Anthropic model names (`claude-*`) in `/v1/messages` — the gateway replaces them with the same default model.

To work with another model, specify its ID from the table above; in the installer this is the `--model` flag.

## Lineup and status via API

The model lineup changes through Gonka network votes — don't hardcode the list, fetch it from the API. These requests don't need a key.

| Request | What it returns |
| --- | --- |
| `GET /v1/models` | Models available right now: ID, context, output limit and token price in dollars. A model the network isn't currently serving won't be in the list. |
| `GET /v1/models/{model}` | A single model in the same format. Pass the slash in the ID as is or as `%2F`. An unknown or hidden model returns `404` with code `model_not_found`, and a request to a hidden model gets `503 model_unavailable`. |
| `GET /v1/capabilities` | Gateway capabilities: protocols, request parameters and the `limits` field — key rate limit, timeouts and per-model `max_tokens` caps. |
| `GET /v1/network-status` | Per-model status and incidents — the same data as on the [Network status](https://gate.joingonka.ai/status) page. |
| `GET /health` | Whether the gateway itself is responding: `{"status":"ok"}`. This request doesn't check model health. |

---

Source: <https://gate.joingonka.ai/docs/errors.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Errors and limits

Rate limits, timeouts, and gateway error codes. For each response, we explain when it occurs and what to do: retry the request or fix it.

## Limits

The numbers come from the `limits` field of the `GET /v1/capabilities` response: values there are always current.

| Limit | Value | When exceeded |
| --- | --- | --- |
| Requests per minute per key | 120, window 60 s from the first request | `429 rate_limit_exceeded` and the `Retry-After` header; gateway 5xx failures don't consume quota |
| Concurrent account requests | capped | the excess waits in a queue; if it times out — `429 queue_timeout` |
| Request body size | 16 MiB | `413` |
| Output length | [by model — see the table below](https://gate.joingonka.ai/docs/errors#max-tokens) | above the model's cap — trimmed to the cap, no error |
| Child keys | up to 50 per managing key, up to 120 requests per minute each | to raise the caps — contact support |

### Output length by model

Without `max_tokens`, the gateway applies a default: without streaming — shorter, so the response fits within the timeouts; in a stream — the model's cap. `max_completion_tokens` is the same field.

| `model` | Cap | No stream | In a stream |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## Timeouts

| Stage | Value | What happens |
| --- | --- | --- |
| Waiting for a queue slot | 45 s | `429 queue_timeout` with the `Retry-After: 1` header |
| Start of network response, stream | 150 s | `504 upstream_timeout`; an estimate of the input tokens is charged |
| Start of network response, no stream | 150 s | `504 upstream_timeout`; an estimate of the input tokens is charged |
| Response generation | ≈ 300 s | the network cuts generation short: the response arrives with `finish_reason: length` — continue with the next request |
| Pause between stream chunks | 30 s | the stream closes: `finish_reason: stop` in the `joingonka-stream-stalled` chunk |
| Keepalive signal in the stream | 15 s | a `: keep-alive` comment — SSE clients skip it |
| Stream opening | 30 s | until this moment a failure comes as a response code, after — as the `joingonka-error` chunk |
| Early non-streaming response | 90 s | the gateway returns `200` and sends spaces every 15 s — the JSON stays valid; an error after that comes in the body with the `error` field, the status remains `200` |

> **What is charged on timeout**
>
> Once the network accepts a request, it cannot be cancelled. On `504 upstream_timeout`, the input token estimate is charged, but not the output; a retry is a new charge. A stream cut off before the final `usage` is billed the same way. For long responses, use `stream: true`.

## Error codes

The error body is an `error` object with `message, type, code, param`; not every error has all fields. Rely on the status and `type`, and check `code` for details: the `message` text may change. The Anthropic format is in the [Anthropic error format](https://gate.joingonka.ai/docs/errors#anthropic-errors) section.

```json
{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}
```

| Response | When | What to do |
| --- | --- | --- |
| 400 `invalid_request_error` | Invalid body: no `messages`, a message isn't an object, the body isn't JSON; unknown model — with `param`: `model` and a list of available models in the text | Fix the request based on the error text |
| 400 `invalid_request_error` `empty_content_after_normalization` | The message is empty after normalization — for example, it contained only an image | Add text to the message |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | The `web` and `privacy-sanitization` plugins in one request | Keep only one of them |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses: a reference to a stored response, conversation, or item; background mode; a built-in tool requirement | Send the full history in `input` |
| 400 `api_error` | The network rejected the parameters — for example, an `reasoning_effort` value outside its list | Fix the value based on the error text |
| 401 `authentication_error` | The key wasn't found, was revoked, or is in an unknown format | Check the key on the [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) page |
| 402 `insufficient_funds` | Insufficient balance to cover the request estimate; the remainder is in `balance_ngonka` | Top up your balance: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | A request without a key, not from the website (`is_demo: true`) | Pass an API key |
| 402 `child_key_limit_exceeded` | The key's spending limit has been exceeded — daily, monthly, or total; the remainders are in `daily_remaining, monthly_remaining, total_remaining` | Raise the key's limit on the [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) page or wait for the reset |
| 403 `forbidden` | A management key `gm-` in a model request; an API key on a dashboard-only route | For requests, use the `jg-` or `gc-` key; for account management, use the dashboard |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: the model isn't in the catalog or is temporarily hidden | Take an id from `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` and other state addresses, `/v1/responses/compact` | Keep the history on your side; for Codex CLI, set your own provider id |
| 404 `invalid_request_error` | Unknown path | Check the method, path, and base URL |
| 413 `invalid_request_error` | The request body exceeds the limit | Shorten the request |
| 415 `invalid_request_error` | The body isn't JSON according to the header: `Content-Type: application/json` is required | Send `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | The per-key requests-per-minute limit has been exceeded; the body contains `rate_limit` with `limit, remaining, reset` | Wait for the number of seconds in `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | The model is overloaded on the Gonka network | Retry after `Retry-After` or pick another model — [Models](https://gate.joingonka.ai/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | All network slots are taken: the queue is full or the wait timed out | Retry after `Retry-After` |
| 500 `server_error` | Internal gateway error | Retry later; if it keeps happening, contact support and include `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: there are no embedding models on the network | Use a different embedding service |
| 502 `api_error` `upstream_unauthorized` | The network provider rejected the gateway's credentials — your key is fine | Retry in a minute |
| 502 `api_error` | Gonka network error; `code` comes from the network if it sent one | Retry after a pause or pick another model |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | The model is currently unavailable according to network probes: a crash, startup, instability, or nobody is serving it; rejected immediately, without waiting | Pick another model — the error text will suggest which; the list is at [Models](https://gate.joingonka.ai/docs/models) |
| 503 `service_unavailable` | No available nodes | Retry later |
| 504 `timeout` `upstream_timeout` | The network accepted the request but didn't respond in time; the input token estimate has been charged | For long responses, use `stream: true`; a retry is a new charge |

## Errors in an open stream

Until the stream is open, a rejection comes as a regular response code — just like without streaming. Once it's open, the status is already `200`, and the error arrives like this:

- Chat Completions — a `joingonka-error` with a `error`, then a disconnect without `[DONE]`.
- Without streaming after an early response — status `200` and a body with a `error`.
- Anthropic Messages — an `event: error`, then the stream closes.
- OpenAI Responses — an `response.failed`, with the reason in `response.error.code`.
- Legacy Completions — `data: {"error": …}`, then `[DONE]`.

```text
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}
```

## Anthropic error format

- `POST /v1/messages` responds with the Anthropic envelope: `{"type": "error", "error": {"type", "message"}}`.
- Gateway rejections preserve the `type` from the table above (`insufficient_funds`, `model_unavailable`, and others); there's no `code` field in this envelope — the reason is in the text.
- Request shape errors — `invalid_request_error`: no messages or `max_tokens`, a tool call without a name, unknown model.
- Unknown path — `not_found_error`, body too large — `request_too_large`.

```text
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}
```

## What to retry

- After the pause from `Retry-After`: `429`
- With increasing pause — 1, 2, 4 s, and so on: `500`, `502`, `503 service_unavailable`, `504`
- With another model: `503 model_unavailable`
- Don't retry without changes — fix the request, key, or balance: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Every retry after `504` is a new input estimate charge; for long responses, enable `stream: true`.

If the error keeps happening, contact support and include the `x-request-id` from the response headers.

---

Source: <https://gate.joingonka.ai/docs/billing.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Pricing and account

Model prices, deposit and withdrawal fees, GNK rate. Account API by key: balance, spend by day and model, transaction history, and top-ups.

## Model prices

Prices already include the platform markup 10%. Live values are at `GET /api/pricing`, no key required.

| `model` | Input, $ per 1M tokens | Output, $ per 1M tokens | nGNK per token: input / output |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | $0.008349 | $0.02505 | 33 / 99 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | $0.008349 | $0.02505 | 33 / 99 |
| `zai-org/GLM-5.3-Flash` | $0.008349 | $0.02505 | 33 / 99 |

- Request cost = input tokens × input price + output tokens × output price. Model reasoning counts as output tokens.
- Charges are in GNK (1 GNK = 10⁹ `nGNK`); dollar prices use the GNK rate $0.253.
- Before the request, the gateway checks the balance against the cost estimate; if it's insufficient — `402 insufficient_funds`.
- After registration, 0.1 GNK is credited to your account — around 3M tokens at the input price.

## Fees

| Operation | Fee | Note |
| --- | --- | --- |
| Markup on model requests | 10% | Already included in the prices above. |
| GNK top-up | free | Transfer to the gateway address with your `memo`; credited automatically. |
| USDT top-up | 5% → 2.5% | Payment via OxaPay; the larger the amount, the lower the fee — [USDT fee tiers](https://gate.joingonka.ai/docs/billing#usdt-tiers). |
| WGNK top-up from Ethereum | 1% | Covers the Ethereum network gas when transferring to Gonka. |
| GNK withdrawal | 5% | Dashboard only, from 1 GNK. |
| GNK rate | $0.253 | Used to calculate top-ups and dollar prices; updates automatically. |

### USDT fee tiers

The rate depends on the top-up amount, threshold inclusive:

| Top-up amount | Fee |
| --- | ---: |
| from $0 | 5% |
| from $25 | 4.5% |
| from $50 | 4% |
| from $100 | 3.5% |
| from $250 | 3% |
| from $500 | 2.75% |
| from $1000 | 2.5% |

## Account API

Balance, spending, and top-ups are available with the same key as model requests (`Authorization: Bearer jg-…`). These requests don't consume tokens.

Errors: no key — `401 authentication_error`, invalid parameters — `400 validation_error`, dashboard route with an API key — `403 forbidden`.

### GET `/api/balance`

Current balance.

| Field | Description |
| --- | --- |
| `balance_ngonka` | Balance in nGNK — as a string to preserve precision |
| `balance_usd` | Balance in dollars at the current rate |
| `cost_per_token_ngonka` | Input token price of the recommended model with markup, nGNK |
| `tokens_remaining` | How many input tokens the balance will cover at this price — an estimate |

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage`

Usage by day: requests, tokens, cost.

- `period` — `day`, `week`, `month`, `quarter`; defaults to `month`.
- Or `from` and `to` in `YYYY-MM-DD`, both at once, up to 92 days inclusive — then the response includes `period: custom`.
- `tz` — offset in minutes, like `getTimezoneOffset()` in the browser: for UTC+3 it's `-180`. Without it — UTC.

The response is an array of days with fields `date, requests, tokens, costNgonka`. Detailed request records are kept for 90 days.

```bash
curl -s "https://gate.joingonka.ai/api/usage?period=week&tz=-180" \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

### GET `/api/usage/by-model`

Usage by model: totals in `models` and a "period × model" series in `series` — hours when `period=day`, otherwise days. Parameters are the same as for `/api/usage`.

### GET `/api/usage/by-key`

Usage by key — `keys`. Parameters are the same as for `/api/usage`.

### GET `/api/transactions`

Transaction history: top-ups, charges for requests, bonuses, withdrawals.

- `limit` — up to 200, defaults to 50; `offset` — offset.
- `type` — filter: `DEPOSIT_USDT`, `DEPOSIT_GNK`, `DEPOSIT_FIAT`, `INFERENCE`, `REFERRAL_REWARD`, `BONUS`, `WITHDRAWAL`.
- `from` and `to` — dates, end inclusive.

The response contains records with fields `id, type, amountNgonka, feeNgonka, description, createdAt` and the total count `total`. `INFERENCE` records older than 90 days are collapsed into one per day.

### GET `/api/deposits`

Top-ups only. Parameters `limit`, `offset`, `from`, and `to` are the same as for transaction history; the response includes `total`.

### POST `/api/deposit/gnk`

GNK top-up details: `address` and `memo`. Send GNK to this address with this `memo` — the credit is automatic.

### GET `/api/deposit/usdt/rate`

USDT top-up rate and fee: `gnk_usd_price`, `fee_percent`, `fee_tiers`.

### POST `/api/deposit/usdt`

USDT invoice: the body `{"amount": 25}` — the amount in dollars from 1 to 10000; the response contains `payment_url`. If USDT deposits are temporarily closed — `503`.

### GET `/api/pricing`

Prices and fees without a key: `models[]`, `deposit_usdt_fee_tiers`, the GNK rate, and the sign-up bonus.

### Dashboard only

Account management lives in the dashboard [gate.joingonka.ai/dashboard](https://gate.joingonka.ai/dashboard). These routes aren't meant for integrations; some of them respond to the API key with `403 forbidden`:

- API keys — [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys);
- GNK withdrawal — from 1 GNK;
- card top-ups and WGNK sender addresses;
- promo codes;
- the referral program and mailing settings.

---

Source: <https://gate.joingonka.ai/docs/agents.md>

> For AI agents: step-by-step setup guide — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), documentation index — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# For AI agents

How to hand off integration to an AI agent: a ready-made prompt for any tool. Below — machine-readable documentation addresses and a skill the agent installs with a single command.

## Prompt for the agent

Send this prompt to your AI agent. It will set up the tool following the instructions below and ask you for the key.

```text
Connect your tool to JoinGonka Gateway — the OpenAI- and Anthropic-compatible API of the Gonka network — following the instructions at https://gate.joingonka.ai/docs/agents.md. I'll provide the key myself: don't save it in repository files and don't modify global environment variables. At the end, verify the connection with a short request and report the result.
```

Below are the instructions themselves. The agent receives them as Markdown at [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Rules

- The API key is created by a human — in the dashboard at [gate.joingonka.ai](https://gate.joingonka.ai/keys). Don't register an account or create keys yourself: ask the user for a key.
- Keep the key in the `JOINGONKA_API_KEY` environment variable of your terminal session. Don't write it to files tracked by git, don't commit it, and don't print it in the report.
- Don't change the global `OPENAI_*` and `ANTHROPIC_*` variables — neither in the shell profile nor system-wide: other tools of the user read them. The key and URL are written to the tool's own config — that's what the installer does.

## Facts

- Base URL for OpenAI API clients: `https://gate.joingonka.ai/v1`
- Base URL for Anthropic API clients, without `/v1`: `https://gate.joingonka.ai`
- The key is passed in the `Authorization: Bearer jg-…` or `x-api-key: jg-…` header
- The key for model requests starts with `jg-`; the management key `gm-` doesn't grant access to models.
- Recommended model: `MiniMaxAI/MiniMax-M2.7`
- List of available models: `GET https://gate.joingonka.ai/v1/models`
- Per key — up to 120 requests per minute; over the limit you get a 429 response with the `Retry-After` header. Limits and timeouts are in the `GET /v1/capabilities` response, field `limits`.

## Configure

Find the user's tool in the table at the end of the section. If there's a `--tool` value, configure it with the installer; if not, do it manually using the guide.

### Via the installer

One command, no questions: the key comes from an environment variable, the model from a flag. The installer writes the tool's config, saves a copy of the previous one, and verifies the connection with a request to the gateway.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| Flag | What it does |
| --- | --- |
| `--tool <id>` | Which tool to configure — a value from the tools table. |
| `--model <id>` | Model ID: the recommended one is `MiniMaxAI/MiniMax-M2.7`, all available ones are in `GET /v1/models`. |
| `--non-interactive` | No questions: the key is taken from `JOINGONKA_API_KEY`. |
| `--scope local` | Config in the current project instead of the home directory. Claude Code only; the config file is added to `.gitignore`. |
| `--no-verify` | Don't verify the connection after writing the config. |

| Exit code | What it means |
| --- | --- |
| `0` | Done: the config is written and the test request succeeded. If verification failed due to the network or balance, the installer prints a warning but still exits with code 0 — let the user know. |
| `1` | Setup failed; the reason is in the output: for example, an unknown `--tool` value, `JOINGONKA_API_KEY` not set, or the key doesn't start with `jg-`. |
| `2` | The config is written but the test request failed: check the key and the model ID. |

If the tool was running, restart it: the config is read at startup.

### Manually

For a tool without an installer, open its guide (link in the table below) and set three values:

- base URL — `https://gate.joingonka.ai/v1` for OpenAI API clients or `https://gate.joingonka.ai` for Anthropic API clients;
- key — in the API key field in the tool's settings;
- model — `MiniMaxAI/MiniMax-M2.7` or another one from `GET /v1/models`.

### Tools and guides

| Tool | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/en/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/en/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/en/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/en/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/en/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/en/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/en/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/en/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/en/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/en/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/en/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/en/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/en/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/en/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/en/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/en/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/en/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/en/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/en/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/en/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/en/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/en/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/en/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/en/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/en/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/en/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/en/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/en/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/en/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/en/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/en/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/en/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/en/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/en/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/en/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/en/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/en/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/en/knowledge/mimo-code/) | `mimo-code` |

## Verify

Verify the key with a balance request: it doesn't spend tokens, and the key is taken from `JOINGONKA_API_KEY`:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

Verify the URL, key, and model with a short request to the model:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

A `200` response with the model's text means the connection works. The installer runs this check itself: after it, exit code 0 is enough.

## Troubleshoot

The error arrives in the `error` field of the response body — with the type and the reason text.

| Response | What to do |
| --- | --- |
| `401 authentication_error` | Key rejected. Check that it was copied in full and passed in `Authorization: Bearer` or `x-api-key`; a new key is created by the user. |
| `402 insufficient_funds` | No funds in the balance. Tell the user: the balance is topped up in the dashboard. |
| `402 child_key_limit_exceeded` | The child key's limit is exhausted. A different key or a higher limit is needed — the key owner decides that. |
| `403 forbidden` | This is the management key `gm-`: it doesn't grant access to models. You need a `jg-` key. |
| `400 invalid_request_error` | Bad request. If the model isn't found, the error text lists the available IDs — take one from there or from `GET /v1/models`. |
| `404 model_not_found` | That model isn't available right now — pick another one from `GET /v1/models`. |
| `429` | Too many requests or the network is busy. Wait as many seconds as the `Retry-After` header says and retry. |
| `503 model_unavailable` | The network isn't serving the model right now. Switch to the model from the error text or another one from `GET /v1/models`. |
| `504 upstream_timeout` | The network didn't start responding in time. Retry the request; for long responses, enable `stream: true`. |
| `502` | A gateway or network failure — nothing to do with the key. Retry later; network status is on the [Network status](https://gate.joingonka.ai/status) page. |

All response codes and limits are in the [Errors & Rate Limits](https://gate.joingonka.ai/docs/errors) section.

## Report

At the end, tell the user:

- which tool was configured and which config file was written (the installer prints the path, with a copy of the previous one next to it);
- the base URL and model ID;
- the check result: the response code and the model's reply — or why the check couldn't be performed;
- what the user still needs to do themselves: for example, restart the tool or top up their balance.

Do not include the key in the report.

## Machine-readable addresses

| Address | What's there |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Documentation index for language models. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | The entire documentation in a single file. |
| `/docs/<page>.md` | Markdown version of a documentation page: the same address with `.md` appended ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) or a page request with the `Accept: text/markdown` header. |
| `GET /v1/capabilities` | Gateway capabilities and limits — the `limits` field. |
| `GET /v1/models` | Models currently available. |
| `GET /api/pricing` | Per-model pricing per 1M tokens and fees. |
| `GET /v1/network-status` | Model status and incidents. |

## Agent skill

The instructions can be installed as a skill for your agent — then it's always at hand, no prompt needed:

```bash
npx skills add https://gate.joingonka.ai
```