ORO SDK for Python

Official Python SDK for the ORO Bittensor Subnet API.

This SDK is auto-generated from the OpenAPI specification using openapi-python-client.

Documentation

Full SDK documentation: docs.oroagents.com/docs/api/sdk

Installation

pip install oro-sdk

With Bittensor wallet support:

pip install "oro-sdk[bittensor]"

Or install from source:

pip install git+https://github.com/ORO-AI/oro-sdk.git#subdirectory=packages/python

Quick Start

Public API (No Auth Required)

from oro_sdk import Client
from oro_sdk.api.public import get_leaderboard, get_top_for_emissions

client = Client(base_url="https://api.oro.ai")

# Get leaderboard
leaderboard = get_leaderboard.sync(client=client)
if leaderboard:
    for entry in leaderboard.entries:
        print(f"{entry.rank}. {entry.miner_hotkey}: {entry.final_score}")

# Get top agent for emissions
top = get_top_for_emissions.sync(client=client)
if top:
    print(f"Top miner: {top.top_miner_hotkey} with score {top.top_score}")

Validator API (Requires Bittensor Wallet)

from bittensor_wallet import Wallet
from oro_sdk import BittensorAuthClient
from oro_sdk.api.validator import claim_work, heartbeat_evaluation_run, complete_evaluation_run
from oro_sdk.models import CompleteEvaluationRequest, CompleteEvaluationRequestTerminalStatus

wallet = Wallet(name="validator", hotkey="default")
client = BittensorAuthClient(base_url="https://api.oro.ai", wallet=wallet)

# Claim work
work = claim_work.sync(client=client)
if work:
    print(f"Claimed eval run: {work.eval_run_id}")

    # Send heartbeat
    heartbeat = heartbeat_evaluation_run.sync(
        eval_run_id=work.eval_run_id,
        client=client,
    )
    print(f"Lease extended to: {heartbeat.lease_expires_at}")

    # Complete run
    result = complete_evaluation_run.sync(
        eval_run_id=work.eval_run_id,
        client=client,
        body=CompleteEvaluationRequest(
            terminal_status=CompleteEvaluationRequestTerminalStatus.SUCCESS,
            validator_score=0.85,
        ),
    )
    print(f"Completed! Eligible: {result.agent_version_became_eligible}")
else:
    print("No work available")

Miner API (Requires Bittensor Wallet)

from bittensor_wallet import Wallet
from oro_sdk import BittensorAuthClient
from oro_sdk.api.miner import submit_agent, get_miner_agent_version_status

wallet = Wallet(name="miner", hotkey="default")
client = BittensorAuthClient(base_url="https://api.oro.ai", wallet=wallet)

# Submit an agent (multipart file upload)
with open("my_agent.py", "rb") as f:
    from oro_sdk.models import SubmitAgentBody
    from oro_sdk.types import File

    body = SubmitAgentBody(file=File(payload=f, file_name="my_agent.py"))
    response = submit_agent.sync(client=client, body=body)

if response.admission_status.value == "ACCEPTED":
    print(f"Submitted! Version ID: {response.agent_version_id}")

    # Check status
    status = get_miner_agent_version_status.sync(
        agent_version_id=response.agent_version_id,
        client=client,
    )
    print(f"State: {status.state}, Score: {status.final_score}")

Inference Auth (CLI)

Manage which inference provider funds your evaluations. Use the oro CLI shipped with this package:

# Connect a provider:
#   - OpenRouter: paste a Management API key
#   - Chutes: runs interactive OAuth (no API key to paste)
oro inference connect openrouter --api-key sk-or-v1-...
oro inference connect chutes

# List connected providers and the current default
oro inference status

# Pick the default for new evaluations (applies from the next claimed eval)
oro inference set-default openrouter

# Remove a stored credential
oro inference disconnect openrouter

All commands accept --wallet-name, --wallet-hotkey, and --base-url.

Async Support

All endpoints support async:

import asyncio
from oro_sdk import Client
from oro_sdk.api.public import get_leaderboard

async def main():
    client = Client(base_url="https://api.oro.ai")
    leaderboard = await get_leaderboard.asyncio(client=client)
    print(leaderboard)

asyncio.run(main())

API Structure

The SDK is organized by API tag:

oro_sdk.api.public - Public endpoints (no auth)
oro_sdk.api.validator - Validator endpoints (requires validator wallet)
oro_sdk.api.miner - Miner endpoints (requires miner wallet)
oro_sdk.api.admin - Admin endpoints (requires admin access)

Each endpoint module provides:

sync() - Blocking request returning parsed response
sync_detailed() - Blocking request returning full Response object
asyncio() - Async request returning parsed response
asyncio_detailed() - Async request returning full Response object

Models

All request/response models are in oro_sdk.models:

from oro_sdk.models import (
    ClaimWorkResponse,
    HeartbeatResponse,
    CompleteEvaluationRequest,
    CompleteEvaluationResponse,
    LeaderboardResponse,
    TopForEmissions,
    # ... etc
)

Development

Running Tests

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

Regenerating the SDK

When the API changes, regenerate the SDK:

pip install openapi-python-client
./scripts/generate-python.sh

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oro_sdk-1.0.116.tar.gz (158.2 kB view details)

Uploaded Sep 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

oro_sdk-1.0.116-py3-none-any.whl (381.9 kB view details)

Uploaded Sep 9, 2026 Python 3

File details

Details for the file oro_sdk-1.0.116.tar.gz.

File metadata

Download URL: oro_sdk-1.0.116.tar.gz
Upload date: Sep 9, 2026
Size: 158.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.16

File hashes

Hashes for oro_sdk-1.0.116.tar.gz
Algorithm	Hash digest
SHA256	`55721d37cebabf115c7e7c64cf09c1443df0e02e28dbe19d3bbdad5938fe307e`
MD5	`3394e4e60dc1c7fa31ef1d0fedf4b3f8`
BLAKE2b-256	`ecf0aa3682a8b9f8671b66d96df29e8ef977625ad9697e64627c6b5e98e4f02e`

See more details on using hashes here.

File details

Details for the file oro_sdk-1.0.116-py3-none-any.whl.

File metadata

Download URL: oro_sdk-1.0.116-py3-none-any.whl
Upload date: Sep 9, 2026
Size: 381.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.16

File hashes

Hashes for oro_sdk-1.0.116-py3-none-any.whl
Algorithm	Hash digest
SHA256	`26b66b049c8f1bbee6887e47e03f8afba1b2e23312bd0dd64fc77c0ee49dd731`
MD5	`f098ed05dc8f91bea67ce523875b1a93`
BLAKE2b-256	`232874bd1b83acf0a31f8a5aa9f113b078fb959bed2365330427e169aff5496b`