ORO SDK for TypeScript

Official TypeScript SDK for the ORO Bittensor Subnet API.

This SDK is auto-generated from the OpenAPI specification using @hey-api/openapi-ts.

Installation

npm install @oro-ai/sdk @hey-api/client-fetch

Quick Start

Public API (No Auth Required)

import { configurePublicClient, getLeaderboard, getTopAgent } from '@oro-ai/sdk';

// Configure the client
configurePublicClient('https://api.oro.ai');

// Get leaderboard
const { data: leaderboard } = await getLeaderboard();
leaderboard?.entries.forEach(entry => {
  console.log(`${entry.rank}. ${entry.miner_hotkey}: ${entry.final_score}`);
});

// Get top agent for emissions
const { data: top } = await getTopAgent();
if (top) {
  console.log(`Top miner: ${top.top_miner_hotkey} with score ${top.top_score}`);
}

Authenticated API (Validators/Miners)

Use configureBittensorAuth to automatically sign all requests:

import { configureBittensorAuth, claimWork, heartbeat, completeRun } from '@oro-ai/sdk';

// Configure with your wallet's signing function
configureBittensorAuth('https://api.oro.ai', {
  hotkey: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
  sign: (message) => {
    // Sign the message with your Bittensor wallet
    // Returns signature as hex string
    return wallet.sign(message);
  },
});

// All requests are now automatically authenticated!

// Validator: Claim work
const { data: work } = await claimWork();
if (work) {
  console.log(`Claimed eval run: ${work.eval_run_id}`);

  // Send heartbeat
  const { data: hb } = await heartbeat({ path: { eval_run_id: work.eval_run_id } });
  console.log(`Lease extended to: ${hb?.lease_expires_at}`);

  // Complete run
  const { data: result } = await completeRun({
    path: { eval_run_id: work.eval_run_id },
    body: {
      terminal_status: 'SUCCESS',
      validator_score: 0.85,
    },
  });
  console.log(`Completed! Eligible: ${result?.agent_version_became_eligible}`);
}

Miner API

import { configureBittensorAuth, submitAgent, getOwnedAgentVersionStatus } from '@oro-ai/sdk';

// Configure auth
configureBittensorAuth('https://api.oro.ai', {
  hotkey: minerHotkey,
  sign: (message) => minerWallet.sign(message),
});

// Submit an agent
const file = new File([agentCode], 'agent.py', { type: 'text/x-python' });
const { data: response } = await submitAgent({
  body: { file },
});

if (response?.admission_status === 'ACCEPTED') {
  console.log(`Submitted! Version ID: ${response.agent_version_id}`);

  // Check status
  const { data: status } = await getOwnedAgentVersionStatus({
    path: { agent_version_id: response.agent_version_id },
  });
  console.log(`State: ${status?.state}, Score: ${status?.final_score}`);
}

Auth Helpers

configureBittensorAuth(baseUrl, config)

Configures the client with automatic Bittensor authentication.

import { configureBittensorAuth } from '@oro-ai/sdk';

configureBittensorAuth('https://api.oro.ai', {
  hotkey: '5GrwvaEF...',      // Your SS58 hotkey address
  sign: async (message) => {   // Signs "nonce:timestamp" format
    return wallet.sign(message);
  },
});

configurePublicClient(baseUrl)

Configures the client for public (unauthenticated) endpoints only.

import { configurePublicClient } from '@oro-ai/sdk';

configurePublicClient('https://api.oro.ai');

generateAuthHeaders(config, nonce?)

Generates auth headers manually if needed.

import { generateAuthHeaders } from '@oro-ai/sdk';

const headers = await generateAuthHeaders({
  hotkey: '5GrwvaEF...',
  sign: (msg) => wallet.sign(msg),
});
// { 'X-Hotkey': '...', 'X-Signature': '...', 'X-Nonce': '...', 'X-Timestamp': '...' }

API Structure

All SDK functions follow the pattern:

const { data, error, response } = await functionName({ path?, query?, body? });

• data - Parsed response body (typed)
• error - Error object if request failed
• response - Raw fetch Response object

Development

Running Tests

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Regenerating the SDK

When the API changes:

cd packages/typescript
npm run generate

Or from the repo root:

./scripts/generate-typescript.sh

License

MIT