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 responsesync_detailed()- Blocking request returning full Response objectasyncio()- Async request returning parsed responseasyncio_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
Optional client metadata
Authenticated SDK helpers automatically send X-Oro-Client-Name and
X-Oro-Client-Version to identify the software package. Existing callers may
override these headers (including with an empty value); they are never required
for authentication or submission. No installation identifier is generated.
Clients that bypass these helpers remain supported without the headers.
1 maintainer
Metadata
1 maintainer
Release files for oro-sdk 4.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| oro_sdk-4.0.1.tar.gz | 178.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| oro_sdk-4.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 602.3 kB
Release files / oro_sdk-4.0.1.tar.gz
| Download URL | oro_sdk-4.0.1.tar.gz |
|---|---|
| Size | 178.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
787f16907743d64d699a79bf5bef59fc254284dccfa28a72169e08b21aabff86
|
|
BLAKE2b-256 checksum How to use checksums |
6f771c0f8a6ffaedef8db8195d8dbba7cdcb4c8e3685236cc714b9ce78a0939f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency logRelease files / oro_sdk-4.0.1-py3-none-any.whl
| Download URL | oro_sdk-4.0.1-py3-none-any.whl |
|---|---|
| Size | 423.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
09860d4df030f1324d888b06ad6f86406bc16a7eeaf5153251a325de27a0121d
|
|
BLAKE2b-256 checksum How to use checksums |
cb3872f722152a5aeab3be2254e6a43eafcb50ca960538523dd8b53e7c239f25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.
Transparency log
