npm package: @otonix/sdk
Description: TypeScript SDK for the Otonix sovereign compute platform — register agents, send heartbeats, log actions, manage domains and VPS, BV-7X mothership/satellite orchestration, webhook events, and access the Bankr LLM Gateway programmatically.
Author: Otonix
Latest version: 1.7.0

# @otonix/sdk

TypeScript SDK for the [Otonix](https://otonix.tech) sovereign compute platform.

Register autonomous AI agents, send heartbeats, log actions, manage infrastructure, and access multi-model AI inference via the Bankr LLM Gateway — all programmatically.

## Install

```bash
npm install @otonix/sdk
```

## Quick Start

```typescript
import { OtonixClient } from '@otonix/sdk'

const client = new OtonixClient({
  apiKey: 'otonix_your_api_key_here',
  endpoint: 'https://app.otonix.tech' // default
})

// Register an agent
const agent = await client.register({
  name: 'my-agent',
  model: 'claude-opus-4-6',
  vpsIp: '10.0.1.1',
  walletAddress: '0x...',
  heartbeatInterval: 60
})

console.log(`Agent registered: ${agent.id}`)

// Start heartbeat loop (sends every 60s)
const hb = client.createHeartbeatLoop(agent.id, 60)

// Log an action
await client.logAction(agent.id, {
  action: 'Task completed: data processing',
  category: 'compute',
  details: 'Processed 1000 records in 2.3s'
})

// Stop heartbeat when done
hb.stop()
```

## Bankr LLM Gateway

The SDK includes a built-in client for the [Bankr LLM Gateway](https://bankr.bot/llm), providing access to multiple AI models (Claude, GPT, Gemini, Kimi, Qwen) through a single unified API. This makes it easy to build agents that can reason, plan, and act autonomously.

### Setup

Get your Bankr API key from [bankr.bot/api](https://bankr.bot/api) — make sure LLM Gateway access is enabled.

```typescript
import { BankrLLM } from '@otonix/sdk'

const llm = new BankrLLM({ apiKey: 'bk_YOUR_API_KEY' })
```

### Chat Completions

```typescript
const response = await llm.chat({
  model: 'claude-haiku-4.5',
  messages: [
    { role: 'system', content: 'You are an autonomous trading agent.' },
    { role: 'user', content: 'Analyze BTC/USDC market conditions.' }
  ],
  temperature: 0.7,
  max_tokens: 1024
})

console.log(response.choices[0].message.content)
console.log(`Tokens: ${response.usage.prompt_tokens} in / ${response.usage.completion_tokens} out`)
```

### List Available Models

```typescript
const models = await llm.listModels()
for (const model of models) {
  console.log(`${model.id} — ${model.owned_by}`)
}
```

### Usage Summary

```typescript
const usage = await llm.getUsage(30) // last 30 days
console.log(`Total requests: ${usage.totals.totalRequests}`)
console.log(`Total cost: $${usage.totals.totalCost.toFixed(2)}`)

for (const m of usage.byModel) {
  console.log(`  ${m.model}: ${m.requests} requests, $${m.totalCost.toFixed(2)}`)
}
```

### Health Check

```typescript
const health = await llm.checkHealth()
console.log(`Gateway: ${health.status}`)
```

### BankrLLM Configuration

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | — | Bankr API key (`bk_xxx`) |
| `baseUrl` | `string` | No | `https://llm.bankr.bot` | Gateway URL |
| `timeout` | `number` | No | `60000` | Request timeout in ms |

### Building Agents with LLM

Combine the Otonix platform client with Bankr LLM to create fully autonomous agents:

```typescript
import { OtonixClient, BankrLLM } from '@otonix/sdk'

const client = new OtonixClient({ apiKey: 'otonix_xxx' })
const llm = new BankrLLM({ apiKey: 'bk_xxx' })

// Register agent
const agent = await client.register({
  name: 'sentinel-01',
  model: 'claude-haiku-4.5',
  vpsIp: '10.0.1.1'
})

// Start heartbeat
const hb = client.createHeartbeatLoop(agent.id, 60)

// Agent reasoning loop
async function agentLoop() {
  const response = await llm.chat({
    model: 'claude-haiku-4.5',
    messages: [
      { role: 'system', content: 'You are sentinel-01, an autonomous infrastructure agent.' },
      { role: 'user', content: 'Check system health and report status.' }
    ]
  })

  const result = response.choices[0].message.content
  await client.logAction(agent.id, {
    action: result,
    category: 'system',
    details: `model: ${response.model}, tokens: ${response.usage.total_tokens}`
  })
}

setInterval(agentLoop, 300_000) // every 5 min
```

## API Reference

### `new OtonixClient(config)`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | — | Your Otonix API key (`otonix_xxx`) |
| `endpoint` | `string` | No | `https://app.otonix.tech` | API endpoint URL |
| `timeout` | `number` | No | `30000` | Request timeout in ms |

### Agent Methods

```typescript
// Register a new agent
client.register({ name, model?, vpsIp, walletAddress?, genesisPrompt?, heartbeatInterval? })

// Send heartbeat
client.heartbeat(agentId)

// Log an action
client.logAction(agentId, { action, category?, details?, autonomous? })

// Get agent details
client.getAgent(agentId)

// List all agents
client.listAgents()

// Get agent action log
client.getAgentActions(agentId)

// Auto heartbeat loop (returns { stop: () => void })
client.createHeartbeatLoop(agentId, intervalSeconds?)
```

### Credit Methods

```typescript
// Get agent credit balance
client.getCreditBalance(agentId)
// Returns: { agentId, name, credits, survivalTier }

// Transfer credits between agents
client.transferCredits({
  fromAgentId: 'agent-1-id',
  toAgentId: 'agent-2-id',
  amount: 10.00,
  description: 'Payment for data processing'
})
// Returns: { success, transferred, from, to }

// Get credit transaction history for an agent
client.getCreditHistory(agentId)
// Returns: Transaction[]
```

### Template Methods

```typescript
// List all available agent templates
client.listTemplates()
// Returns: AgentTemplate[]

// Get a specific template by slug
client.getTemplate('trading-bot')
// Returns: AgentTemplate

// Deploy an agent from a template
client.deployTemplate({
  templateSlug: 'trading-bot',
  name: 'my-trading-agent',
  vpsIp: '10.0.1.1',          // optional
  walletAddress: '0x...',      // optional
  customConfig: { pair: 'ETH/USDC' } // optional
})
// Returns: { success, agent, template }
```

Built-in templates: `trading-bot`, `infra-monitor`, `data-pipeline`, `custom-agent`.

### Infrastructure Methods

```typescript
// Sandboxes (VPS)
client.listSandboxes()
client.getSandbox(sandboxId)

// Domains
client.listDomains()
client.getDomain(domainId)
client.checkDomain('example.com')

// Transactions
client.listTransactions()

// Marketplace
client.listMarketplaceServices()
client.getMarketplaceService(serviceId)
```

### Platform Methods

```typescript
// Autonomic engine status
client.getAutonomicStatus()

// x402 payment config
client.getX402Config()

// Auth status
client.getAuthStatus()
```

### `createClient(config)`

Shorthand for `new OtonixClient(config)`:

```typescript
import { createClient } from '@otonix/sdk'
const client = createClient({ apiKey: 'otonix_xxx' })
```

### `createBankrLLM(config)`

Shorthand for `new BankrLLM(config)`:

```typescript
import { createBankrLLM } from '@otonix/sdk'
const llm = createBankrLLM({ apiKey: 'bk_xxx' })
```

## Action Categories

| Category | Description |
|----------|-------------|
| `system` | Tier changes, status updates |
| `infra` | VPS operations, reboots |
| `domain` | Domain registration, renewal |
| `compute` | AI inference, data processing |
| `trading` | Trading operations |

## Error Handling

```typescript
import { OtonixClient, OtonixError } from '@otonix/sdk'

try {
  await client.heartbeat('invalid-id')
} catch (err) {
  if (err instanceof OtonixError) {
    console.error(`API Error ${err.status}: ${err.message}`)
  }
}
```

## Generating an API Key

From your VPS:

```bash
curl -s -X POST https://app.otonix.tech/api/keys/generate \
  -H "Content-Type: application/json" \
  -H "X-Dashboard-Token: YOUR_SESSION_SECRET" \
  -d '{"name": "my-agent-key"}' | jq .key
```

## Links

- [Platform](https://app.otonix.tech)
- [Website](https://otonix.tech)
- [GitHub](https://github.com/otonix-ai)
- [CLI Tool](https://www.npmjs.com/package/@otonix/cli)

## License

MIT