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.

How developers connect to Gonka now

Gonka inference is now organised 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.

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 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.	Pricing and settlement are protocol-defined or on-chain, making inference economics more 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 method (USD, crypto, credits), rate limits, supported models, SLAs, refund policy, and data handling are decided 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 is not an endorsement of 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?.

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 Send your first request

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=Qwen/Qwen3-235B-A22B-Instruct-2507-FP8   # 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.4 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, not an open process, 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, 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.