Python SDK Quick Start

Get up and running with the official clore-ai Python SDK in under 5 minutes. By the end of this guide, you'll search the GPU marketplace, create an order, and manage it — all from Python and the terminal.

---

Step 1: Install the SDK

pip install clore-ai

Verify the installation:

clore --version

---

Step 2: Get Your API Key

1. Go to clore.ai and sign in

2. Navigate to your profile / API settings

3. Copy your API key

Set it up (choose one):

# Option A: Environment variable (recommended)
export CLORE_API_KEY=your_api_key_here

# Option B: CLI config (persistent)
clore config set api_key YOUR_API_KEY

---

Step 3: Your First Script

Create a file called my_first_gpu.py:

from clore_ai import CloreAI

# Initialize client (picks up CLORE_API_KEY from env)
client = CloreAI()

# 1. Browse the marketplace
print("🔍 Searching for RTX 4090 GPUs...")
servers = client.marketplace(gpu="RTX 4090", max_price_usd=1.0)

if not servers:
    print("No servers found matching criteria")
    exit()

# Sort by price
servers.sort(key=lambda s: s.price_usd or float("inf"))

print(f"Found {len(servers)} servers:\n")
for s in servers[:5]:
    print(f"  ID {s.id}: {s.gpu_count}x {s.gpu_model} — ${s.price_usd:.4f}/h — {s.location}")

# 2. Rent the cheapest one
best = servers[0]
print(f"\n🚀 Renting server {best.id}...")

order = client.create_order(
    server_id=best.id,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"},
)

print(f"✅ Order created!")
print(f"   Order ID: {order.id}")
print(f"   IP: {order.pub_cluster}")

# 3. Check your orders
print("\n📦 Your active orders:")
orders = client.my_orders()
for o in orders:
    print(f"  Order {o.id}: {o.type} — {o.status} @ {o.pub_cluster}")

# 4. Check wallet balance
print("\n💰 Wallet balances:")
wallets = client.wallets()
for w in wallets:
    print(f"  {w.name}: {w.balance:.8f}")

Run it:

python my_first_gpu.py

---

Step 4: Using the CLI

You can do the same operations from the terminal without writing any Python.

Search the marketplace

# Find RTX 4090 GPUs under $1/hour, sorted by price
clore search --gpu "RTX 4090" --max-price 1.0 --sort price --limit 10

Deploy a server

clore deploy 123 \
  --image cloreai/ubuntu22.04-cuda12 \
  --type on-demand \
  --currency bitcoin \
  --ssh-password MySecurePass123 \
  --port 22:tcp \
  --port 8888:http

List orders

clore orders

SSH into your instance

clore ssh 456

Cancel an order

clore cancel 456

Check balances

clore wallets

Spot market

# View spot offers for a server
clore spot 123

# Update your spot bid
clore spot-price 456 0.000003

---

Step 5: Async Operations

For advanced use cases (concurrent API calls, integration with async frameworks), use the AsyncCloreAI client:

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI() as client:
        # Search multiple GPU types concurrently
        rtx4090, a100, rtx3090 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="A100"),
            client.marketplace(gpu="RTX 3090"),
        )

        print(f"RTX 4090: {len(rtx4090)} servers")
        print(f"A100:     {len(a100)} servers")
        print(f"RTX 3090: {len(rtx3090)} servers")

        # Create an order
        if rtx4090:
            best = min(rtx4090, key=lambda s: s.price_usd or float("inf"))
            order = await client.create_order(
                server_id=best.id,
                image="cloreai/pytorch",
                type="spot",
                currency="bitcoin",
                spot_price=0.0001,
            )
            print(f"Created spot order {order.id}")

asyncio.run(main())

---

Troubleshooting

AuthError: API key required for this endpoint

Your API key isn't being found. Check:

# Is it set?
echo $CLORE_API_KEY

# Or check the config
clore config get api_key

Fix: set the key in your environment or pass it directly:

client = CloreAI(api_key="your_key_here")

RateLimitError: Rate limit exceeded

The SDK auto-retries with exponential backoff up to max_retries times. If you still hit this, you're making too many requests. The built-in rate limiter enforces 1 req/sec — avoid creating your own parallel loops that bypass it.

InvalidInputError when creating an order

Double-check:

• server_id exists and is available (check marketplace() first)

• image is a valid Docker image

• type is exactly "on-demand" or "spot"

• currency is a valid payment method (e.g. "bitcoin", "CLORE-Blockchain")

• For spot orders, spot_price must be set

Connection refused when using clore ssh

The server might still be starting up. Wait 30–60 seconds after order creation and try again. Check the order status:

clore orders

ModuleNotFoundError: No module named 'clore_ai'

Make sure you installed the SDK in the right Python environment:

pip install clore-ai

# Check it's installed
pip show clore-ai

---

What's Next?

• SDK API Reference — every method, parameter, and model

• Automation Recipes — auto-scaler, spot bidding bot, training pipeline

• CI/CD Integration — GitHub Actions, GitLab CI, Docker

• Automating GPU Rental — raw requests approach (for learning)

📚 See also: Clore.ai Python SDK — Automate Your GPU Workflows in 5 Minutes