# API Quick Reference

Quick reference for the most commonly used Clore.ai API endpoints.

## Step 1: Set Up the Clore Client

> 📦 **Using the standard Clore API client.** See [Clore API Client Reference](https://docs.clore.ai/dev/reference/clore-client) for the full implementation and setup instructions. Save it as `clore_client.py` in your project.

```python
from clore_client import CloreClient

client = CloreClient(api_key="your-api-key")
```

## Authentication

All requests require the `auth` header:

```bash
curl -H "auth: YOUR_API_KEY" https://api.clore.ai/v1/marketplace
```

**Note:** The header is `auth`, NOT `Authorization: Bearer`! <https://api.clore.ai>

````

## Rate Limiting

- **1 request per second** per API key
- Implement exponential backoff when you receive code 5

## Common Endpoints

### Get Marketplace

```bash
GET /v1/marketplace
````

Returns all available servers with specs and pricing.

```python
import requests

headers = {"auth": "YOUR_API_KEY"}
response = requests.get("https://api.clore.ai/v1/marketplace", headers=headers)
servers = response.json()["servers"]

# Filter available RTX 4090s
available = [s for s in servers 
             if not s["rented"] 
             and "RTX 4090" in str(s.get("gpu_array", []))]
```

### Get Wallets

```bash
GET /v1/wallets
```

Returns wallet balances for all currencies.

```python
response = requests.get("https://api.clore.ai/v1/wallets", headers=headers)
wallets = response.json()["wallets"]

# Get CLORE balance
clore_balance = next(w["balance"] for w in wallets if "CLORE" in w["name"])
```

### Create Order

```bash
POST /v1/create_order
```

Rent a server.

```python
order_data = {
    "renting_server": 12345,           # Server ID
    "type": "on-demand",               # or "spot"
    "currency": "CLORE-Blockchain",    # or "bitcoin", "USD-Blockchain"
    "image": "nvidia/cuda:12.8.0-base-ubuntu22.04",
    "ports": {"22": "tcp", "8888": "http"},
    "env": {"NVIDIA_VISIBLE_DEVICES": "all"},
    "ssh_password": "YourSecurePass123!"
}

# For spot orders, add:
# order_data["spotprice"] = 0.15

response = requests.post(
    "https://api.clore.ai/v1/create_order",
    headers=headers,
    json=order_data
)
order_id = response.json()["order_id"]
```

### Get Orders

```bash
GET /v1/my_orders
GET /v1/my_orders?return_completed=true
```

```python
response = requests.get("https://api.clore.ai/v1/my_orders", headers=headers)
orders = response.json()["orders"]

# Find active orders
active = [o for o in orders if o["status"] == "running"]
```

### Cancel Order

```bash
POST /v1/cancel_order
```

```python
response = requests.post(
    "https://api.clore.ai/v1/cancel_order",
    headers=headers,
    json={"id": order_id}
)
```

### Update Spot Price

```bash
POST /v1/set_spot_price
```

```python
response = requests.post(
    "https://api.clore.ai/v1/set_spot_price",
    headers=headers,
    json={
        "order_id": order_id,
        "desired_price": 0.20
    }
)
```

### Get Spot Market

```bash
GET /v1/spot_marketplace?market=SERVER_ID
```

```python
response = requests.get(
    "https://api.clore.ai/v1/spot_marketplace",
    headers=headers,
    params={"market": 12345}
)
spot_data = response.json()["market"]
```

## Response Codes

| Code | Meaning                 |
| ---- | ----------------------- |
| 0    | Success                 |
| 1    | Database error          |
| 2    | Invalid input           |
| 3    | Invalid/missing API key |
| 4    | Invalid endpoint        |
| 5    | Rate limit exceeded     |
| 6    | See error field         |

## Common Errors

| Error                   | Solution                       |
| ----------------------- | ------------------------------ |
| `not_enough_balance`    | Top up your wallet             |
| `server-already-rented` | Server not available           |
| `too_low_price`         | Increase spot bid              |
| `server-offline`        | Server is offline, try another |
| `currency-not-allowed`  | Use different currency         |

## Quick Python Client

```python
import requests
import time

# Usage
client = CloreClient("YOUR_API_KEY")
servers = client.get_marketplace()
```

## Server Object Structure

```python
{
    "id": 12345,
    "owner": 67890,
    "mrl": 168,                     # Max rental hours
    "rented": False,
    "price": {
        "on_demand": {
            "bitcoin": 0.00000125,
            "CLORE-Blockchain": 0.25,
            "USD-Blockchain": 0.40
        },
        "spot": {
            "bitcoin": 0.0000008,
            "CLORE-Blockchain": 0.15
        },
        "usd": {
            "on_demand_clore": 0.40,  # USD per hour
            "spot": 0.25
        }
    },
    "specs": {
        "gpu": "2x NVIDIA GeForce RTX 4090",  # count prefix + full vendor name
        "cpu": "Intel i9-13900K",
        "ram": 64.0,                           # float, value in GB
        "disk": "SAMSUNG SSD SM841 2000GB"     # raw string
    },
    # Note: gpu count = len(gpu_array); use gpu_array for per-card model matching
    "gpu_array": ["NVIDIA GeForce RTX 4090", "NVIDIA GeForce RTX 4090"],
    "reliability": 0.985,  # float 0.0–1.0 (fraction, not percentage; e.g. 0.985 = 98.5% uptime)
    "rating": {"avg": 4.8, "cnt": 25},
    "allowed_coins": ["bitcoin", "CLORE-Blockchain", "USD-Blockchain"]
}
```

## Order Object Structure

```python
{
    "order_id": 98765,
    "renting_server": 12345,
    "type": "on-demand",
    "status": "running",           # pending, running, paused, expired
    "currency": "CLORE-Blockchain",
    "price": 0.25,
    "created": 1709400000,         # Unix timestamp
    "started": 1709400120,
    "connection": {
        "ssh": "ssh root@node123.clore.ai -p 40022",
        "jupyter": "http://node123.clore.ai:8888",
        "ports": {
            "22": "tcp://node123.clore.ai:40022",
            "8888": "http://node123.clore.ai:40088"
        }
    }
}
```

## See Also

* [Common Error Codes](https://docs.clore.ai/dev/reference/error-codes)
* [Docker Images Reference](https://docs.clore.ai/dev/reference/docker-images)
* [Quick Start Guide](https://docs.clore.ai/dev/getting-started/quick-start)