Python SDK (clore-ai)

Complete API reference for the official clore-ai Python SDK — the recommended way to interact with the Clore.ai GPU marketplace from Python and the command line.

---

Installation

pip install clore-ai

Requirements: Python 3.9+

📚 New to the SDK? Read Clore.ai Python SDK — Automate Your GPU Workflows in 5 Minutes for a hands-on tutorial.

From source:

git clone https://gitlab.com/cloreai/clore-ai-sdk.git
cd clore-ai
pip install -e .

---

Authentication

The SDK resolves your API key in this order:

1. Constructor argument — CloreAI(api_key="...")

2. Environment variable — CLORE_API_KEY

3. Config file — ~/.clore/config.json (set via clore config set api_key YOUR_KEY)

Get your key from clore.ai.

---

CloreAI — Synchronous Client

Constructor

from clore_ai import CloreAI

client = CloreAI(
    api_key: str | None = None,       # API key (falls back to env/config)
    base_url: str | None = None,       # Default: "https://api.clore.ai/v1"
    timeout: float = 30.0,             # HTTP timeout in seconds
    max_retries: int = 3,              # Retry attempts on rate-limit / network errors
)

Parameter	Type	Default	Description
api_key	str | None	None	Clore.ai API key. If omitted, reads CLORE_API_KEY env var or ~/.clore/config.json
base_url	str | None	https://api.clore.ai/v1	API base URL
timeout	float	30.0	Request timeout (seconds)
max_retries	int	3	Max retries on transient / rate-limit errors

Context manager support:

with CloreAI(api_key="...") as client:
    servers = client.marketplace()
# client.close() called automatically

---

wallets()

Get all wallet balances for the authenticated account.

wallets: List[Wallet] = client.wallets()

Returns: List[Wallet]

Raises: AuthError if no API key is set.

Example:

from clore_ai import CloreAI

client = CloreAI()
wallets = client.wallets()
for w in wallets:
    print(f"{w.name}: {w.balance:.8f} (deposit: {w.deposit})")

---

marketplace()

Browse available GPU servers. This is a public endpoint — no API key required.

servers: List[MarketplaceServer] = client.marketplace(
    gpu: str | None = None,
    min_gpu_count: int | None = None,
    min_ram_gb: float | None = None,
    max_price_usd: float | None = None,
    available_only: bool = True,
)

Parameter	Type	Default	Description
gpu	str | None	None	Filter by GPU model substring (case-insensitive), e.g. "RTX 4090"
min_gpu_count	int | None	None	Minimum number of GPUs per server
min_ram_gb	float | None	None	Minimum RAM in GB
max_price_usd	float | None	None	Maximum price per hour in USD
available_only	bool	True	Only return servers not currently rented

Returns: List[MarketplaceServer]

Note: Filtering happens client-side. The API returns all servers; the SDK filters the results based on your criteria.

Example:

# Find cheap RTX 4090 servers
servers = client.marketplace(gpu="RTX 4090", max_price_usd=0.50)
servers.sort(key=lambda s: s.price_usd or float("inf"))

for s in servers[:5]:
    print(f"Server {s.id}: {s.gpu_count}x {s.gpu_model} — ${s.price_usd:.4f}/h")

---

my_servers()

List servers you host on the Clore.ai marketplace.

servers: List[MyServer] = client.my_servers()

Returns: List[MyServer]

Note: my_servers() returns MyServer objects, not MarketplaceServer. MyServer has a .status property that returns "Online", "Offline", "Disconnected", or "Not Working".

Raises: AuthError if no API key is set.

Example:

my_servers = client.my_servers()
for s in my_servers:
    print(f"Server {s.id} ({s.gpu_model}): {s.status}")

---

server_config()

Get the configuration for one of your hosted servers.

config: ServerConfig = client.server_config(server_name: str)

Parameter	Type	Description
server_name	str	Name of your server

Returns: ServerConfig

Example:

cfg = client.server_config("MyGPU")
print(f"Available: {cfg.availability}")
print(f"Min rental: {cfg.mrl}h")
print(f"On-demand: {cfg.on_demand_price}")
print(f"Spot: {cfg.spot_price}")

---

my_orders()

List your rental orders.

orders: List[Order] = client.my_orders(include_completed: bool = False)

Parameter	Type	Default	Description
include_completed	bool	False	Also return completed/cancelled orders

Returns: List[Order]

Example:

orders = client.my_orders()
for o in orders:
    print(f"Order {o.id}: {o.type} — {o.status} @ {o.pub_cluster}")

---

create_order()

Create a new GPU rental order.

order: Order = client.create_order(
    server_id: int,
    image: str,
    type: Literal["on-demand", "spot"],
    currency: str,
    ssh_password: str | None = None,
    ssh_key: str | None = None,
    ports: Dict[str, str] | None = None,
    env: Dict[str, str] | None = None,
    jupyter_token: str | None = None,
    command: str | None = None,
    spot_price: float | None = None,
    required_price: float | None = None,
    autossh_entrypoint: str | None = None,
)

Parameter	Type	Description
server_id	int	Server ID from marketplace
image	str	Docker image, e.g. "cloreai/ubuntu22.04-cuda12"
type	"on-demand" | "spot"	Order type
currency	str	Payment currency: "bitcoin", "CLORE-Blockchain", etc.
ssh_password	str | None	SSH password for the instance
ssh_key	str | None	SSH public key (mutually exclusive with ssh_password)
ports	Dict[str, str] | None	Port mappings, e.g. {"22": "tcp", "8888": "http"}
env	Dict[str, str] | None	Environment variables
jupyter_token	str | None	Jupyter access token
command	str | None	Custom startup command
spot_price	float | None	Bid price for spot orders
required_price	float | None	Required price
autossh_entrypoint	str | None	Auto SSH entrypoint

Returns: Order

Raises: AuthError, InvalidInputError, RateLimitError

Rate limit: create_order has a special 5-second cooldown between calls, enforced by the built-in rate limiter.

Example:

order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"},
    env={"NVIDIA_VISIBLE_DEVICES": "all"},
)
print(f"Order {order.id} created @ {order.pub_cluster}")

---

cancel_order()

Cancel an active order.

result: Dict[str, Any] = client.cancel_order(
    order_id: int,
    issue: str | None = None,
)

Parameter	Type	Description
order_id	int	Order ID to cancel
issue	str | None	Optional cancellation reason

Returns: Dict[str, Any] — API response

Example:

client.cancel_order(order_id=38, issue="Job complete")

---

spot_marketplace()

Get spot market data for a specific server.

market: SpotMarket = client.spot_marketplace(server_id: int)

Parameter	Type	Description
server_id	int	Server ID

Returns: SpotMarket — object with offers (list of SpotOffer), server info, and currency_rates_in_usd

Example:

market = client.spot_marketplace(server_id=6)
if market.offers:
    for offer in market.offers:
        print(f"Order {offer.order_id}: price={offer.price}")
if market.currency_rates_in_usd:
    print(f"Currency rates: {market.currency_rates_in_usd}")

---

set_spot_price()

Update the spot price for one of your orders.

result: Dict[str, Any] = client.set_spot_price(
    order_id: int,
    price: float,
)

Parameter	Type	Description
order_id	int	Active order ID
price	float	New spot bid price

Returns: Dict[str, Any]

Example:

client.set_spot_price(order_id=39, price=0.000003)

---

set_server_settings()

Update settings for one of your hosted servers.

result: Dict[str, Any] = client.set_server_settings(
    name: str,
    availability: bool | None = None,
    mrl: int | None = None,
    on_demand: float | None = None,
    spot: float | None = None,
)

Parameter	Type	Description
name	str	Server name
availability	bool | None	Toggle availability on/off
mrl	int | None	Minimum rental length in hours
on_demand	float | None	On-demand price
spot	float | None	Spot price

Returns: Dict[str, Any]

Example:

client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113,
)

---

close()

Close the underlying HTTP client. Called automatically when using the context manager.

client.close()

---

AsyncCloreAI — Asynchronous Client

The async client mirrors every method of CloreAI but returns coroutines. It uses httpx.AsyncClient under the hood.

Constructor

from clore_ai import AsyncCloreAI

client = AsyncCloreAI(
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
)

Parameters are identical to CloreAI.

Context Manager (recommended)

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="...") as client:
        servers = await client.marketplace(gpu="RTX 4090")
        print(f"Found {len(servers)} servers")

asyncio.run(main())

Methods

All methods have the same signatures as the sync client. Prefix calls with await:

wallets = await client.wallets()
servers = await client.marketplace(gpu="A100", max_price_usd=2.0)
my_servers = await client.my_servers()
config = await client.server_config("MyGPU")
orders = await client.my_orders(include_completed=True)
order = await client.create_order(server_id=123, image="...", type="on-demand", currency="bitcoin")
await client.cancel_order(order_id=38)
market = await client.spot_marketplace(server_id=6)
await client.set_spot_price(order_id=39, price=0.000003)
await client.set_server_settings(name="MyGPU", availability=True)
await client.close()

Concurrent Operations

The main advantage of the async client is running multiple API calls in parallel:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        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)} | A100: {len(a100)} | RTX 3090: {len(rtx3090)}")

asyncio.run(compare_gpus())

---

Models

All models are Pydantic BaseModel subclasses with extra="allow" (so they won't break when the API adds new fields) and populate_by_name=True.

Wallet

class Wallet(BaseModel):
    name: str                      # e.g. "bitcoin", "CLORE-Blockchain", "USD-Blockchain"
    deposit: str | None            # Deposit address
    balance: float | None          # Current balance
    withdrawal_fee: float | None   # Withdrawal fee

MarketplaceServer

Returned by marketplace(). Has a nested structure with specs, price, and rating sub-objects, plus convenience properties for easy access.

class MarketplaceServer(BaseModel):
    id: int
    owner: int | None
    rented: bool | None
    specs: ServerSpecs | None      # Hardware specs (CPU, RAM, GPU, disk, network)
    price: ServerPrice | None      # Nested price object with on_demand/spot/usd
    reliability: float | None
    allowed_coins: List[str] | None
    rating: ServerRating | None
    gpu_array: List[Any] | None
    cuda_version: str | None
    mrl: int | None                # Minimum rental length

    # Convenience properties (read-only):
    @property gpu_model -> str | None       # e.g. "1x NVIDIA GeForce RTX 4090" (from specs.gpu)
    @property gpu_count -> int              # Number of GPUs (from gpu_array length)
    @property ram_gb -> float | None        # RAM in GB (from specs.ram)
    @property price_usd -> float | None     # On-demand price in USD (from price.usd.on_demand_usd)
    @property spot_price_usd -> float | None  # Spot price in USD (from price.usd.spot)
    @property available -> bool             # True if not rented
    @property location -> str | None        # Country code (from specs.net.cc)

Note: Server is a backward-compatible alias for MarketplaceServer.

ServerSpecs

Nested under MarketplaceServer.specs.

class ServerSpecs(BaseModel):
    mb: str | None                 # Motherboard
    cpu: str | None                # CPU model
    cpus: str | None               # "cores/threads" e.g. "16/32"
    ram: float | None              # RAM in GB
    disk: str | None               # Disk description
    disk_speed: float | None       # Disk speed MB/s
    gpu: str | None                # e.g. "1x NVIDIA GeForce RTX 4090"
    gpuram: float | None           # GPU VRAM in GB
    net: NetworkSpecs | None       # Network info (cc, down, up)
    pcie_rev: int | None
    pcie_width: int | None

ServerPrice

Nested under MarketplaceServer.price.

class ServerPrice(BaseModel):
    on_demand: PriceTier | None    # Per-currency on-demand prices
    spot: PriceTier | None         # Per-currency spot prices
    usd: PriceUSD | None           # USD-equivalent prices
    original_usd: Dict[str, OriginalUSDEntry] | None

class PriceTier(BaseModel):        # Per payment method
    bitcoin: float | None
    CLORE_Blockchain: float | None  # alias: "CLORE-Blockchain"
    USD_Blockchain: float | None    # alias: "USD-Blockchain"

class PriceUSD(BaseModel):         # USD equivalents
    on_demand_btc: float | None
    on_demand_clore: float | None
    on_demand_usd: float | None
    spot: float | None

MyServer

Returned by my_servers(). Different from MarketplaceServer — represents servers you host.

class MyServer(BaseModel):
    id: int
    name: str | None
    connected: bool | None
    visibility: str | None         # "public" / "private"
    pricing: Dict[str, float] | None
    online: bool | None
    gpu_array: List[Any] | None
    specs: ServerSpecs | None
    working_properly: bool | None

    # Convenience properties:
    @property gpu_model -> str | None   # Primary GPU description
    @property ram_gb -> float | None    # RAM in GB
    @property status -> str             # "Online", "Offline", "Disconnected", or "Not Working"

ServerConfig

Returned by server_config().

class ServerConfig(BaseModel):
    id: int | None
    name: str | None
    connected: bool | None
    visibility: str | None
    pricing: Dict[str, float] | None
    usd_pricing: Dict[str, CurrencyPricing] | None
    mrl: int | None                # Min rental length
    online: bool | None
    specs: ServerSpecs | None
    background_job: BackgroundJob | None

    # Convenience properties:
    @property gpu_model -> str | None
    @property on_demand_price -> float | None   # First available on-demand USD price
    @property spot_price -> float | None        # First available spot USD price

Order

class Order(BaseModel):
    id: int
    server_id: int | None          # Alias: "renting_server"
    type: str | None               # "on-demand" or "spot"
    status: str | None
    image: str | None
    currency: str | None
    price: float | None
    created_at: str | None
    pub_cluster: str | None        # Public IP / hostname
    tcp_ports: Dict[str, int] | None  # Port mappings
    http_port: int | None
    env: Dict[str, str] | None
    ssh_password: str | None
    ssh_key: str | None
    jupyter_token: str | None
    command: str | None

SpotMarket

Returned by spot_marketplace().

class SpotMarket(BaseModel):
    currency_rates_in_usd: Dict[str, float] | None
    offers: List[SpotOffer] | None
    server: SpotServerInfo | None

class SpotOffer(BaseModel):
    order_id: int | None
    price: float | None
    server_id: int | None

class SpotServerInfo(BaseModel):
    min_pricing: Dict[str, float] | None
    mrl: int | None
    visibility: str | None
    online: bool | None

APIResponse

class APIResponse(BaseModel):
    code: int
    message: str | None
    data: Any | None

---

Exceptions

All exceptions inherit from CloreAPIError.

Hierarchy

CloreAPIError (base)
├── DBError            # Code 1 — database error
├── InvalidInputError  # Code 2 — bad request parameters
├── AuthError          # Code 3 — invalid or missing API key
├── InvalidEndpointError # Code 4 — endpoint does not exist
├── RateLimitError     # Code 5 — rate limit exceeded
└── FieldError         # Code 6 — error in a specific field

CloreAPIError

class CloreAPIError(Exception):
    code: int | None       # API error code (1–6)
    response: dict | None  # Raw API response

Error Code Table

Code	Exception Class	Meaning
0	(success)	No error
1	DBError	Database / internal error
2	InvalidInputError	Invalid input parameters
3	AuthError	Authentication failed
4	InvalidEndpointError	Unknown endpoint
5	RateLimitError	Rate limit exceeded
6	FieldError	Error in a specific field (see response)

Handling Errors

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,
    AuthError,
    RateLimitError,
    InvalidInputError,
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=999999,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("Check your CLORE_API_KEY")
except InvalidInputError as e:
    print(f"Bad request: {e} (code={e.code})")
except RateLimitError:
    print("Slow down — rate limit hit (auto-retry exhausted)")
except CloreAPIError as e:
    print(f"API error: {e} (code={e.code}, response={e.response})")

---

Rate Limiter

The SDK includes a built-in RateLimiter that enforces:

• 1 request/second for all endpoints (configurable via requests_per_second)

• 5-second cooldown between create_order calls (configurable via create_order_delay)

• Exponential backoff on rate-limit errors (code 5): starts at 1 s, doubles each retry up to max_retries

How It Works

Request 1 ─── 1s gap ─── Request 2 ─── 1s gap ─── Request 3
                                                        ↓
                                               Rate limit (code 5)
                                                        ↓
                                               Backoff 1s → retry
                                                        ↓
                                               Backoff 2s → retry
                                                        ↓
                                               Backoff 4s → retry (or raise)

The rate limiter is automatic — you don't need to configure anything. If you want to adjust:

client = CloreAI()
client.rate_limiter.min_interval = 2.0        # 0.5 req/sec
client.rate_limiter.create_order_delay = 10.0  # 10s between create_order calls

---

Configuration

Environment Variables

Variable	Description
CLORE_API_KEY	API key (preferred over config file)

Config File (~/.clore/config.json)

{
  "api_key": "your_api_key_here"
}

Set via CLI:

clore config set api_key YOUR_API_KEY
clore config get api_key
clore config show

Priority Order

1. api_key passed to constructor

2. CLORE_API_KEY environment variable

3. ~/.clore/config.json

---

CLI Reference

The clore command-line tool is installed with the package. It uses Rich for formatted terminal output.

Commands

Command	Description
clore search	Search GPU marketplace
clore orders	List your orders
clore deploy <server_id>	Create a new order
clore cancel <order_id>	Cancel an order
clore wallets	Show wallet balances
clore servers	List your hosted servers
clore server-config <name>	Get server configuration
clore spot <server_id>	View spot market for a server
clore spot-price <order_id> <price>	Set spot price
clore ssh <order_id>	SSH into an order
clore config set <key> <value>	Set config value
clore config get <key>	Get config value
clore config show	Show all config

clore search

clore search [OPTIONS]

Options:
  --gpu TEXT          Filter by GPU model (e.g. "RTX 4090")
  --min-gpu INTEGER   Minimum GPU count
  --min-ram FLOAT     Minimum RAM in GB
  --max-price FLOAT   Maximum price in USD/hour
  --sort [price|gpu|ram]  Sort results (default: price)
  --limit INTEGER     Limit results (default: 20)

clore deploy

clore deploy SERVER_ID [OPTIONS]

Options:
  --image TEXT           Docker image (required)
  --type [on-demand|spot]  Order type (required)
  --currency TEXT        Payment currency (required)
  --ssh-password TEXT    SSH password
  --ssh-key TEXT         SSH public key
  --port TEXT            Port mapping, repeatable (e.g. 22:tcp)
  --env TEXT             Environment variable, repeatable (KEY=VALUE)
  --spot-price FLOAT     Spot price (for spot orders)

clore ssh

clore ssh ORDER_ID [OPTIONS]

Options:
  --user TEXT  SSH user (default: root)

---

See Also

• SDK Quick Start — step-by-step tutorial

• Automation Recipes — production patterns

• CI/CD with clore-ai SDK — pipeline integration

• Clore Client Reference — legacy requests-based client