Skip to content

Developer Quickstart

This guide explains how to send an inference request to Gonka through a community broker. It is the fastest way to start using the network today. If you would like to run your own gateway instead of going through a broker, see Run your own gateway at the bottom of this page. Want to operate as a broker yourself? See Interested in operating a gateway? - start with OpenBroker, or use a GitHub allow-list issue as a fallback if OpenBroker does not satisfy your needs.

How to connect to Gonka

Gonka inference is now organized around devshards — short-lived sessions that hold a small on-chain deposit (an escrow) and settle per-request billing off-chain. The role of opening a devshard, signing requests, rotating the session, and submitting settlement to the chain is performed by a piece of software called a gateway.

For most developers, the simplest way to use Gonka is to call a community broker — a third party that provides inference access through a gateway and exposes a standard OpenAI-compatible API. You just need an API key from the broker.

How Gonka differs from traditional AI APIs

Gonka is not just another AI API. It is a cryptographic protocol for provable inference that aims to make model execution, billing, and settlement independently auditable, rather than fully controlled by a single provider.

Aspect Traditional AI API
(OpenAI, Anthropic, etc.)		 Gonka API
Model provenance and verifiable output Models are hosted and versioned by the provider, but users cannot independently verify which model produced a given output. Inference can be linked to protocol-defined model metadata and network execution records, enabling verifiable provenance.
Censorship resistance Access is controlled centrally by the provider. Access is moving into transparent, protocol-governed mechanisms. Current production access is guarded while protocol-level request validation is being completed.
Auditability and transparency Logging, billing, and usage tracking are controlled by the API provider. Requests, billing, and settlement are designed to be signed, timestamped, and auditable.
Transparent tokenomics Pricing and resource allocation are provider-defined. The network's per-inference price and settlement are protocol-defined and on-chain, making the underlying inference economics inspectable.

A broker is an independent operator who runs a Gonka gateway and resells inference to developers. From your application's point of view, a broker endpoint behaves like any OpenAI-compatible API: you set a base_url, pass an Authorization: Bearer <API_KEY> header, and call /v1/chat/completions as usual.

Brokers are not part of the core protocol

Brokers are independent third parties. Pricing, payment methods (USD, crypto, credits), rate limits, supported models, SLAs, refund policies, and data handling are determined by each broker. Read the broker's own documentation and terms before going live.

1.1 Pick a broker

About this list

This is a curated directory of community brokers that route inference through a public Gonka gateway and have agreed to be publicly listed. It is not exhaustive and does not endorse any operator. The list is displayed in a random order that is re-shuffled on every page load, so the position of each broker is not a ranking; please evaluate each operator on its own merits. This directory reflects an early bootstrap set. Want to become a broker yourself? Use OpenBroker (see §3), or open a GitHub allow-list issue as a fallback if OpenBroker does not satisfy your needs. Some brokers provide a ▶ demo link to a short onboarding screencast - style and length may vary.

Compare brokers — community observability dashboards

Community members run independent monitoring probes against public broker endpoints and publish the results. These dashboards can help you compare uptime, latency, and pricing before choosing a broker:

These dashboards are community-built tools, not part of the core protocol. Data accuracy, methodology, and availability are the responsibility of each dashboard operator. Always verify critical metrics against your own testing. The list is displayed in a random order on every page load.

1.2 Get an API key

Follow the onboarding instructions on the broker's site. Typically, you will:

  1. Sign up on the broker's site (email, account, billing setup).
  2. Generate an API key in the broker's dashboard.
  3. Note the broker's base_url (for example https://api.<broker-domain>/v1) and the list of supported models.

1.3 Connect a no-code app or AI coding assistant

Plug your API key into almost any AI software, chat interface, or agent framework that supports OpenAI-compatible providers.

You need three things from your broker (see §1.2): the Base URL, your API key, and a Model ID.

In most apps the mapping is:

Field in your app What to enter
API Base URL / Endpoint Your broker URL with /v1 appended, e.g. https://<broker-url>/v1. If the app asks for an "OpenAI Base URL" or "Custom Endpoint", this is it.
API Key / Auth Token The key you generated. Even if the app says "Enter OpenAI API Key", use your broker key here.
Model / Custom Model The exact Model ID your broker supports. Model IDs are case-sensitive — copy them exactly, e.g. MiniMaxAI/MiniMax-M2.7.

The exact menu names below may differ between app versions — look for the equivalent settings.

Examples: Open WebUI, LibreChat, LobeChat.

Go to Settings → AI Providers / Connections, choose the OpenAI provider, replace the default OpenAI URL with your broker URL plus /v1, insert your key, and add the Model ID to the allowed models list.

Examples: Cursor, Cline, Windsurf.

Go to Settings → Models, enable the OpenAI-compatible provider (or Add Custom Model), override the Base URL with your broker URL plus /v1, and paste your broker API key.

Examples: Make.com, n8n, Flowise.

Use the standard OpenAI module, then look for advanced settings to override the Base Path / Base URL with your broker's URL.

Prefer to write code instead? Continue to §1.4 Send your first request on Gonka.

1.4 Send your first request on Gonka

Set environment variables:

export GONKA_BROKER_URL=<broker-base-url>     # e.g. https://api.example-broker.com/v1
export GONKA_BROKER_API_KEY=<your-api-key>
export GONKA_MODEL=MiniMaxAI/MiniMax-M2.7   # or any model your broker supports

The Gonka broker endpoint is OpenAI-compatible, so you can use the official OpenAI SDK directly — no Gonka-specific client is required.

Install the OpenAI Python SDK:

pip install openai

Create example.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["GONKA_BROKER_URL"],
    api_key=os.environ["GONKA_BROKER_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["GONKA_MODEL"],
    messages=[
        {"role": "user", "content": "Write a one-sentence bedtime story about a unicorn"}
    ],
)

print(response.choices[0].message.content)

Run with python example.py.

Install the OpenAI JS SDK:

npm install openai

Create example.mjs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: process.env.GONKA_BROKER_URL,
    apiKey: process.env.GONKA_BROKER_API_KEY,
});

const response = await client.chat.completions.create({
    model: process.env.GONKA_MODEL,
    messages: [{ role: "user", content: "Hello! Tell me a short joke." }],
});

console.log(response.choices[0].message.content);

Run with node example.mjs.

Use the official openai-go client:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package main

import (
    "context"
    "log"
    "os"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
)

func main() {
    client := openai.NewClient(
        option.WithBaseURL(os.Getenv("GONKA_BROKER_URL")),
        option.WithAPIKey(os.Getenv("GONKA_BROKER_API_KEY")),
    )

    r, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: os.Getenv("GONKA_MODEL"),
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Write a haiku about programming"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Println(r.Choices[0].Message.Content)
}

In a few moments, you should see the inference response in your terminal.

1.5 Tool calling

Tool calling is supported through the same OpenAI-compatible endpoint. Only type: "function" is supported — Gonka uses vLLM under the hood, which implements the OpenAI chat completions spec, not the Assistants API (code_interpreter, file_search are unavailable).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import os
import json
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["GONKA_BROKER_URL"],
    api_key=os.environ["GONKA_BROKER_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"}
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model=os.environ["GONKA_MODEL"],
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    call = message.tool_calls[0]
    args = json.loads(call.function.arguments)
    print(call.function.name, args)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: process.env.GONKA_BROKER_URL,
    apiKey: process.env.GONKA_BROKER_API_KEY,
});

const tools = [
    {
        type: "function",
        function: {
            name: "get_weather",
            description: "Get the current weather for a city",
            parameters: {
                type: "object",
                properties: { city: { type: "string", description: "City name" } },
                required: ["city"],
            },
        },
    },
];

const response = await client.chat.completions.create({
    model: process.env.GONKA_MODEL,
    messages: [{ role: "user", content: "What's the weather in Paris?" }],
    tools,
    tool_choice: "auto",
});

const message = response.choices[0].message;
if (message.tool_calls) {
    const call = message.tool_calls[0];
    const args = JSON.parse(call.function.arguments);
    console.log(call.function.name, args);
}

2. Run your own gateway (advanced)

If you need to operate an on-chain Gonka gateway yourself (your own allow-listed wallet, your own escrows, direct GNK settlement), you can run the gateway software on your own machine or server - never on a Gonka host. It exposes the same OpenAI-compatible API as a broker, but you own the keys and pay GNK directly on-chain for the devshards it creates.

Most operators should become a broker via OpenBroker instead

OpenBroker is not “just another broker in the directory.” It is infrastructure created and operated by trusted community members that lets you become a broker - create a broker account, fund GNK, issue API keys, and serve inference - without an on-chain allow-listed creator address and without running your own gateway.

Prefer §3 (OpenBroker) unless you specifically need a self-hosted, allow-listed gateway.

Self-hosted gateway requires an allow-listed address

Today, only Gonka accounts on the on-chain devshard_escrow_params.allowed_creator_addresses list can open devshards. If your address is not on that list, your gateway cannot create sessions, and you cannot send inference. The allow-list is changed only by on-chain governance vote. See Interested in operating a gateway? - start with OpenBroker, or use a GitHub allow-list issue as a fallback if OpenBroker does not satisfy your needs.

Full deployment instructions are in Run your own gateway.

3. Interested in operating a gateway?

Inference reaches the network through a gateway. If you want to become a broker / operate inference access for yourself or your users, choose the path below.

OpenBroker (openbroker.gonka.gg) is the recommended way to become a broker.

It is a broker control plane created and operated by trusted community members: you register a broker account, deposit GNK, mint API keys, and serve an OpenAI-compatible endpoint. OpenBroker runs the allow-listed escrow wallet and devshard lifecycle for you - you do not need your address on allowed_creator_addresses.

Advanced - run your own on-chain gateway

Operate your own gonka-mainnet gateway only if OpenBroker cannot meet your requirements (for example you must hold the escrow keys yourself, or you need a custom on-chain setup). This requires your address on the governance-controlled allow-list (devshard_escrow_params.allowed_creator_addresses). Full instructions are in the gateway guide.

Fallback - GitHub allow-list request

If OpenBroker does not satisfy your needs and you still require your own allow-listed creator address for a self-hosted gateway, open a GitHub issue as a fallback.

Include your operator name and contact, the gonka1... address you intend to use, and the models you plan to serve. Inclusion is an on-chain governance decision - no single operator or organization adds an address unilaterally - and expressing interest does not guarantee inclusion, review, or a timeline.

Need help? See the FAQ page, or join the Discord server for technical issues or security concerns.