# gonka RPC

> gonka RPC (rpc.gonka.gg) is a managed API gateway for the Gonka blockchain (Cosmos SDK). It provides authenticated access to CometBFT RPC, Cosmos REST, custom Gonka chain modules, an AI inference API, and fast ClickHouse-indexed chain data — all through a single base URL.

## Quick start

Base URL: https://rpc.gonka.gg

Authentication: every request requires an API key, sent as either:
- Header: `X-Api-Key: YOUR_KEY`
- Bearer: `Authorization: Bearer YOUR_KEY`

Get a free key at https://rpc.gonka.gg/access

## Routing

Path prefixes determine which upstream service handles the request:

- `/chain-rpc/*` — CometBFT JSON-RPC (blocks, validators, consensus, tx broadcast)
- `/chain-api/*` — Cosmos REST / LCD (bank, staking, gov, auth, IBC, CosmWasm, Gonka modules)
- `/v1/*` — Gonka API node (models, participants, inference, training, epochs)
- `/api/ch/*` — Fast indexed data from ClickHouse (tx lookup, address history, slashing, hardware, epochs)
- `/comet/*` — Direct CometBFT passthrough
- `/v1/analytics/*` — Feather analytics (indexed tx search, block events, stats)

## Key examples

Get node status:
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/chain-rpc/status
```

Get latest block:
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/chain-rpc/block
```

Get account balance:
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/chain-api/cosmos/bank/v1beta1/balances/{address}
```

Get all validators:
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/chain-api/cosmos/staking/v1beta1/validators
```

Get available AI models:
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/v1/models
```

Transaction by hash (indexed, fast):
```
curl -H 'X-Api-Key: YOUR_KEY' https://rpc.gonka.gg/api/ch/tx/{64_hex_chars}
```

Address history (indexed, fast):
```
curl -H 'X-Api-Key: YOUR_KEY' 'https://rpc.gonka.gg/api/ch/address/{address}?limit=50'
```

Submit inference (OpenAI-compatible):
```
curl -X POST -H 'X-Api-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  https://rpc.gonka.gg/v1/chat/completions \
  -d '{"model":"model_id","messages":[{"role":"user","content":"Hello"}]}'
```

Broadcast transaction (Cosmos REST):
```
curl -X POST -H 'X-Api-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  https://rpc.gonka.gg/chain-api/cosmos/tx/v1beta1/txs \
  -d '{"tx_bytes":"...","mode":"BROADCAST_MODE_SYNC"}'
```

## Caching

Immutable data (historical blocks, finalized txs) is cached 24 hours. Live state refreshes 1-3 seconds. Module-specific caching: bank 3s, staking 15s, gov 30s, others 5-10s.

## Rate limits

Free: 10 rps / 10,000 daily. Pro: 50 rps / 500,000 daily. Business: 200 rps / unlimited.

## Full reference

- Complete endpoint list with parameters: [/llms-full.txt](https://rpc.gonka.gg/llms-full.txt)
- Structured JSON endpoint catalog: [/api/endpoints](https://rpc.gonka.gg/api/endpoints)
- Interactive documentation: [/endpoints](https://rpc.gonka.gg/endpoints)

## Gonka blockchain overview

Gonka is a Cosmos SDK blockchain focused on decentralized AI inference. Key concepts:
- **Participants**: Nodes that provide GPU compute for inference
- **Epochs**: Fixed-length periods for reward distribution (~15,391 blocks)
- **Proof of Computation (PoC)**: Mechanism to verify inference was correctly performed
- **Models**: AI models registered on-chain with per-token pricing
- **Collateral**: Staking requirement for participants
- **BLS**: Threshold signature scheme for distributed key generation
- **Bridge**: Cross-chain token bridging
- **Training**: Distributed model training tasks

## Contact

- Website: https://gonka.gg
- Email: info@gonka.gg
- Documentation: https://rpc.gonka.gg/endpoints