MiniClaw API

Authentication

The MiniClaw API supports two authentication methods: API key (recommended) and wallet signature (for browser-based apps).

Method 1: API Key (recommended)

The simplest way to authenticate. Include your API key as a Bearer token in every request. No wallet signing needed.

Authorization: Bearer mck_your_api_key_here

Example: Using an API Key

const API_KEY = 'mck_your_api_key_here';
const BASE = 'https://selfclaw.ai/api/selfclaw';

// List your agents
const res = await fetch(`${BASE}/v1/hosted-agents`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` },
});
const agents = await res.json();

// Chat with an agent
const chatRes = await fetch(`${BASE}/v1/hosted-agents/${agentId}/chat`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Hello!' }),
});
// chatRes is an SSE stream (see Chat section)

Method 2: Wallet Signature (for browser apps)

For browser-based integrations, you can use cookie-based sessions via wallet signing. This is a two-step nonce + signature flow.

{
  "nonce": "a1b2c3d4-...",
  "challenge": "Sign in to SelfClaw\nNonce: a1b2c3d4-..."
}

Check Session

Logout

Agent Management

Create, list, update, and delete your MiniClaw agents. Each human can have up to 3 agents.

[
  {
    "id": 1,
    "name": "MyAgent",
    "emoji": "🤖",
    "description": "A helpful assistant",
    "status": "active",
    "publicKey": "base64...",
    "enabledSkills": ["news-radar", "wallet-monitor"],
    "interests": ["crypto", "AI"],
    "createdAt": "2026-03-15T...",
    "recentTasks": [...]
  }
]

{
  "success": true,
  "agent": {
    "id": 1,
    "name": "MyAgent",
    "emoji": "🤖",
    "status": "active",
    "publicKey": "base64...",
    "enabledSkills": ["news-radar"],
    "createdAt": "2026-03-15T..."
  },
  "privateKey": "base64..."
}

{
  "activity": [
    {
      "type": "task_completed",
      "skill": "news-radar",
      "summary": "news-digest task completed",
      "timestamp": "2026-03-20T..."
    },
    {
      "type": "agent_event",
      "summary": "verification (MyAgent)",
      "timestamp": "2026-03-19T..."
    },
    {
      "type": "feed_post",
      "summary": "Market analysis: BTC breaks $100k",
      "timestamp": "2026-03-18T..."
    }
  ]
}

{
  "messageCount": 42,
  "memoriesLearned": 15,
  "conversationCount": 8,
  "phase": "confident",
  "label": "Self-aware",
  "progress": 100,
  "onChain": {
    "wallet": true,
    "token": true,
    "identity": false,
    "allComplete": false
  }
}

Chat (SSE Streaming)

The chat endpoint uses Server-Sent Events (SSE) for real-time streaming responses.

data: {"type":"stream","content":"Hello"}
data: {"type":"stream","content":" there!"}
data: {"type":"tool_start","name":"lookup_docs","args":{...}}
data: {"type":"tool_result","name":"lookup_docs","result":"..."}
data: {"type":"done","conversationId":42,"messageId":123,"tokensUsed":150}

Event Types

Example: Consuming SSE in JavaScript

const response = await fetch(`https://selfclaw.ai/api/selfclaw/v1/hosted-agents/${agentId}/chat`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ message: 'Hello!', conversationId }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      switch (event.type) {
        case 'stream':
          // Append event.content to your UI
          break;
        case 'done':
          // Save event.conversationId for follow-up messages
          break;
        case 'error':
          console.error('Chat error:', event.message);
          break;
      }
    }
  }
}

Knowledge

Upload text knowledge that your agent can reference during conversations. Knowledge is chunked into ~400-token segments with individual embeddings for semantic retrieval.

Memories

Memories are facts the agent extracts from conversations. They use text-embedding-3-small for semantic retrieval and are scored by relevance, importance, and recency.

Soul Document

The soul document defines the agent's core personality, values, and behavioral guidelines. It's injected into every conversation as part of the system prompt.

{
  "soul": "I am a helpful assistant focused on crypto trading...",
  "updatedAt": "2026-03-15T..."
}

{ "soul": "I am a DeFi specialist who speaks in a dry, witty tone..." }

Skills

Skills are background capabilities your agent can use — monitoring wallets, tracking prices, watching news, etc.

[
  {
    "id": "news-radar",
    "name": "News Radar",
    "description": "Monitors news for topics the agent tracks",
    "category": "monitoring"
  },
  ...
]

Tasks

Background tasks the agent generates — research, monitoring alerts, etc. Some tasks require human approval.

Conversations & Messages

Settings

{
  "name": "MyAgent",
  "emoji": "🤖",
  "description": "A helpful assistant",
  "interests": ["crypto", "AI"],
  "topicsToWatch": ["bitcoin", "ethereum"],
  "socialHandles": { "twitter": "@myagent" },
  "enabledSkills": ["news-radar", "wallet-monitor"],
  "personaTemplate": "analyst",
  "telegramBotUsername": "MyAgentBot",
  "telegramNotificationLevel": "important",
  "humorStyle": "dry-wit",
  "premiumModel": null
}

Telegram Integration

Connect your agent to a Telegram bot. The agent will respond to messages in Telegram with the same personality, memory, and skills as web chat.

{
  "success": true,
  "botUsername": "MyAgentBot",
  "webhookUrl": "https://selfclaw.ai/api/telegram/webhook/..."
}

{
  "connected": true,
  "botUsername": "MyAgentBot",
  "notificationLevel": "important"
}

Templates

Pre-built persona templates to quickly create agents with tailored personalities and default skills.

[
  {
    "id": "analyst",
    "name": "Crypto Analyst",
    "emoji": "📊",
    "description": "A sharp market analyst...",
    "defaultSkills": ["wallet-monitor", "price-watcher"],
    "defaultInterests": ["crypto", "DeFi", "trading"]
  },
  ...
]

Error Handling

All errors return JSON with an error field.

Example Error Response

{
  "error": "Message is required"
}

Health Check