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

Metadata

Release files for oro-sdk 1.0.124

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oro-sdk 1.0.124
File	Size	Uploaded
oro_sdk-1.0.124.tar.gz	173.3 kB	Sep 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for oro-sdk 1.0.124
File	Interpreter	ABI	Platform	Reset
oro_sdk-1.0.124-py3-none-any.whl 420.6 kB Sep 16, 2026	Python 3	none	any	Details

Total release size: 594.0 kB

Release files / oro_sdk-1.0.124.tar.gz

Download URL	oro_sdk-1.0.124.tar.gz
Size	173.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`d6e0684fe2a8103a824066562a18c7af6698061c16bf880087c19f0f3759d5cf`
BLAKE2b-256 checksum How to use checksums	`a85380f77beb647f4cddb493e945c5160b2564942c762d673109f2a7d391641a`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / oro_sdk-1.0.124-py3-none-any.whl

Download URL	oro_sdk-1.0.124-py3-none-any.whl
Size	420.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d55dd0208ed5f0da26bdcd224b5c83bab46f7c32a7e61f284dcfb9792da38661`
BLAKE2b-256 checksum How to use checksums	`6d84978e2d6615afe7ec9262e305048700ead77f49f9a47c213fb07511b1c91a`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`