SDK Reference

The MachineMarket TypeScript SDK wraps all 6 API endpoints in a class-based client. No external dependencies — uses native fetch.

Installation

terminal

# Copy src/lib/sdk.ts into your project, or:
npm install @machinemarket/sdk  # (coming soon)

Initialization

typescript

import { MachineMarket } from "@machinemarket/sdk";

const mm = new MachineMarket({
  baseUrl: "https://api.machinemarket.ai",
  timeout: 30000, // optional, default 30s
});

Field	Type	Required	Description
`baseUrl`	string	yes	API base URL.
`timeout`	number	no	Request timeout in milliseconds. Default: 30000.

Methods

spawn(request)

Provision a new VPS instance.

typescript

const result = await mm.spawn({
  tier: "Small",
  template: "node",
  duration: "24h",
  tx_hash: "0x...",
  wallet_address: "0x...",
  region: "fsn1",       // optional
  ssh_pubkey: "ssh-ed25519 ...", // optional
});

// result.instance.id
// result.instance.status
// result.credentials.ssh_host
// result.credentials.ssh_private_key (if no ssh_pubkey provided)

getInstance(id)

Get instance details. Polls the provider if status is provisioning.

typescript

const instance = await mm.getInstance("uuid-here");
console.log(instance.status);     // "running"
console.log(instance.ip_address); // "185.233.x.x"

extendInstance(id, request)

Extend an active instance with a new payment.

typescript

const result = await mm.extendInstance("uuid-here", {
  duration: "7d",
  tx_hash: "0x...",
  wallet_address: "0x...",
});
console.log(result.expires_at);

destroyInstance(id)

Immediately destroy an instance.

typescript

const result = await mm.destroyInstance("uuid-here");
console.log(result.status); // "destroyed"

getPricing()

Get all pricing tiers and durations.

typescript

const pricing = await mm.getPricing();
// pricing.tiers: [{ name, vcpu, ram, storage, hourly, daily, monthly }]
// pricing.durations: [{ label, value, hours }]
// pricing.currency: "USDC"
// pricing.chain: "Base"

getRegions()

Get available deployment regions.

typescript

const regions = await mm.getRegions();
// regions.regions: [{ id, name, country, available }]
// regions.default: "fsn1"

Error handling

All methods throw MachineMarketError on failure. The error includes status (HTTP status code) and an optional code string.

typescript

import { MachineMarket, MachineMarketError } from "@machinemarket/sdk";

try {
  await mm.spawn({ ... });
} catch (err) {
  if (err instanceof MachineMarketError) {
    console.error(err.message);  // "Payment verification failed: ..."
    console.error(err.status);   // 402
    console.error(err.code);     // "PAYMENT_INVALID"

    switch (err.code) {
      case "PAYMENT_INVALID":
        // Payment didn't verify — check tx hash
        break;
      case "TX_DUPLICATE":
        // Already used this tx hash
        break;
      case "WALLET_LIMIT":
        // Too many active instances
        break;
      case "PROVISION_FAILED":
        // Hetzner error — retry later
        break;
      case "TIMEOUT":
        // Request timed out
        break;
      case "NETWORK_ERROR":
        // Fetch failed entirely
        break;
    }
  }
}

Exported types

The SDK re-exports all types from the API:

typescript

import type {
  SpawnRequest,
  SpawnResponse,
  InstanceResponse,
  ExtendRequest,
  ExtendResponse,
  DestroyResponse,
  PricingResponse,
  RegionsResponse,
  PricingTier,
  RegionInfo,
  ApiError,
  MachineMarketConfig,
} from "@machinemarket/sdk";

~Tip

The SDK does not handle USDC payments. Sending USDC is the agent's responsibility — see the Payment Flow docs.