SuperBrain SDK

Minimal Node client for the SuperBrain SN442 knowledge network on Bittensor.

Five functions: query, share, earnings, peers, generateSigningKey. No dependencies, just fetch + Node's built-in crypto for Ed25519. Works in Node 18+.

Install

Not yet on npm (coming at mainnet). Install directly from GitHub:

npm install github:KatchDaVizion/superbrain-sdk

Quick start

const sb = require('superbrain-sdk')

// List peers on the network (fast, always available)
const p = await sb.peers()
console.log(`${p.peers.length} peers online`)

// Check earnings for a hotkey
const e = await sb.earnings('5EHQh8frNHpjY5Cw7HuPiNgN4DotBYXWnHk2dvDFbQqJmUTavk')
console.log(`${e.chunks_contributed} chunks, ${e.total_retrievals} retrievals`)

// Share a chunk and earn retrievals on your hotkey
const r = await sb.share('My validated knowledge', {
  title: 'My note',
  hotkey: '5EHQh8frNHpjY5Cw7HuPiNgN4DotBYXWnHk2dvDFbQqJmUTavk',
})
console.log(r.chunk_id, r.sig_reason)  // chunk_id, 'legacy-unsigned'

// (optional) sign contributions with your Ed25519 identity for attribution-proof shares
const key = sb.generateSigningKey()  // { seedHex, publicKeyHex } — persist seedHex securely
const r2 = await sb.share('Signed knowledge', {
  title: 'My signed note',
  category: 'research',
  hotkey: '5EHQh8frNHpjY5Cw7HuPiNgN4DotBYXWnHk2dvDFbQqJmUTavk',
  signingKey: key.seedHex,
})
console.log(r2.sig_reason)  // 'verified'

// Ask the network a question (RAG pipeline — may take a few seconds)
const a = await sb.query('What is SuperBrain?')
console.log(a.answer)

API

query(question, options?)

Ask the SN442 network a question. Returns an answer with citations.

| Field | Type | Default | Description | |---|---|---|---| | question | string | required | Natural language question | | options.mode | string | 'auto' | 'auto', 'rag', or 'extractive' | | options.node | string | Frankfurt seed | Override base URL |

Returns { answer, citations, method, routed_to, routing_confidence, query_type, latency_ms, private, tier }.

share(content, options?)

File a knowledge chunk to SN442. Pass hotkey to attribute earnings.

| Field | Type | Default | Description | |---|---|---|---| | content | string | required | The text to share | | options.title | string | 'Untitled' | Chunk title | | options.source | string | 'superbrain-sdk' | Source label | | options.tags | string[] | [] | Topic tags | | options.license | string | 'unknown' | Content license | | options.submitter | string | 'sb-user' | Submitter handle | | options.hotkey | string | '' | Bittensor ss58 — earns retrievals |

Returns { chunk_id, status, ... }.

earnings(hotkey, options?)

Get retrieval-based earnings for a specific Bittensor hotkey.

Returns { hotkey, chunks_contributed, total_retrievals, estimated_tao, last_updated }.

peers(options?)

List registered peers on the SN442 network.

Returns Peer[] — each peer has { node_id, url, last_seen, chunks, role }.

Configuration

Custom seed node

Default: Frankfurt seed at http://46.225.114.202:8400. Override per-call:

await sb.query('What is SuperBrain?', { node: 'http://my-node.example.com:8400' })

Or set globally via env var:

export SB_NODE_URL=http://my-node.example.com:8400
node my-app.js

SUPERBRAIN_NODE is also accepted as a fallback for backwards compatibility. Precedence: per-call options.node → SB_NODE_URL → SUPERBRAIN_NODE → Frankfurt default.

Errors

All methods throw on network errors or non-2xx HTTP responses. The error message includes the method, URL, status code, and any detail field from the API.

try {
  await sb.query('hello')
} catch (e) {
  console.error(e.message)
  // SuperBrain SDK: POST http://.../query returned 500 — "internal error"
}

What this SDK is NOT

• Not a full Bittensor wallet client. Use btcli or bittensor Python package for staking, registration, and key management.
• Not a streaming client. All methods are request/response. Streaming chat is available through the SuperBrain desktop app or the sb CLI.
• Not yet published to npm — install from the GitHub URL above until mainnet launch.

License

MIT © KatchDaVizion