# 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

```bash
pip install clore-ai
```

Verify the installation:

```bash
clore --version
```

***

## Step 2: Get Your API Key

1. Go to [clore.ai](https://clore.ai) and sign in
2. Navigate to your profile / API settings
3. Copy your API key

Set it up (choose one):

```bash
# 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`:

```python
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:

```bash
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

```bash
# 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

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

### List orders

```bash
clore orders
```

### SSH into your instance

```bash
clore ssh 456
```

### Cancel an order

```bash
clore cancel 456
```

### Check balances

```bash
clore wallets
```

### Spot market

```bash
# 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:

```python
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:

```bash
# 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:

```python
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:

```bash
clore orders
```

### `ModuleNotFoundError: No module named 'clore_ai'`

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

```bash
pip install clore-ai

# Check it's installed
pip show clore-ai
```

***

## What's Next?

* [**SDK API Reference**](/reference/python-sdk.md) — every method, parameter, and model
* [**Automation Recipes**](/advanced-use-cases/sdk-automation-recipes.md) — auto-scaler, spot bidding bot, training pipeline
* [**CI/CD Integration**](/devops-and-automation/cicd-clore-sdk.md) — GitHub Actions, GitLab CI, Docker
* [**Automating GPU Rental**](/getting-started/automation-basics.md) — raw `requests` approach (for learning)

> 📚 See also: [Clore.ai Python SDK — Automate Your GPU Workflows in 5 Minutes](https://blog.clore.ai/cloreai-python-sdk-automate-your-gpu-workflows-in-5-minutes/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.clore.ai/getting-started/python-sdk-quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.