Skip to content

Developer Quickstart

This guide explains how to create a developer account in Gonka and submit an inference request using Gonka API.

Important for existing Leap Wallet users

If you previously created your Gonka account with Leap Wallet, please be aware that Leap is shutting down all of its products on May 28, 2026, including the browser extension, mobile app, and dashboard.

Because Leap is a non-custodial wallet, your assets and account remain on-chain. However, to keep access to your wallet, you should import your existing recovery phrase into another supported wallet, such as Keplr, before Leap services go offline.

How Gonka differs from traditional AI APIs

Gonka isn’t just another AI API — it’s a cryptographic protocol for provable inference. By eliminating centralized identity, Gonka removes the traditional single point of failure that plagues SaaS-based AI services. Here is a quick comparison table to help you understand the differences between a Traditional AI API and the Gonka API.

Aspect Traditional AI API
(OpenAI, Anthropic, etc.)		 Gonka API
Model provenance & verifiable output Models are hosted and versioned by the provider, but there’s no way to cryptographically verify which model actually produced a given output. There’s no proof that the model wasn’t switched, fine-tuned behind the scenes, or A/B tested on you. Every inference request and response can be cryptographically linked to a specific model hash and execution environment. This enables verifiable provenance — anyone can prove that a particular model version generated a specific output.
Censorship resistance All access is controlled centrally — providers can restrict or terminate accounts at any time. This includes enforcement of geographic, political, or commercial policies. Inference requests are signed and broadcast through a decentralized network. As long as you hold your private key and connect to a node, you can run inference. The system is designed to be uncensorable, unless restrictions are applied by a transparent, protocol-level consensus.
Auditability & transparency Logging, billing, and usage tracking are fully controlled by the API provider. Users cannot independently verify their own usage or inspect how pricing, latency, or errors were handled. Every interaction is signed and timestamped, enabling independent audit trails. You can prove when and how an inference occurred, which model was used, whether the results were altered, and ensure that disputes can be publicly resolved.
Transparent tokenomics Billing rates have limited insight into compute pricing, model costs, or system load. Tokenomics are on-chain or protocol-defined, meaning pricing mechanisms are transparent and inspectable. Users convert GNK into AI Tokens with predictable, traceable exchange logic, enabling clear forecasting of inference costs and supply-demand–driven economics.

0. Choose your access path

There are two ways to start using Gonka:

  • Crypto-native path — use your own Gonka account, private key, and GNK balance to send inference requests directly.

  • Broker path — use a third-party broker service to pay in USD and avoid managing wallets, private keys, or GNK directly.

Use this path if you want to interact with Gonka directly using your own wallet, private key, GNK balance, and SDK requests.

You will need to:

  1. Create or import a Gonka-compatible account
  2. Export or store the private key securely
  3. Fund the account with GNK
  4. Publish the public key on-chain
  5. Send inference requests through the SDK

Use this path if you want to pay in USD and avoid managing GNK, wallets, private keys, or on-chain transactions. Broker services handle GNK conversion and on-chain interaction internally.

Trade-offs

Broker services are not part of the core protocol.
They introduce an additional layer of trust and abstraction compared to direct interaction with the network.

If you use a broker service, follow the broker's own onboarding instructions. The rest of this guide is intended for users who want to interact with Gonka directly.

1. Define variables

Before creating an account, set up the required environment variables:

export ACCOUNT_NAME=<your-desired-account-name>
export NODE_URL=<http://random-node-url>
  • Replace <your-desired-account-name> with your chosen account name.
    • This name is not recorded on-chain — it exists only in your local key store.
    • Uniqueness is local: creating two keys with the same name will overwrite the existing one (with a CLI warning). If you proceed, the original key will be permanently lost. It is highly recommended to back up your public and private keys before performing this operation.
  • Replace <http://random-node-url> with a random Node URL. You can choose any node randomly — you do not need to consider which model it runs. At this point, the node is used purely as a gateway to fetch network state and broadcast transactions. You can either:
    • Use one of the genesis nodes from the list below.
    • Fetch the current list of active participants and select a random node. To avoid over-reliance on the genesis node and encourage decentralization, Gonka recommends selecting a random active node from the current epoch. This improves network load distribution and resilience to node outages.

Set the NODE_URL to one of the genesis nodes:

Genesis Node List
http://36.189.234.237:17241
http://node1.gonka.ai:8000
http://node2.gonka.ai:8000
http://47.236.26.199:8000
http://47.236.19.22:18000
http://gonka.spv.re:8000

Alternatively, you can select a random active participant from the current epoch. Open the link or run the following command to fetch the list of active participants along with a cryptographic proof for verification:

http://node1.gonka.ai:8000/v1/epochs/current/participants

curl http://node1.gonka.ai:8000/v1/epochs/current/participants

Save the selected NODE_URL; you will use it in the next steps.

2. Create an account

Download the inferenced CLI tool (the latest inferenced binary for your system is here).

What is the inferenced CLI tool?

The inferenced CLI tool is a command-line interface utility used to interact with the Gonka network. It is a standalone, executable binary that allows users to create and manage Gonka accounts, perform inference tasks, upload models, and automate various operations through scripted commands.

Enabling Execution on Mac OS

On Mac OS, after downloading the inferenced binary, you may need to enable execution permissions manually. Follow these steps:

  1. Open a terminal and navigate to the directory where the binary is located.

  2. Run the following command to grant execution permission: 

    chmod +x inferenced

  3. Try running ./inferenced --help to ensure it's working.

  4. If you see a security warning when trying to run inferenced, go to System Settings → Privacy & Security.

  5. Scroll down to the warning about inferenced and click "Allow Anyway".

You can create an account with the following command: 

./inferenced keys add "$ACCOUNT_NAME"

Make sure to securely save your passphrase — you'll need it for future access.

This command will:

  • Generate a keypair
  • Save it to ~/.inferenced
  • Return your account address, public key, and mnemonic phrase (store it securely in a hard copy as well!)
- address: <your-account-address>
  name: ACCOUNT_NAME
  pubkey: '{"@type":"...","key":"..."}'
  type: local

The account stores your balance, add it to environment variable GONKA_ADDRESS, or .env file.

export GONKA_ADDRESS=<your-account-address>

You will use this account to purchase Gonka (GNK) coins and pay for inference requests.

Add Private Key to environment variables.

If you'd like to perform the request, export your private key.

./inferenced keys export $ACCOUNT_NAME --unarmored-hex --unsafe

This command outputs a plain-text private key.

Go to the official Keplr website and click "Get Keplr wallet".

Choose an extension for your browser.

Add the selected extension to your browser.

Click "Create a new wallet".

Click "Connect with Google". Do not create the wallet in Keplr using a mnemonic phrase. Keplr will not allow you to export the private key later, and you will need that private key for the next steps.

Set up your wallet.

Back up your private key securely. Anyone with your private key can have access to your assets. If you lose access to your Gmail Account, the only way to recover your wallet is using your private key. Keep this in a safe place.

Type “Gonka” into the search bar and select Gonka chain to add it to your wallet.

Your Keplr wallet has been created.

Open Keplr, navigate, and click on “Copy Address” in your wallet.

Click the Copy button next to the Gonka chain.

You copied your Gonka account address. You can share it with anyone who will send you payments. Sharing it is safe.

Optional: How to add an additional Gonka account in Keplr wallet — click to view steps

Open the extension and click on the account icon in the top-right corner of the extension window.

Click the "Add wallet" button.

Click "Import an Existing Wallet".

Click "Use recovery phrase or private key"

Paste your private key. Do not import a mnemonic phrase. Keplr will not allow you to export the private key later, and you will need that private key for the next steps.

Give your wallet a name for easy reference.

Type “Gonka” into the search bar and select Gonka chain to add it to your wallet.

Done — your Gonka account has been successfully imported into Keplr!

Important Notice: Limited Functionality

This option creates an account using a mnemonic phrase and does not support transactions through the bridge. If you want to perform transactions via the bridge, please use Option 1: Via inferenced CLI tool or Option 2: Via Keplr (external wallet, "Connect with Google") instead.

Get Cosmostation Wallet browser extension.

Add an extension to your browser.

Choose "Create new wallet".

Write down your mnemonic phrase. DO NOT share your recovery phrase with ANYONE. Anyone with your recovery phrase can have full control over your assets. Please stay vigilant against phishing attacks at all times. Back up the phrase safely.

Complete the quiz in order. Check the backed-up mnemonic and select the correct phrase in order for each number.

Set account name. Please enter a name for your account. You can change the account name at any time.

In the top-right corner, click “All Networks” and select the Gonka chain to add it to your wallet.

Done! Your Gonka Developer account has been successfully created. Copy your Gonka account address. It starts with gonka... and is shown above your balance. You can safely share this address with anyone who needs to send you payments.

Click on the Wallet name at the top. Click "Manage" in the top-right corner, then click the Wallet name.

Click "View private key".

Verify your password.

Choose "Gonka" from the list.

Click on "Gonka" to see the private key. Copy your private key or recovery phrase and store it securely (a hard copy is preferred).

Add private key to the environment variable GONKA_PRIVATE_KEY or the .env file. 

export GONKA_PRIVATE_KEY=<your-private-key>
To retrieve a list of all locally stored accounts, execute the following command: 
./inferenced keys list [--keyring-backend test]

3. Fund your account with GNK

GNK is the native coin of the Gonka network. You’ll need it to pay for inference — every request you send to the network consumes a small amount of GNK.

At the moment, GNK is not officially listed on any exchanges.

You can obtain GNK through:

  • Running a host and earning rewards for contributing compute
  • Participating in the bounty program
  • Community-driven channels (peer-to-peer transfers within the ecosystem)
    • These interactions are not part of the protocol and rely on direct coordination between participants
    • Any purchase, swap, or transfer is performed at your own risk

Buying GNK

Direct purchase flows are still a work in progress. Follow updates in Discord for announcements. Any GNK listing you find on third-party websites or exchanges is not part of the Gonka protocol.

4. Activate the account for inference

Before inference, your account must have a balance and a published on-chain public key.

  • You do not need to register as a Participant to run inference.
  • Participant registration is required only for hosting.

Check balance: 

./inferenced query bank balances "$GONKA_ADDRESS" --node "$NODE_URL/chain-rpc/"

If your account was created with inferenced, publish the key: 

./inferenced publish-pubkey \
  --from "$ACCOUNT_NAME" \
  --node "$NODE_URL/chain-rpc/" \
  --chain-id "gonka-mainnet" \
  --yes

If your account was created in an external wallet, send any on-chain transaction (a self-transfer is enough) to publish the key.

Verify account data: 

curl -s "$NODE_URL/v2/accounts/$GONKA_ADDRESS" | jq .

5. Run inference using the Gonka OpenAI SDK

Public devshard creator node

Inference on Gonka is settled through a devshard-based billing flow. A public node creates a devshard escrow session for your account and routes your requests to executors inside that session. Only nodes whose addresses are in the on-chain allowlist devshard_escrow_params.allowed_creator_addresses are allowed to create those escrows.

As of the latest mainnet update, the recommended public inference gateway is https://node4.gonka.ai.

For SDK endpoint discovery, set SOURCE_URL to the public inference gateway: 

export SOURCE_URL=https://node4.gonka.ai

Optionally, you can inspect the on-chain allowlist of devshard creator addresses (use any NODE_URL from step 1 — node4 does not expose /chain-api): 

curl "$NODE_URL/chain-api/productscience/inference/inference/params" \
  | jq '.params.devshard_escrow_params.allowed_creator_addresses'

To use the Gonka API in Python, you can use the Gonka OpenAI SDK for Python. Get started by installing the SDK using pip:

pip install gonka-openai==0.2.6

If you encounter build errors, you may need to install system-level libraries

brew install pkg-config secp256k1

With the SDK installed, create a file called example.py and copy the example code into it:

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

client = GonkaOpenAI(
    gonka_private_key=os.environ.get('GONKA_PRIVATE_KEY'),
    source_url=os.environ.get('SOURCE_URL')
)

response = client.chat.completions.create(
    model="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    messages=[
        { "role": "user", "content": "Write a one-sentence bedtime story about a unicorn" }
    ]
)

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

Execute the code with python example.py. In a few moments, you should see the output of your API request.

To use the Gonka API in server-side JavaScript environments like Node.js, Deno, or Bun, you can use the Gonka OpenAI SDK for TypeScript and JavaScript. Get started by installing the SDK using npm or your preferred package manager:

npm install gonka-openai@0.2.6

With the SDK installed, create a file called example.mjs and copy the example code into it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { GonkaOpenAI, resolveEndpoints } from 'gonka-openai';

const endpoints = await resolveEndpoints({ sourceUrl: process.env.SOURCE_URL });
const client = new GonkaOpenAI({
    gonkaPrivateKey: process.env.GONKA_PRIVATE_KEY,
    endpoints
});

const response = await client.chat.completions.create({
    model: "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    messages: [
        { role: "user", content: "Hello! Tell me a short joke." }
    ]
});

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

Execute the code with node example.mjs. In a few moments, you should see the output of your API request.

To use the Gonka API in Go, you can use the Gonka OpenAI SDK for Go. Get started by installing the SDK using go get:

go get github.com/gonka-ai/gonka-openai/go@v0.2.6

With the SDK installed, create a file called example.go and copy the example code into it:

 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
package main

import (
    "context"
    "log"
    "os"

    gonka "github.com/gonka-ai/gonka-openai/go"
    "github.com/openai/openai-go"
)

func main() {
    client, err := gonka.NewGonkaOpenAI(gonka.Options{
        GonkaPrivateKey: os.Getenv("GONKA_PRIVATE_KEY"),
        SourceUrl:       os.Getenv("SOURCE_URL"),
    })
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("Write a haiku about programming"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Println(resp.Choices[0].Message.Content)
}

Execute the code with go run example.go. In a few moments, you should see the output of your API request.

To perform inference from another language, see the Gonka OpenAI client library repository, and adjust the examples accordingly.

6. Tool Calling

Only type: "function" is supported — vLLM implements the OpenAI chat completions spec, not the Assistants API (code_interpreter, file_search are unavailable).

Define functions, and the model will return structured call arguments when the user's request matches — you decide what to do with them.

 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, json
from gonka_openai import GonkaOpenAI

client = GonkaOpenAI(
    gonka_private_key=os.environ.get('GONKA_PRIVATE_KEY'),
    source_url=os.environ.get('SOURCE_URL')
)

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="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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)
    # model chose get_weather with {"city": "Paris"} — call your function now
    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
36
37
import { GonkaOpenAI, resolveEndpoints } from 'gonka-openai';

const endpoints = await resolveEndpoints({ sourceUrl: process.env.SOURCE_URL });
const client = new GonkaOpenAI({
    gonkaPrivateKey: process.env.GONKA_PRIVATE_KEY,
    endpoints
});

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: "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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);
    // model chose get_weather with { city: "Paris" } — call your function now
    console.log(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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
package main

import (
    "context"
    "encoding/json"
    "log"
    "os"

    gonka "github.com/gonka-ai/gonka-openai/go"
    "github.com/openai/openai-go"
)

func main() {
    client, err := gonka.NewGonkaOpenAI(gonka.Options{
        GonkaPrivateKey: os.Getenv("GONKA_PRIVATE_KEY"),
        SourceUrl:       os.Getenv("SOURCE_URL"),
    })
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
        Messages: []openai.ChatCompletionMessageParamUnion{
            openai.UserMessage("What's the weather in Paris?"),
        },
        Tools: []openai.ChatCompletionToolParam{
            {
                Type: "function",
                Function: openai.FunctionDefinitionParam{
                    Name:        "get_weather",
                    Description: openai.String("Get the current weather for a city"),
                    Parameters: openai.FunctionParameters{
                        "type": "object",
                        "properties": map[string]any{
                            "city": map[string]string{"type": "string", "description": "City name"},
                        },
                        "required": []string{"city"},
                    },
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if len(resp.Choices[0].Message.ToolCalls) > 0 {
        call := resp.Choices[0].Message.ToolCalls[0]
        var args struct{ City string }
        json.Unmarshal([]byte(call.Function.Arguments), &args)
        // model chose get_weather with {City: "Paris"} — call your function now
        log.Printf("Tool: %s, City: %s\n", call.Function.Name, args.City)
    }
}

Need help? Find answers on FAQ page, or join Discord server for assistance with general inquiries, technical issues, or security concerns.