SDK reference

TypeScript SDK for integrating SadClaw into your applications and agents.

Installation

npm install @sadclaw/sdk

Quick Start

import { SadClawClient } from '@sadclaw/sdk';
import { Keypair } from '@solana/web3.js';

// Initialize client
const client = new SadClawClient({
  rpcUrl: 'https://api.mainnet-beta.solana.com',
  keypair: myKeypair,
});

// Purchase a VM
const vm = await client.purchaseVm({
  tier: 'STANDARD',
  durationHours: 24,
});

// Get SSH credentials
const ssh = await client.getSshCredentials(vm.nftMint);
console.log(`ssh ${ssh.username}@${ssh.host}`);

SadClawClient

Constructor

new SadClawClient(config: SadClawConfig)

SadClawConfig:

Property	Type	Description	Default
rpcUrl	string	Solana RPC URL	Required
keypair	Keypair	Wallet keypair	Required
programId	string	SadClaw program ID	Default program
apiUrl	string	SadClaw API URL	Production API

Example:

import { Keypair } from '@solana/web3.js';
import { SadClawClient } from '@sadclaw/sdk';

const keypair = Keypair.fromSecretKey(
  Buffer.from(process.env.WALLET_SECRET_KEY, 'base64')
);

const client = new SadClawClient({
  rpcUrl: process.env.SOLANA_RPC_URL,
  keypair,
});

Properties

wallet

get wallet(): PublicKey

Returns the wallet public key.

console.log(client.wallet.toBase58());
// 7xKX...abc123

Methods

getTiers()

Get available VM tiers.

async getTiers(): Promise<VmTier[]>

Returns: Array of VmTier

interface VmTier {
  id: number;
  name: string;
  pricePerHour: number;
  vcpusMin: number;
  vcpusMax: number;
  ramGbMin: number;
  ramGbMax: number;
}

Example:

const tiers = await client.getTiers();

for (const tier of tiers) {
  console.log(`${tier.name}: $${tier.pricePerHour}/hr`);
}

listVms()

List VMs owned by the wallet.

async listVms(): Promise<VmInstance[]>

Returns: Array of VmInstance

interface VmInstance {
  id: string;
  nftMint: string;
  tier: string;
  status: 'pending' | 'provisioning' | 'active' | 'expired' | 'destroyed';
  ipAddress?: string;
  region: string;
  createdAt: Date;
  expiresAt: Date;
}

Example:

const vms = await client.listVms();

const activeVms = vms.filter(vm => vm.status === 'active');
console.log(`You have ${activeVms.length} active VMs`);

getVm()

Get a specific VM by NFT mint.

async getVm(nftMint: string): Promise<VmInstance | null>

Parameters:

Parameter	Type	Description
nftMint	string	NFT mint address

Returns: VmInstance or null if not found

Example:

const vm = await client.getVm('9abc...xyz789');

if (vm) {
  console.log(`Status: ${vm.status}`);
  console.log(`IP: ${vm.ipAddress}`);
}

purchaseVm()

Purchase a new VM.

async purchaseVm(options: PurchaseOptions): Promise<VmInstance>

PurchaseOptions:

Property	Type	Description	Default
tier	'MICRO' | 'SMALL' | 'STANDARD' | 'LARGE' | 'XLARGE'	VM tier	Required
durationHours	number	Duration in hours (1-720)	Required
region	string	Region code	'fsn1'

Returns: VmInstance

Example:

const vm = await client.purchaseVm({
  tier: 'STANDARD',
  durationHours: 24,
  region: 'hel1',
});

console.log(`VM purchased: ${vm.nftMint}`);
console.log(`IP: ${vm.ipAddress}`);
console.log(`Expires: ${vm.expiresAt}`);

getSshCredentials()

Get SSH credentials for a VM.

async getSshCredentials(nftMint: string): Promise<SshCredentials>

Parameters:

Parameter	Type	Description
nftMint	string	NFT mint address

Returns: SshCredentials

interface SshCredentials {
  host: string;
  port: number;
  username: string;
  privateKey: string;
}

Example:

const ssh = await client.getSshCredentials(vm.nftMint);

console.log(`SSH command: ssh -i key.pem ${ssh.username}@${ssh.host}`);

// Save private key to file
fs.writeFileSync('key.pem', ssh.privateKey, { mode: 0o600 });

extendVm()

Extend a VM's duration.

async extendVm(nftMint: string, additionalHours: number): Promise<VmInstance>

Parameters:

Parameter	Type	Description
nftMint	string	NFT mint address
additionalHours	number	Hours to add

Returns: Updated VmInstance

Example:

const updated = await client.extendVm(vm.nftMint, 24);
console.log(`New expiration: ${updated.expiresAt}`);

destroyVm()

Destroy a VM (burns the NFT).

async destroyVm(nftMint: string): Promise<void>

Parameters:

Parameter	Type	Description
nftMint	string	NFT mint address

Example:

await client.destroyVm(vm.nftMint);
console.log('VM destroyed');

This is irreversible. The VM and all its data will be permanently deleted.

Error Handling

The SDK throws typed errors:

import { SadClawError, InsufficientFundsError, VmNotFoundError } from '@sadclaw/sdk';

try {
  await client.purchaseVm({ tier: 'STANDARD', durationHours: 24 });
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.log(`Need ${error.required} USDC, have ${error.available}`);
  } else if (error instanceof VmNotFoundError) {
    console.log('VM not found');
  } else if (error instanceof SadClawError) {
    console.log(`SadClaw error: ${error.message}`);
  } else {
    throw error;
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

import {
  SadClawClient,
  SadClawConfig,
  VmTier,
  VmInstance,
  SshCredentials,
  PurchaseOptions,
} from '@sadclaw/sdk';

Examples

Auto-scaling Agent

async function autoScale(client: SadClawClient, workload: number) {
  const vms = await client.listVms();
  const activeVms = vms.filter(vm => vm.status === 'active');

  const targetVms = Math.ceil(workload / 100);

  if (activeVms.length < targetVms) {
    // Scale up
    const needed = targetVms - activeVms.length;
    for (let i = 0; i < needed; i++) {
      await client.purchaseVm({ tier: 'STANDARD', durationHours: 6 });
    }
  } else if (activeVms.length > targetVms + 1) {
    // Scale down
    const excess = activeVms.length - targetVms;
    const toRemove = activeVms.slice(0, excess);
    for (const vm of toRemove) {
      await client.destroyVm(vm.nftMint);
    }
  }
}

SSH Connection Helper

import { NodeSSH } from 'node-ssh';

async function connectToVm(client: SadClawClient, nftMint: string) {
  const ssh = await client.getSshCredentials(nftMint);

  const connection = new NodeSSH();
  await connection.connect({
    host: ssh.host,
    port: ssh.port,
    username: ssh.username,
    privateKey: ssh.privateKey,
  });

  return connection;
}

// Usage
const conn = await connectToVm(client, vm.nftMint);
const result = await conn.execCommand('uname -a');
console.log(result.stdout);