Client API Documentation

Complete guide for robots, IoT devices, and AI agents to rent computational power on RoboCompute

Solana Stablecoins USDC/USDT REST API WebSocket

1. Authentication

All API requests require authentication using API keys and Solana wallet signatures.

API Base Domain

API base domain: robocompute.xyz/api/

All API requests are made to the robocompute.xyz/api/ domain. The SDK automatically uses this domain by default.

Get API Key

POST /api/v1/auth/register
Content-Type: application/json

{
  "wallet_address": "YourSolanaWalletAddress",
  "device_id": "unique-device-identifier",
  "device_type": "robot|iot|ai_agent"
}

Response:
{
  "api_key": "rc_live_...",
  "client_id": "client_123456",
  "wallet_address": "YourSolanaWalletAddress"
}

Authenticate Request

Headers:
Authorization: Bearer rc_live_your_api_key
X-Wallet-Signature: base64_encoded_signature
X-Timestamp: 1234567890

2. Solana Wallet Setup

RoboCompute uses Solana stablecoins (USDC/USDT) for all payments. You need a Solana wallet with USDC or USDT.

Check Wallet Balance

GET /api/v1/wallet/balance

Response:
{
  "wallet_address": "YourSolanaWalletAddress",
  "usdc_balance": "1000.50",
  "usdt_balance": "500.25",
  "sol_balance": "0.5"
}

Deposit Funds

POST /api/v1/wallet/deposit
{
  "amount": "100.00",
  "currency": "USDC", // or "USDT"
  "memo": "Deposit for compute tasks"
}

Response:
{
  "deposit_address": "SolanaDepositAddress",
  "amount": "100.00",
  "currency": "USDC",
  "expires_at": "2025-01-15T12:00:00Z"
}

3. Task Management (CRUD)

CREATE Submit Task

POST /api/v1/tasks
{
  "name": "Object Detection Task",
  "type": "gpu",
  "resource_requirements": {
    "cpu_cores": 4,
    "gpu_memory_gb": 8,
    "ram_gb": 16,
    "storage_gb": 50
  },
  "docker_image": "your-registry/image:tag",
  "command": ["python", "detect.py"],
  "max_price_per_hour": "10.00", // USDC
  "timeout_seconds": 3600,
  "priority": "high|normal|low"
}

Response:
{
  "task_id": "task_abc123",
  "status": "pending",
  "estimated_cost": "5.50",
  "estimated_completion": "2025-01-15T13:30:00Z",
  "created_at": "2025-01-15T12:00:00Z"
}

READ Get Task(s)

// Get single task
GET /api/v1/tasks/{task_id}

// List all tasks
GET /api/v1/tasks?status=running&limit=50&offset=0

Response:
{
  "tasks": [
    {
      "task_id": "task_abc123",
      "name": "Object Detection Task",
      "status": "running",
      "provider_id": "provider_xyz789",
      "cost_so_far": "3.25",
      "started_at": "2025-01-15T12:05:00Z",
      "progress": 65
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

UPDATE Update Task

PATCH /api/v1/tasks/{task_id}
{
  "max_price_per_hour": "15.00", // Increase max price
  "priority": "high",
  "timeout_seconds": 7200
}

Response:
{
  "task_id": "task_abc123",
  "status": "updated",
  "updated_at": "2025-01-15T12:30:00Z"
}

DELETE Cancel Task

DELETE /api/v1/tasks/{task_id}

Response:
{
  "task_id": "task_abc123",
  "status": "cancelled",
  "refund_amount": "2.50", // USDC refunded
  "cancelled_at": "2025-01-15T12:45:00Z"
}

Task Status Values

  • pending - Waiting for provider
  • queued - Queued on provider
  • running - Currently executing
  • completed - Successfully finished
  • failed - Execution failed
  • cancelled - Cancelled by client
  • timeout - Execution timeout

4. Payments & Billing

Get Billing History

GET /api/v1/billing/history?start_date=2025-01-01&end_date=2025-01-31

Response:
{
  "transactions": [
    {
      "transaction_id": "tx_123",
      "task_id": "task_abc123",
      "amount": "5.50",
      "currency": "USDC",
      "type": "task_payment",
      "status": "completed",
      "solana_tx_hash": "5j7s8K9...",
      "created_at": "2025-01-15T13:00:00Z"
    }
  ],
  "total_spent": "1250.75",
  "total_tasks": 45
}

Get Invoice

GET /api/v1/billing/invoices/{invoice_id}

Response:
{
  "invoice_id": "inv_456",
  "task_id": "task_abc123",
  "amount": "5.50",
  "currency": "USDC",
  "breakdown": {
    "compute_hours": 0.5,
    "rate_per_hour": "10.00",
    "platform_fee": "0.55",
    "network_fee": "0.05"
  },
  "solana_tx_hash": "5j7s8K9...",
  "paid_at": "2025-01-15T13:00:00Z"
}

Set Payment Method

POST /api/v1/billing/payment-method
{
  "preferred_currency": "USDC", // or "USDT"
  "auto_topup": true,
  "topup_threshold": "50.00",
  "topup_amount": "200.00"
}

Response:
{
  "payment_method_id": "pm_789",
  "preferred_currency": "USDC",
  "auto_topup_enabled": true
}

5. Resource Discovery

Search Providers

GET /api/v1/providers/search?gpu_memory_min=8&cpu_cores_min=4&max_price=15.00&location=us-east

Response:
{
  "providers": [
    {
      "provider_id": "provider_xyz789",
      "name": "High-Performance Compute Node",
      "specs": {
        "cpu_cores": 16,
        "gpu_memory_gb": 24,
        "ram_gb": 64,
        "storage_gb": 500
      },
      "pricing": {
        "cpu_per_hour": "0.50",
        "gpu_per_hour": "8.00",
        "ram_per_hour": "0.20",
        "storage_per_hour": "0.10"
      },
      "reputation_score": 4.8,
      "uptime_percentage": 99.9,
      "location": "us-east",
      "available": true
    }
  ],
  "total": 25
}

Get Provider Details

GET /api/v1/providers/{provider_id}

Response:
{
  "provider_id": "provider_xyz789",
  "name": "High-Performance Compute Node",
  "specs": { /* full specs */ },
  "pricing": { /* full pricing */ },
  "reputation": {
    "score": 4.8,
    "total_tasks": 1250,
    "success_rate": 99.2
  },
  "availability": {
    "current_load": 45,
    "max_capacity": 100
  }
}

6. Task Monitoring

WebSocket Connection

wss://robocompute.xyz/api/v1/tasks/{task_id}/stream

// Subscribe to task updates
{
  "action": "subscribe",
  "task_id": "task_abc123"
}

// Receive updates
{
  "event": "status_update",
  "task_id": "task_abc123",
  "status": "running",
  "progress": 45,
  "elapsed_time": 1800,
  "estimated_remaining": 2200
}

Get Task Logs

GET /api/v1/tasks/{task_id}/logs?lines=100&follow=false

Response:
{
  "logs": [
    {
      "timestamp": "2025-01-15T12:05:00Z",
      "level": "info",
      "message": "Task started"
    },
    {
      "timestamp": "2025-01-15T12:05:30Z",
      "level": "info",
      "message": "Processing image batch 1/10"
    }
  ],
  "total_lines": 150
}

Get Task Metrics

GET /api/v1/tasks/{task_id}/metrics

Response:
{
  "task_id": "task_abc123",
  "metrics": {
    "cpu_usage_percent": 85.5,
    "gpu_usage_percent": 92.3,
    "memory_usage_gb": 12.5,
    "network_io_mb": 450.2,
    "disk_io_mb": 120.8
  },
  "timestamp": "2025-01-15T12:30:00Z"
}

7. SDK Integration

Python Frameworks

from fastapi import FastAPI, HTTPException
from robocompute import RoboComputeClient
from pydantic import BaseModel
from solana.rpc.api import Client

app = FastAPI()
client = RoboComputeClient(
    api_key="rc_live_your_api_key",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

class TaskRequest(BaseModel):
    name: str
    type: str
    cpu_cores: int
    gpu_memory_gb: int
    ram_gb: int
    docker_image: str
    command: list[str]
    max_price_per_hour: str

@app.post("/tasks/submit")
async def submit_task(request: TaskRequest):
    task = client.tasks.create(
        name=request.name,
        type=request.type,
        resource_requirements={
            "cpu_cores": request.cpu_cores,
            "gpu_memory_gb": request.gpu_memory_gb,
            "ram_gb": request.ram_gb
        },
        docker_image=request.docker_image,
        command=request.command,
        max_price_per_hour=request.max_price_per_hour  # USDC
    )
    return {"task_id": task.task_id, "status": task.status}

@app.get("/tasks/{task_id}")
async def get_task(task_id: str):
    task = client.tasks.get(task_id)
    return task
from flask import Flask, request, jsonify
from robocompute import RoboComputeClient
from solana.rpc.api import Client

app = Flask(__name__)
client = RoboComputeClient(
    api_key="rc_live_your_api_key",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

@app.route('/tasks/submit', methods=['POST'])
def submit_task():
    data = request.json
    task = client.tasks.create(
        name=data['name'],
        type=data['type'],
        resource_requirements={
            "cpu_cores": data['cpu_cores'],
            "gpu_memory_gb": data['gpu_memory_gb'],
            "ram_gb": data['ram_gb']
        },
        docker_image=data['docker_image'],
        command=data['command'],
        max_price_per_hour=data['max_price_per_hour']  # USDC
    )
    return jsonify({"task_id": task.task_id, "status": task.status})

@app.route('/tasks/<task_id>', methods=['GET'])
def get_task(task_id):
    task = client.tasks.get(task_id)
    return jsonify(task)
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from robocompute import RoboComputeClient
import json

client = RoboComputeClient(
    api_key="rc_live_your_api_key",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

@csrf_exempt
@require_http_methods(["POST"])
def submit_task(request):
    data = json.loads(request.body)
    task = client.tasks.create(
        name=data['name'],
        type=data['type'],
        resource_requirements={
            "cpu_cores": data['cpu_cores'],
            "gpu_memory_gb": data['gpu_memory_gb'],
            "ram_gb": data['ram_gb']
        },
        docker_image=data['docker_image'],
        command=data['command'],
        max_price_per_hour=data['max_price_per_hour']  # USDC
    )
    return JsonResponse({"task_id": task.task_id, "status": task.status})

@require_http_methods(["GET"])
def get_task(request, task_id):
    task = client.tasks.get(task_id)
    return JsonResponse(task)
from robocompute import RoboComputeClient
from solana.rpc.api import Client

# Initialize client
client = RoboComputeClient(
    api_key="rc_live_your_api_key",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

# Submit task
task = client.tasks.create(
    name="Object Detection",
    type="gpu",
    resource_requirements={
        "cpu_cores": 4,
        "gpu_memory_gb": 8,
        "ram_gb": 16
    },
    docker_image="your-registry/image:tag",
    command=["python", "detect.py"],
    max_price_per_hour="10.00"  # USDC
)

# Monitor task
for update in client.tasks.stream(task.task_id):
    print(f"Status: {update.status}, Progress: {update.progress}%")
    if update.status == "completed":
        results = client.tasks.get_results(task.task_id)
        break

Node.js Frameworks

const express = require('express');
const { RoboComputeClient } = require('@robocompute/node-sdk');
const { Connection } = require('@solana/web3.js');

const app = express();
app.use(express.json());

const client = new RoboComputeClient({
    apiKey: 'rc_live_your_api_key',
    walletAddress: 'YourSolanaWalletAddress',
    solanaRpc: 'https://api.mainnet-beta.solana.com'
});

app.post('/tasks/submit', async (req, res) => {
    try {
        const task = await client.tasks.create({
            name: req.body.name,
            type: req.body.type,
            resourceRequirements: {
                cpuCores: req.body.cpu_cores,
                gpuMemoryGb: req.body.gpu_memory_gb,
                ramGb: req.body.ram_gb
            },
            dockerImage: req.body.docker_image,
            command: req.body.command,
            maxPricePerHour: req.body.max_price_per_hour // USDC
        });
        res.json({ task_id: task.taskId, status: task.status });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.get('/tasks/:taskId', async (req, res) => {
    try {
        const task = await client.tasks.get(req.params.taskId);
        res.json(task);
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.listen(3000);
import { Controller, Post, Get, Body, Param } from '@nestjs/common';
import { RoboComputeClient } from '@robocompute/nestjs';
import { Connection } from '@solana/web3.js';

@Controller('tasks')
export class TasksController {
    private client: RoboComputeClient;

    constructor() {
        this.client = new RoboComputeClient({
            apiKey: 'rc_live_your_api_key',
            walletAddress: 'YourSolanaWalletAddress',
            solanaRpc: 'https://api.mainnet-beta.solana.com'
        });
    }

    @Post('submit')
    async submitTask(@Body() taskData: any) {
        const task = await this.client.tasks.create({
            name: taskData.name,
            type: taskData.type,
            resourceRequirements: {
                cpuCores: taskData.cpu_cores,
                gpuMemoryGb: taskData.gpu_memory_gb,
                ramGb: taskData.ram_gb
            },
            dockerImage: taskData.docker_image,
            command: taskData.command,
            maxPricePerHour: taskData.max_price_per_hour // USDC
        });
        return { task_id: task.taskId, status: task.status };
    }

    @Get(':taskId')
    async getTask(@Param('taskId') taskId: string) {
        return await this.client.tasks.get(taskId);
    }
}
const { RoboComputeClient } = require('@robocompute/node-sdk');
const { Connection } = require('@solana/web3.js');

const client = new RoboComputeClient({
    apiKey: 'rc_live_your_api_key',
    walletAddress: 'YourSolanaWalletAddress',
    solanaRpc: 'https://api.mainnet-beta.solana.com'
});

// Submit task
const task = await client.tasks.create({
    name: 'Object Detection',
    type: 'gpu',
    resourceRequirements: {
        cpuCores: 4,
        gpuMemoryGb: 8,
        ramGb: 16
    },
    dockerImage: 'your-registry/image:tag',
    command: ['python', 'detect.py'],
    maxPricePerHour: '10.00' // USDC
});

// Monitor task
client.tasks.stream(task.taskId, (update) => {
    console.log(`Status: ${update.status}, Progress: ${update.progress}%`);
    if (update.status === 'completed') {
        const results = client.tasks.getResults(task.taskId);
    }
});

C++ SDK

#include <robocompute/client.hpp>

using namespace robocompute;

RoboComputeClient client(
    "rc_live_your_api_key",
    "YourSolanaWalletAddress"
);

TaskRequest request;
request.name = "Object Detection";
request.type = TaskType::GPU;
request.resource_requirements.cpu_cores = 4;
request.resource_requirements.gpu_memory_gb = 8;
request.max_price_per_hour = "10.00"; // USDC

auto task = client.create_task(request);

// Monitor task
client.monitor_task(task.task_id, [](const TaskUpdate& update) {
    std::cout << "Status: " << update.status << std::endl;
});

ROS2 Integration

# ros2_robocompute package
from ros2_robocompute.client import RoboComputeROS2Client

client = RoboComputeROS2Client()

# Subscribe to compute requests
def handle_compute_request(msg):
    task = client.submit_task(
        name=msg.task_name,
        docker_image=msg.docker_image,
        max_price_per_hour=str(msg.max_price)
    )
    # Publish task status
    status_pub.publish(task.status)

compute_sub = node.create_subscription(
    ComputeRequest,
    'compute_request',
    handle_compute_request
)

Error Handling

// Error Response Format
{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Wallet balance insufficient for task",
    "details": {
      "required": "10.00",
      "available": "5.50",
      "currency": "USDC"
    }
  }
}

// Common Error Codes
- INSUFFICIENT_FUNDS
- TASK_NOT_FOUND
- PROVIDER_UNAVAILABLE
- INVALID_RESOURCE_REQUIREMENTS
- WALLET_SIGNATURE_INVALID
- RATE_LIMIT_EXCEEDED