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.

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.

1. Use a community broker (recommended)

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. New operators who want to serve inference independently should see Interested in operating a gateway?. 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:

Sign up on the broker's site (email, account, billing setup).
Generate an API key in the broker's dashboard.
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.

Chat interfacesAI IDEs and coding agentsNo-code automations

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.

PythonTypeScriptGo

Install the OpenAI Python SDK:

pip install openai

Create example.py:

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:

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:

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).

PythonTypeScript

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)

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 your application has high throughput or other requirements, you can run a Gonka gateway yourself instead of going through a broker. The gateway is a small program (shipped as a Docker container) that you run 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 you pay GNK directly on-chain for the devshards it creates.

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? below.

Full deployment instructions are in Run your own gateway.

3. Interested in operating a gateway?

Inference reaches the network through a gateway. There are two ways to have one, and they are governed differently.

Use a public gateway (current brokers). The brokers in §1.1 reach inference through a public Gonka gateway under access arrangements made during the early rollout. That was a bootstrap step, and the directory is not being actively expanded.

Run your own gateway. Operate your own on-chain devshard gateway. This requires your address on the governance-controlled allow-list (devshard_escrow_params.allowed_creator_addresses), and it is the recommended path for new operators. Full instructions are in the gateway guide.

To request consideration for on-chain allow-listing, open a GitHub issue including 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.