Complete guide for robots, IoT devices, and AI agents to rent computational power on RoboCompute
All API requests require authentication using API keys and Solana wallet signatures.
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.
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"
}
Headers:
Authorization: Bearer rc_live_your_api_key
X-Wallet-Signature: base64_encoded_signature
X-Timestamp: 1234567890
RoboCompute uses Solana stablecoins (USDC/USDT) for all payments. You need a Solana wallet with USDC or USDT.
GET /api/v1/wallet/balance
Response:
{
"wallet_address": "YourSolanaWalletAddress",
"usdc_balance": "1000.50",
"usdt_balance": "500.25",
"sol_balance": "0.5"
}
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"
}
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"
}
// 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
}
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 /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"
}
pending - Waiting for providerqueued - Queued on providerrunning - Currently executingcompleted - Successfully finishedfailed - Execution failedcancelled - Cancelled by clienttimeout - Execution timeoutGET /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 /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"
}
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
}
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 /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
}
}
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 /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 /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"
}
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
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);
}
});
#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_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 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