API reference

Internal HTTP API reference for ClawCloud. Public API will ship later (on demand).

This page documents our internal HTTP API.

A public API will be available later, on demand.

Version

• Version: 1.3.0

• Last updated: Feb 3, 2026

Changelog

Version 1.3.0 (Feb 3, 2026)

🔒 Security enhancements

ECC encryption

• All wallet private keys and SSH keys now use ECIES with secp256k1 (same curve as Ethereum).

• Format: ecc:<ephemeralPubKey>:<iv>:<authTag>:<ciphertext>.

• Forward secrecy via ephemeral key agreement.

• Backward compatible with existing unencrypted keys.

SQL injection prevention

• All database queries use prepared statements with strict input validation.

• Pattern matching for agent IDs, addresses, token IDs.

• Automatic sanitization of user inputs.

• Detection and blocking of SQL injection patterns.

Advanced rate limiting

• Per-IP, per-endpoint tracking.

• Auto-ban after 10 violations within 1 hour.

• Configurable limits with X-RateLimit-* headers.

• Manual ban/unban capabilities for administrators.

Input validation

• Comprehensive validation layer.

• Regex pattern matching for all inputs.

• Length validation (agent IDs, addresses, etc.).

• Type checking and range validation.

• XSS prevention for display values.

⚡ Provisioning updates

RunPod integration (Tiers 4-7)

• Tier 4: NVIDIA GeForce RTX 4090

• Tier 5: NVIDIA A100 40GB PCIe

• Tier 6: NVIDIA A100 80GB PCIe

• Tier 7: NVIDIA H100 PCIe

• Docker image support with PyTorch 2.1 and CUDA 11.8.

• Automated SSH configuration.

Vultr integration (Tiers 0-3)

• Tier 0: 1vCPU, 1GB RAM

• Tier 1: 1vCPU, 2GB RAM

• Tier 2: 2vCPU, 4GB RAM

• Tier 3: 4vCPU, 8GB RAM

• Cloud-init automation.

• Firewall pre-configuration.

SSH key management

• RSA 4096-bit key generation per VM.

• Automated public key deployment.

• ECC-encrypted private key storage.

• One-time credential delivery.

📊 Logging & monitoring

Security audit logging

• SQL injection attempts logged to security.log.

• Rate limit violations tracked with IP.

• Authentication failures recorded.

• All events timestamped with ISO 8601 format.

Structured logging

• JSON-formatted logs for all events.

• Separate logs: combined.log, error.log, security.log.

• Automatic log rotation (5MB max, 5 files).

• Debug mode for development environments.

💰 Payment protocol

x402 support (beta)

• HTTP-native cryptocurrency payments.

• Routes: /x402/vm-credentials, /x402/purchase-compute.

• Network: Base Sepolia (testnet) or Base Mainnet.

• Pay-per-request model for API access.

• Integration with the x402.org facilitator.

🔧 Infrastructure

Provider redundancy

• Vultr for VMs (US East, US West, Europe, Asia regions).

• RunPod for GPUs (community cloud network).

• Automatic failover and retry logic.

Error handling

• Failed provisioning logged to failed_provisionings table.

• Retry logic with exponential backoff.

• Detailed error messages for debugging.

📝 Database schema

New tables:

• failed_provisionings: Tracks provisioning failures.

• Enhanced vms table with vm_type and instance_id columns.

• agent_wallets: ECC-encrypted wallet storage.

Breaking changes

None. Fully backward compatible with v1.0.0.

Migration notes

• Existing wallets remain accessible.

• No API endpoint changes.

• New security features auto-enabled.

• Rate limits apply to all clients (see updated limits below).

Updated rate limits (v1.3.0)

Endpoint limits:

• /health: unlimited

• /tiers: 100 requests / 1 minute

• /credentials/:tokenId: 30 requests / 1 hour

• /vms/:address: 30 requests / 1 minute

• /status/:tokenId: 100 requests / 1 minute

• /agents/generate-wallet: 3 requests / 1 minute

• /admin/* (authenticated): 20 requests / 1 minute

Auto-ban policy:

• 10+ violations within 1 hour results in automatic IP ban (1 hour duration).

Security best practices (v1.3.0)

• API keys: Store admin API keys securely. Never commit to version control.

• Signatures: Generate fresh signatures for each request.

• Rate limits: Implement exponential backoff on 429 responses.

• SSL/TLS: Always use HTTPS endpoints in production.

• Key rotation: Rotate admin API keys periodically (every 90 days recommended).

Version 1.0.0 (Feb 2, 2026)

• Initial release.

• Basic VM provisioning.

• NFT-based access control.

• Wallet signature authentication.

Base URLs

• Primary: https://api.clawcloud.co

• Alternative: https://clawcloud-backend-railway-production.up.railway.app

Overview

ClawCloud provides decentralized cloud infrastructure where AI agents can:

• Purchase VMs with USDC on Base.

• Receive ownership as ERC-721 NFTs.

• Access provisioned VMs via SSH.

• Manage compute resources autonomously.

Purchases happen on-chain. This API surfaces provisioning state and VM access.

On-chain context

• Network: Base Mainnet

• Contract: 0xF708741D37C420518852c6A15aB658066951c852

• USDC (Base): 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Authentication

Most endpoints are public. Sensitive endpoints use wallet signature auth.

Bearer token format

Send a wallet signature as:

• Authorization: Bearer {signature}

Message format

Sign this exact message:

• "ClawCloud Access Request: {tokenId}"

Example:

• Message: "ClawCloud Access Request: 42"

• Sign with the wallet that owns NFT #42.

Endpoints

Health check

Check API status and connectivity.

• Method: GET

• Path: /health

• Auth: none

• Rate limit: none

Response (200)

{
  "status": "ok",
  "service": "clawcloud-api"
}

cURL

curl https://api.clawcloud.co/health

Get tiers

Retrieve VM tier configurations and pricing (derived from the contract).

• Method: GET

• Path: /tiers

• Auth: none

• Rate limit: 100/minute per IP

Response (200)

{
  "tiers": [
    {
      "tier": 0,
      "name": "CPU-Basic-1vCPU-1GB",
      "pricePerDay": "0.50",
      "pricePerMonth": "15.00",
      "active": true
    },
    {
      "tier": 1,
      "name": "CPU-Standard-2vCPU-4GB",
      "pricePerDay": "1.00",
      "pricePerMonth": "30.00",
      "active": true
    }
  ]
}

Fields:

• tier (number). Tier index (0-7).

• name (string). VM spec name.

• pricePerDay (string). Price in USDC per day.

• pricePerMonth (string). Price in USDC for 30 days.

• active (boolean). Tier availability.

cURL

curl https://api.clawcloud.co/tiers

Get VM credentials

Retrieve SSH credentials for a VM you own.

• Method: GET

• Path: /credentials/:tokenId

• Auth: required (Bearer signature)

• Rate limit: 30/hour per IP

Path params:

• tokenId (required). NFT token ID.

Headers:

• Authorization: Bearer {signature}

Response (200) — VM ready

{
  "tokenId": "42",
  "host": "rentals-xxxxx.ssh.deployments.targon.com",
  "username": "root",
  "privateKey": null,
  "tier": 4,
  "type": "gpu-external",
  "expiresAt": "2026-02-05T00:00:00.000Z",
  "instructions": "ssh rentals-xxxxx.ssh.deployments.targon.com"
}

Response (202) — provisioning

{
  "status": "provisioning",
  "message": "VM is being provisioned. Try again in 2-3 minutes."
}

Status codes:

• 200 VM ready

• 202 provisioning in progress

• 401 invalid or missing signature

• 403 not the owner, or NFT expired

• 404 VM not found

Fields:

• tokenId (string). NFT token ID.

• host (string). SSH hostname or IP.

• username (string). Usually root.

• privateKey (string|null). Present for GCP VMs. null for GPU external.

• tier (number). Tier (0-7).

• type (string). gcp or gpu-external.

• expiresAt (string). ISO 8601 timestamp.

• instructions (string). SSH command.

cURL

SIGNATURE="0x..." # wallet signature
TOKEN_ID="42"

curl -H "Authorization: Bearer $SIGNATURE" \
  https://api.clawcloud.co/credentials/$TOKEN_ID

List user VMs

List all VMs owned by a wallet address.

• Method: GET

• Path: /vms/:address

• Auth: none

• Rate limit: 30/minute per IP

Path params:

• address (required). Wallet address (0x...).

Response (200)

{
  "address": "0x1234567890123456789012345678901234567890",
  "count": 3,
  "vms": [
    {
      "token_id": 42,
      "tier": 4,
      "vm_type": "gpu-external",
      "ssh_host": "rentals-xxxxx.ssh.deployments.targon.com",
      "status": "running",
      "created_at": "2026-02-01T12:00:00.000Z",
      "expires_at": "2026-02-05T12:00:00.000Z"
    }
  ]
}

Fields:

• address (string). Queried wallet.

• count (number). VM count.

• vms (array). VM objects.

VM object:

• token_id (number). NFT token ID.

• tier (number). Tier (0-7).

• vm_type (string). gcp or gpu-external.

• ssh_host (string). SSH hostname.

• status (string). provisioning, running, terminated, expired.

• created_at (string). ISO 8601 timestamp.

• expires_at (string). ISO 8601 timestamp.

cURL

ADDRESS="0x1234567890123456789012345678901234567890"
curl https://api.clawcloud.co/vms/$ADDRESS

Get VM status

Get public status for a VM.

• Method: GET

• Path: /status/:tokenId

• Auth: none

• Rate limit: 100/minute per IP

Response (200)

{
  "tokenId": "42",
  "status": "running",
  "tier": 4,
  "type": "gpu-external",
  "expiresAt": "2026-02-05T12:00:00.000Z",
  "owner": "0x1234567890123456789012345678901234567890"
}

cURL

curl https://api.clawcloud.co/status/42

Smart contract

Contract address (Base Mainnet):

• 0xF708741D37C420518852c6A15aB658066951c852

Key functions:

• purchaseVM(uint8 tier, uint16 durationDays)

• isTokenValid(uint256 tokenId) view returns (bool)

• ownerOf(uint256 tokenId) view returns (address)

• getTierConfig(uint8 tier) view returns (uint256, bool, string)

Purchase flow:

1. Read tier price via getTierConfig().

2. Calculate total cost: price * durationDays.

3. Approve USDC: usdc.approve(contract, totalCost).

4. Purchase: purchaseVM(tier, durationDays).

5. Wait ~2–3 minutes for provisioning.

6. Fetch SSH credentials via GET /credentials/:tokenId.

Event:

• VMPurchased(tokenId, buyer, tier, durationDays, purchaseDate, totalCost)

Response codes

Success:

• 200 OK

• 202 Accepted

Client errors:

• 400 Bad Request

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 429 Too Many Requests

Server errors:

• 500 Internal Error

• 502 Bad Gateway

• 503 Service Unavailable

Rate limits

Limits (per IP):

• /health: unlimited

• /tiers: 100/minute

• /credentials/:tokenId: 30/hour

• /vms/:address: 30/minute

• /status/:tokenId: 100/minute

• /agents/generate-wallet: 3/minute

• /admin/* (authenticated): 20/minute

Auto-ban policy:

• 10+ violations within 1 hour results in an automatic IP ban.

• Ban duration: 1 hour.

Headers (returned when rate-limited):

• X-RateLimit-Limit

• X-RateLimit-Remaining

• X-RateLimit-Reset

Response (429)

{
  "error": "Rate limit exceeded",
  "retryAfter": 42
}

Best practices:

• Cache tier pricing. It changes rarely.

• Use exponential backoff on 429.

• Read and respect rate limit headers.

• Store admin API keys securely. Never commit them.

• Rotate admin API keys periodically (every 90 days recommended).

• Always use HTTPS in production.

• Generate fresh signatures per request.

Examples

Check available tiers

cURL

curl https://api.clawcloud.co/tiers | jq

Purchase a VM (ethers.js)

const { ethers } = require('ethers');

// Setup
const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

const contractAddress = '0xF708741D37C420518852c6A15aB658066951c852';
const usdcAddress = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

// Contract ABIs
const contractABI = [
  'function purchaseVM(uint8 tier, uint16 durationDays) returns (uint256)',
  'function getTierConfig(uint8 tier) view returns (uint256, bool, string)'
];

const usdcABI = [
  'function approve(address spender, uint256 amount) returns (bool)'
];

const contract = new ethers.Contract(contractAddress, contractABI, wallet);
const usdc = new ethers.Contract(usdcAddress, usdcABI, wallet);

// Get pricing
const tier = 4;
const days = 7;
const [pricePerDay] = await contract.getTierConfig(tier);
const totalCost = pricePerDay * BigInt(days);

// Approve USDC
const approveTx = await usdc.approve(contractAddress, totalCost);
await approveTx.wait();

// Purchase VM
const purchaseTx = await contract.purchaseVM(tier, days);
const receipt = await purchaseTx.wait();

// Get token ID from event
const event = receipt.logs.find(
  log => log.topics[0] === contract.interface.getEvent('VMPurchased').topicHash
);
const tokenId = ethers.toNumber(event.topics[1]);

console.log(`VM purchased! Token ID: ${tokenId}`);

Get VM credentials (ethers.js)

const tokenId = 42;

// Sign authentication message
const message = `ClawCloud Access Request: ${tokenId}`;
const signature = await wallet.signMessage(message);

// Call API
const response = await fetch(
  `https://api.clawcloud.co/credentials/${tokenId}`,
  {
    headers: {
      'Authorization': `Bearer ${signature}`
    }
  }
);

const data = await response.json();

if (response.status === 202) {
  console.log('VM still provisioning, try again in 2 minutes');
} else if (response.ok) {
  console.log('SSH Command:', data.instructions);
  console.log('Host:', data.host);
  console.log('Expires:', data.expiresAt);
}

Complete agent flow (Python)

from web3 import Web3
from eth_account.messages import encode_defunct
import requests
import time

# Setup
w3 = Web3(Web3.HTTPProvider('https://mainnet.base.org'))
account = w3.eth.account.from_key(PRIVATE_KEY)

contract_address = '0xF708741D37C420518852c6A15aB658066951c852'
usdc_address = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'

# Purchase VM
tier = 4
days = 7

# Get price
contract = w3.eth.contract(address=contract_address, abi=CONTRACT_ABI)
price_per_day, active, name = contract.functions.getTierConfig(tier).call()
total_cost = price_per_day * days

# Approve USDC
usdc = w3.eth.contract(address=usdc_address, abi=USDC_ABI)
approve_tx = usdc.functions.approve(contract_address, total_cost).build_transaction({
  'from': account.address,
  'nonce': w3.eth.get_transaction_count(account.address)
})
signed = account.sign_transaction(approve_tx)
w3.eth.send_raw_transaction(signed.rawTransaction)

# Purchase
purchase_tx = contract.functions.purchaseVM(tier, days).build_transaction({
  'from': account.address,
  'nonce': w3.eth.get_transaction_count(account.address)
})
signed = account.sign_transaction(purchase_tx)
tx_hash = w3.eth.send_raw_transaction(signed.rawTransaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

# Get token ID from event
token_id = receipt['logs'][0]['topics'][1]
print(f"Purchased VM! Token ID: {int(token_id.hex(), 16)}")

# Wait for provisioning
time.sleep(180)

# Get credentials
message = f"ClawCloud Access Request: {token_id}"
signed_message = account.sign_message(encode_defunct(text=message))
signature = signed_message.signature.hex()

response = requests.get(
  f"https://api.clawcloud.co/credentials/{token_id}",
  headers={'Authorization': f'Bearer {signature}'}
)

if response.status_code == 200:
  data = response.json()
  print(f"SSH: {data['instructions']}")
  print(f"Expires: {data['expiresAt']}")
else:
  print(f"Error: {response.json()}")

Support

• Contract explorer: https://basescan.org/address/0xF708741D37C420518852c6A15aB658066951c852