Skip to Content
SDK

SDK (@hatcher/sdk)

The official TypeScript/JavaScript SDK for the Hatcher API. Zero dependencies, uses native fetch (Node.js 18+ or browser).

Installation

npm install @hatcher/sdk

Quick Start

import { HatcherClient } from '@hatcher/sdk';
 
const hatcher = new HatcherClient({ apiKey: 'hk_your_api_key' });
 
// List all agents
const agents = await hatcher.listAgents();
console.log(agents);
 
// Chat with an agent
const response = await hatcher.chat('agent-id', 'Hello!');
console.log(response.content);

Constructor

const hatcher = new HatcherClient({
  apiKey: 'hk_...',             // Required. Your Hatcher API key.
  baseUrl: 'https://...',       // Optional. Defaults to https://api.hatcher.host/api/v1
  fetch: customFetch,           // Optional. Custom fetch implementation.
});

API keys must start with hk_. Get yours from Dashboard > Settings > API Keys.

Agents

listAgents()

List all agents belonging to the authenticated user.

const agents = await hatcher.listAgents();
// Returns: AgentSummary[]

Each AgentSummary includes: id, name, slug, status, framework, messageCount, createdAt.

getAgent(id)

Get detailed information about a specific agent.

const agent = await hatcher.getAgent('agent-id');
// Returns: Agent (includes config, features, description, avatarUrl, etc.)

createAgent(data)

Create a new agent.

const agent = await hatcher.createAgent({
  name: 'My Agent',
  framework: 'openclaw',        // 'openclaw' | 'hermes'
  description: 'A helpful agent', // optional
  config: {
    model: {
      provider: 'openrouter',
      model: 'deepseek/deepseek-v4-flash',
    },
  }, // optional
});

updateAgent(id, data)

Update an existing agent’s name, description, or config.

const updated = await hatcher.updateAgent('agent-id', {
  name: 'New Name',
  description: 'Updated description',
  config: { personality: 'New personality' },
});

deleteAgent(id)

Permanently delete an agent and its container.

await hatcher.deleteAgent('agent-id');

Chat

chat(agentId, message, options?)

Send a message to an agent and get a response.

const response = await hatcher.chat('agent-id', 'What is the weather?');
console.log(response.content); // Agent's reply
console.log(response.model);   // LLM model used

With conversation history:

const response = await hatcher.chat('agent-id', 'And tomorrow?', {
  history: [
    { role: 'user', content: 'What is the weather?' },
    { role: 'assistant', content: 'It is sunny today.' },
  ],
});

streamChat(agentId, message, onToken)

Stream a chat response token by token using Server-Sent Events.

const fullResponse = await hatcher.streamChat(
  'agent-id',
  'Tell me a story',
  (token) => process.stdout.write(token),
);

Falls back to non-streaming chat() if the server does not support streaming for the agent.

Lifecycle

startAgent(id)

Start an agent’s container.

await hatcher.startAgent('agent-id');

stopAgent(id)

Stop an agent’s container.

await hatcher.stopAgent('agent-id');

restartAgent(id)

Restart an agent’s container.

await hatcher.restartAgent('agent-id');

getAgentStatus(id)

Get the current status of an agent (lightweight, no full config).

const status = await hatcher.getAgentStatus('agent-id');
// Returns: { status, containerId, messageCount }

Account

getAccount()

Get the authenticated user’s account info.

const account = await hatcher.getAccount();
// Returns account profile fields, referral code, wallet address, and AI Credit balance fields when available.

getUsage()

Get API usage stats for the current day.

const usage = await hatcher.getUsage();
// Returns current API usage and AI-credit-backed hosted usage metadata when available.

Error Handling

The SDK throws typed errors for different failure modes:

import {
  HatcherError,
  HatcherAuthError,
  HatcherNotFoundError,
  HatcherRateLimitError,
  HatcherValidationError,
} from '@hatcher/sdk';
 
try {
  await hatcher.chat('agent-id', 'Hello');
} catch (err) {
  if (err instanceof HatcherAuthError) {
    // 401 -- invalid or expired API key
    console.error('Auth failed:', err.message);
  } else if (err instanceof HatcherNotFoundError) {
    // 404 -- agent does not exist
    console.error('Not found:', err.message);
  } else if (err instanceof HatcherRateLimitError) {
    // 429 -- rate limit exceeded
    console.error('Rate limited:', err.message);
    console.error('Resets at:', err.rateLimitInfo?.resetAt);
  } else if (err instanceof HatcherValidationError) {
    // 400/422 -- invalid input
    console.error('Validation:', err.message);
  } else if (err instanceof HatcherError) {
    // Any other API error
    console.error(`Error ${err.status}:`, err.message);
  }
}

All errors extend HatcherError which has:

  • status — HTTP status code
  • message — Error description
  • rateLimitInfo — (on 429 only) { limit, remaining, resetAt }

TypeScript Types

All types are exported for use in your code:

import type {
  Agent,
  AgentSummary,
  AgentFramework,      // 'openclaw' | 'hermes'
  AgentStatusValue,    // 'active' | 'paused' | 'building' | 'error' | 'sleeping'
  AgentStatus,
  AgentFeature,
  CreateAgentInput,
  UpdateAgentInput,
  ChatResponse,
  ChatOptions,
  Message,
  Account,
  Usage,
  HatcherClientOptions,
  HatcherErrorDetails,
} from '@hatcher/sdk';
Last updated on
Platform FeaturesSkills & Plugins