Provider API Documentation

Complete guide for providers to share computing resources and earn Solana stablecoins (USDC/USDT)

Earn USDC/USDT Solana Blockchain Staking Required Reputation System

Table of Contents

1. Provider Registration

Register your compute node to start earning Solana stablecoins by sharing computational resources.

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.

Register Provider

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

{
  "wallet_address": "YourSolanaWalletAddress",
  "node_name": "My Compute Node",
  "location": "us-east",
  "resources": {
    "cpu_cores": 16,
    "gpu_memory_gb": 24,
    "gpu_count": 2,
    "ram_gb": 64,
    "storage_gb": 500,
    "gpu_model": "NVIDIA RTX 4090"
  },
  "pricing": {
    "cpu_per_hour": "0.50", // USDC
    "gpu_per_hour": "8.00",
    "ram_per_hour": "0.20",
    "storage_per_hour": "0.10"
  }
}

Response:
{
  "provider_id": "provider_xyz789",
  "api_key": "rc_prov_live_...",
  "staking_requirement": "1000.00", // USDC minimum stake
  "status": "pending_verification"
}

Verify Node

POST /api/v1/providers/{provider_id}/verify
{
  "benchmark_results": {
    "cpu_score": 12500,
    "gpu_score": 45000,
    "network_latency_ms": 15
  }
}

Response:
{
  "provider_id": "provider_xyz789",
  "verification_status": "verified",
  "verified_at": "2025-01-15T12:00:00Z"
}

2. Staking & Security

Providers must stake Solana stablecoins (USDC/USDT) as collateral to ensure reliable service and prevent fraud.

Check Staking Status

GET /api/v1/providers/{provider_id}/staking

Response:
{
  "provider_id": "provider_xyz789",
  "staked_amount": "1500.00",
  "currency": "USDC",
  "minimum_required": "1000.00",
  "staking_address": "SolanaStakingAddress",
  "slashing_risk": "low",
  "last_updated": "2025-01-15T12:00:00Z"
}

Stake Funds

POST /api/v1/providers/{provider_id}/staking/stake
{
  "amount": "1000.00",
  "currency": "USDC" // or "USDT"
}

Response:
{
  "staking_transaction": {
    "tx_hash": "5j7s8K9...",
    "amount": "1000.00",
    "currency": "USDC",
    "status": "pending",
    "confirmation_required": 32
  },
  "new_staked_amount": "2500.00"
}

Unstake Funds (with cooldown)

POST /api/v1/providers/{provider_id}/staking/unstake
{
  "amount": "500.00",
  "currency": "USDC"
}

Response:
{
  "unstake_request": {
    "request_id": "unstake_req_123",
    "amount": "500.00",
    "currency": "USDC",
    "cooldown_period_days": 7,
    "available_at": "2025-01-22T12:00:00Z"
  },
  "remaining_staked": "2000.00"
}

3. Resource Management (CRUD)

CREATE Register Resource 

POST /api/v1/providers/{provider_id}/resources
{
  "resource_type": "gpu",
  "specifications": {
    "model": "NVIDIA RTX 4090",
    "memory_gb": 24,
    "compute_capability": "8.9"
  },
  "pricing": {
    "per_hour": "8.00", // USDC
    "per_minute": "0.133"
  },
  "availability": {
    "max_concurrent_tasks": 4,
    "scheduling_policy": "fifo"
  }
}

Response:
{
  "resource_id": "resource_gpu_001",
  "provider_id": "provider_xyz789",
  "status": "available",
  "created_at": "2025-01-15T12:00:00Z"
}

READ Get Resource(s) 

// Get single resource
GET /api/v1/providers/{provider_id}/resources/{resource_id}

// List all resources
GET /api/v1/providers/{provider_id}/resources?type=gpu&status=available

Response:
{
  "resources": [
    {
      "resource_id": "resource_gpu_001",
      "type": "gpu",
      "specifications": { /* full specs */ },
      "pricing": { /* pricing */ },
      "status": "available",
      "current_load": 2,
      "max_capacity": 4,
      "utilization_percent": 50
    }
  ],
  "total": 5
}

UPDATE Update Resource 

PATCH /api/v1/providers/{provider_id}/resources/{resource_id}
{
  "pricing": {
    "per_hour": "10.00" // Update pricing
  },
  "availability": {
    "max_concurrent_tasks": 6,
    "scheduling_policy": "priority"
  },
  "status": "available" // or "maintenance", "unavailable"
}

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

DELETE Remove Resource 

DELETE /api/v1/providers/{provider_id}/resources/{resource_id}

Response:
{
  "resource_id": "resource_gpu_001",
  "status": "removed",
  "removed_at": "2025-01-15T12:45:00Z",
  "note": "All active tasks completed before removal"
}

4. Task Execution

Accept Task

POST /api/v1/providers/{provider_id}/tasks/accept
{
  "task_id": "task_abc123",
  "resource_id": "resource_gpu_001"
}

Response:
{
  "task_id": "task_abc123",
  "provider_id": "provider_xyz789",
  "status": "accepted",
  "estimated_earnings": "5.50", // USDC
  "start_time": "2025-01-15T12:05:00Z"
}

Start Task Execution

POST /api/v1/providers/{provider_id}/tasks/{task_id}/start
{
  "container_id": "docker_container_id",
  "resource_usage": {
    "cpu_cores": 4,
    "gpu_memory_gb": 8,
    "ram_gb": 16
  }
}

Response:
{
  "task_id": "task_abc123",
  "status": "running",
  "started_at": "2025-01-15T12:05:00Z",
  "monitoring_url": "wss://robocompute.xyz/api/v1/tasks/task_abc123/monitor"
}

Update Task Progress

PATCH /api/v1/providers/{provider_id}/tasks/{task_id}/progress
{
  "progress": 65,
  "status": "running",
  "metrics": {
    "cpu_usage": 85.5,
    "gpu_usage": 92.3,
    "memory_usage_gb": 12.5
  }
}

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

Complete Task

POST /api/v1/providers/{provider_id}/tasks/{task_id}/complete
{
  "result_hash": "sha256_hash_of_results",
  "result_storage_url": "https://storage.robocompute.io/results/...",
  "execution_time_seconds": 3600,
  "resource_usage": {
    "cpu_hours": 4.0,
    "gpu_hours": 1.0,
    "ram_hours": 16.0
  }
}

Response:
{
  "task_id": "task_abc123",
  "status": "completed",
  "earnings": "5.50", // USDC
  "completed_at": "2025-01-15T13:05:00Z",
  "payment_tx_hash": "5j7s8K9..."
}

Report Task Failure

POST /api/v1/providers/{provider_id}/tasks/{task_id}/fail
{
  "error_code": "EXECUTION_ERROR",
  "error_message": "Container crashed during execution",
  "logs": "Error logs here..."
}

Response:
{
  "task_id": "task_abc123",
  "status": "failed",
  "penalty_applied": false, // true if provider fault
  "reputation_impact": -0.1
}

5. Earnings & Payouts

Get Earnings Summary

GET /api/v1/providers/{provider_id}/earnings?start_date=2025-01-01&end_date=2025-01-31

Response:
{
  "provider_id": "provider_xyz789",
  "period": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "earnings": {
    "total_usdc": "1250.75",
    "total_usdt": "0.00",
    "total_tasks": 45,
    "average_per_task": "27.79"
  },
  "breakdown": {
    "cpu_earnings": "250.50",
    "gpu_earnings": "850.25",
    "ram_earnings": "100.00",
    "storage_earnings": "50.00"
  },
  "fees": {
    "platform_fee": "125.08", // 10%
    "network_fee": "6.25"
  },
  "net_earnings": "1119.42"
}

Get Pending Payouts

GET /api/v1/providers/{provider_id}/payouts/pending

Response:
{
  "pending_payouts": [
    {
      "payout_id": "payout_123",
      "amount": "500.00",
      "currency": "USDC",
      "status": "pending",
      "scheduled_at": "2025-01-16T00:00:00Z"
    }
  ],
  "total_pending": "500.00"
}

Request Payout

POST /api/v1/providers/{provider_id}/payouts/request
{
  "amount": "500.00",
  "currency": "USDC", // or "USDT"
  "wallet_address": "YourSolanaWalletAddress"
}

Response:
{
  "payout_id": "payout_123",
  "amount": "500.00",
  "currency": "USDC",
  "status": "processing",
  "estimated_arrival": "2025-01-15T13:00:00Z",
  "solana_tx_hash": "5j7s8K9..."
}

Get Payout History

GET /api/v1/providers/{provider_id}/payouts/history?limit=50

Response:
{
  "payouts": [
    {
      "payout_id": "payout_122",
      "amount": "750.00",
      "currency": "USDC",
      "status": "completed",
      "solana_tx_hash": "5j7s8K9...",
      "completed_at": "2025-01-14T12:00:00Z"
    }
  ],
  "total": 25
}

6. Reputation System

Your reputation score affects task matching priority and earnings. Maintain high uptime and task completion rate.

Get Reputation Score

GET /api/v1/providers/{provider_id}/reputation

Response:
{
  "provider_id": "provider_xyz789",
  "reputation_score": 4.8,
  "total_tasks": 1250,
  "successful_tasks": 1240,
  "failed_tasks": 10,
  "success_rate": 99.2,
  "average_response_time_ms": 150,
  "uptime_percentage": 99.9,
  "factors": {
    "task_completion": 0.99,
    "response_time": 0.95,
    "uptime": 0.99,
    "client_ratings": 4.7
  },
  "rank": 45, // Out of 1000 providers
  "tier": "gold" // bronze, silver, gold, platinum
}

Reputation Impact Events

  • +0.01 - Successful task completion
  • +0.05 - Early task completion
  • -0.1 - Task failure (provider fault)
  • -0.5 - Slashing event (fraud detection)
  • -0.02 - Late task completion
  • +0.1 - Positive client rating

7. Node Monitoring

Get Node Status

GET /api/v1/providers/{provider_id}/status

Response:
{
  "provider_id": "provider_xyz789",
  "status": "online",
  "resources": {
    "total_cpu_cores": 16,
    "available_cpu_cores": 8,
    "total_gpu_memory_gb": 48,
    "available_gpu_memory_gb": 24,
    "total_ram_gb": 64,
    "available_ram_gb": 32
  },
  "active_tasks": 2,
  "queued_tasks": 1,
  "system_metrics": {
    "cpu_usage_percent": 50.0,
    "gpu_usage_percent": 50.0,
    "memory_usage_percent": 50.0,
    "network_bandwidth_mbps": 1000,
    "disk_io_mbps": 500
  },
  "last_heartbeat": "2025-01-15T12:30:00Z"
}

Send Heartbeat

POST /api/v1/providers/{provider_id}/heartbeat
{
  "status": "online",
  "resources_available": {
    "cpu_cores": 8,
    "gpu_memory_gb": 24,
    "ram_gb": 32
  },
  "active_tasks": 2
}

Response:
{
  "status": "ok",
  "timestamp": "2025-01-15T12:30:00Z"
}

Get Performance Metrics

GET /api/v1/providers/{provider_id}/metrics?period=7d

Response:
{
  "provider_id": "provider_xyz789",
  "period": "7d",
  "metrics": {
    "tasks_completed": 45,
    "average_task_duration_seconds": 1800,
    "average_earnings_per_task": "27.79",
    "uptime_percentage": 99.9,
    "resource_utilization": {
      "cpu_avg": 65.5,
      "gpu_avg": 72.3,
      "memory_avg": 58.2
    }
  }
}

8. Provider SDK

Python Frameworks

from fastapi import FastAPI, BackgroundTasks
from robocompute.provider import RoboComputeProvider
from solana.rpc.api import Client

app = FastAPI()
provider = RoboComputeProvider(
    api_key="rc_prov_live_your_api_key",
    provider_id="provider_xyz789",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

@app.on_event("startup")
async def startup_event():
    # Register resources
    resource = provider.resources.create(
        resource_type="gpu",
        specifications={"model": "NVIDIA RTX 4090", "memory_gb": 24},
        pricing={"per_hour": "8.00"}  # USDC
    )
    
    # Start provider
    provider.start()

@provider.on_task_assigned
async def handle_task(task):
    provider.tasks.accept(task.task_id)
    provider.tasks.start(task.task_id)
    result = await execute_task(task)
    provider.tasks.complete(task.task_id, result)
from flask import Flask
from robocompute.provider import RoboComputeProvider
from threading import Thread

app = Flask(__name__)
provider = RoboComputeProvider(
    api_key="rc_prov_live_your_api_key",
    provider_id="provider_xyz789",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

@provider.on_task_assigned
def handle_task(task):
    provider.tasks.accept(task.task_id)
    provider.tasks.start(task.task_id)
    result = execute_task(task)
    provider.tasks.complete(task.task_id, result)

def start_provider():
    resource = provider.resources.create(
        resource_type="gpu",
        specifications={"model": "NVIDIA RTX 4090", "memory_gb": 24},
        pricing={"per_hour": "8.00"}  # USDC
    )
    provider.start()

Thread(target=start_provider).start()
from robocompute.provider import RoboComputeProvider
from solana.rpc.api import Client

# Initialize provider
provider = RoboComputeProvider(
    api_key="rc_prov_live_your_api_key",
    provider_id="provider_xyz789",
    wallet_address="YourSolanaWalletAddress",
    solana_rpc="https://api.mainnet-beta.solana.com"
)

# Register resources
resource = provider.resources.create(
    resource_type="gpu",
    specifications={
        "model": "NVIDIA RTX 4090",
        "memory_gb": 24
    },
    pricing={"per_hour": "8.00"}  # USDC
)

# Listen for tasks
@provider.on_task_assigned
def handle_task(task):
    print(f"New task: {task.task_id}")
    # Accept and execute task
    provider.tasks.accept(task.task_id)
    provider.tasks.start(task.task_id)
    
    # Execute task...
    result = execute_task(task)
    
    # Complete task
    provider.tasks.complete(task.task_id, result)

# Start provider node
provider.start()

Node.js Frameworks

const express = require('express');
const { RoboComputeProvider } = require('@robocompute/node-sdk-provider');

const app = express();
const provider = new RoboComputeProvider({
    apiKey: 'rc_prov_live_your_api_key',
    providerId: 'provider_xyz789',
    walletAddress: 'YourSolanaWalletAddress',
    solanaRpc: 'https://api.mainnet-beta.solana.com'
});

// Register resource
provider.resources.create({
    resourceType: 'gpu',
    specifications: { model: 'NVIDIA RTX 4090', memoryGb: 24 },
    pricing: { perHour: '8.00' } // USDC
});

// Listen for tasks
provider.onTaskAssigned(async (task) => {
    await provider.tasks.accept(task.taskId);
    await provider.tasks.start(task.taskId);
    const result = await executeTask(task);
    await provider.tasks.complete(task.taskId, result);
});

provider.start();
import { Injectable, OnModuleInit } from '@nestjs/common';
import { RoboComputeProvider } from '@robocompute/nestjs-provider';

@Injectable()
export class ProviderService implements OnModuleInit {
    private provider: RoboComputeProvider;

    constructor() {
        this.provider = new RoboComputeProvider({
            apiKey: 'rc_prov_live_your_api_key',
            providerId: 'provider_xyz789',
            walletAddress: 'YourSolanaWalletAddress',
            solanaRpc: 'https://api.mainnet-beta.solana.com'
        });
    }

    async onModuleInit() {
        // Register resource
        await this.provider.resources.create({
            resourceType: 'gpu',
            specifications: { model: 'NVIDIA RTX 4090', memoryGb: 24 },
            pricing: { perHour: '8.00' } // USDC
        });

        // Listen for tasks
        this.provider.onTaskAssigned(async (task) => {
            await this.provider.tasks.accept(task.taskId);
            await this.provider.tasks.start(task.taskId);
            const result = await this.executeTask(task);
            await this.provider.tasks.complete(task.taskId, result);
        });

        this.provider.start();
    }
}
const { RoboComputeProvider } = require('@robocompute/node-sdk-provider');

const provider = new RoboComputeProvider({
    apiKey: 'rc_prov_live_your_api_key',
    providerId: 'provider_xyz789',
    walletAddress: 'YourSolanaWalletAddress',
    solanaRpc: 'https://api.mainnet-beta.solana.com'
});

// Register resource
provider.resources.create({
    resourceType: 'gpu',
    specifications: { model: 'NVIDIA RTX 4090', memoryGb: 24 },
    pricing: { perHour: '8.00' } // USDC
});

// Listen for tasks
provider.onTaskAssigned(async (task) => {
    await provider.tasks.accept(task.taskId);
    await provider.tasks.start(task.taskId);
    const result = await executeTask(task);
    await provider.tasks.complete(task.taskId, result);
});

provider.start();

Go SDK

package main

import (
    "github.com/robocompute/go-sdk/provider"
)

func main() {
    // Initialize provider
    p := provider.NewProvider(
        "rc_prov_live_your_api_key",
        "provider_xyz789",
        "YourSolanaWalletAddress",
    )
    
    // Register resource
    resource := &provider.Resource{
        Type: "gpu",
        Specifications: map[string]interface{}{
            "model": "NVIDIA RTX 4090",
            "memory_gb": 24,
        },
        Pricing: map[string]string{
            "per_hour": "8.00", // USDC
        },
    }
    p.RegisterResource(resource)
    
    // Start listening for tasks
    p.OnTaskAssigned(func(task *provider.Task) {
        p.AcceptTask(task.ID)
        p.StartTask(task.ID)
        
        // Execute task...
        result := executeTask(task)
        
        p.CompleteTask(task.ID, result)
    })
    
    p.Start()
}

Rust SDK

use robocompute::provider::Provider;
use solana_sdk::pubkey::Pubkey;

#[tokio::main]
async fn main() {
    let provider = Provider::new(
        "rc_prov_live_your_api_key",
        "provider_xyz789",
        Pubkey::from_str("YourSolanaWalletAddress").unwrap(),
    ).await;
    
    // Register resource
    let resource = Resource {
        resource_type: "gpu".to_string(),
        specifications: json!({
            "model": "NVIDIA RTX 4090",
            "memory_gb": 24
        }),
        pricing: json!({
            "per_hour": "8.00" // USDC
        }),
    };
    provider.register_resource(resource).await;
    
    // Start provider
    provider.start().await;
}

Error Handling

// Error Response Format
{
  "error": {
    "code": "INSUFFICIENT_STAKE",
    "message": "Staking requirement not met",
    "details": {
      "required": "1000.00",
      "current": "500.00",
      "currency": "USDC"
    }
  }
}

// Common Error Codes
- INSUFFICIENT_STAKE
- RESOURCE_UNAVAILABLE
- TASK_ALREADY_ACCEPTED
- VERIFICATION_FAILED
- SLASHING_EVENT
- RATE_LIMIT_EXCEEDED