Skip to content

Developer Quickstart

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

1. Define variables

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

export ACCOUNT_NAME=<your-desired-account-name>
export NODE_URL=http://195.242.13.239:8000
  • Replace <your-desired-account-name> with your chosen account name.
  • Replace NODE_URL with any random node from the list of current active participants, or keep the address of the genesis node (http://195.242.13.239:8000).

The following command returns a JSON array of participants currently active in the epoch, along with a cryptographic proof that can be used to independently verify the list of active nodes: 

curl http://195.242.13.239:8000/v1/epochs/current/participants

2. Create an account

To create and interact with your Gonka account, you need the inferenced CLI tool.
You can download the latest inferenced binary for your system here.

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 create-client $ACCOUNT_NAME \
  --node-address $NODE_URL

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

This command creates a new account, securely stores its keys in the ~/.inference directory, and returns your new account address:

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

3. Add Private Key to environment variables

If you'd like to perform the request in Python:

3.1. Export your private key (for demo/testing only).

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

This command outputs a plain-text private key.

3.2. Add it to environment variable GONKA_PRIVATE_KEY, or .env file.

export GONKA_PRIVATE_KEY=<your-private-key>

4. Inference using modified OpenAI SDK

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

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=NODE_URL
)

response = client.chat.completions.create(
    model="Qwen/QwQ-32B",
    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

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 } from 'gonka-openai';

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

const response = await client.chat.completions.create({
    model: "Qwen/QwQ-32B",
    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

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

import (
    "fmt"
    "os"

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

func main() {
    client, err := gonka.NewClient(gonka.Options{
        GonkaPrivateKey: os.Getenv("GONKA_PRIVATE_KEY"),
        SourceUrl: os.Getenv("NODE_URL")},
    })
    if err != nil {
        panic(err)
    }

    response, err := client.CreateChatCompletion(
        "Qwen/QwQ-32B",
        []gonka.ChatCompletionMessage{
            {
                Role:    "user",
                Content: "Write a haiku about programming",
            },
        },
    )
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Println(response.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.

Need help? Join our Discord server for assistance with general inquiries, technical issues, or security concerns.