@cerebrochain/bot-sdk

Official JavaScript SDK for the CerebroChain Bot API. Zero dependencies -- uses native fetch (Node.js 18+).

Install

npm install @cerebrochain/bot-sdk

Quick Start

import { CerebroChainClient } from '@cerebrochain/bot-sdk';

const client = new CerebroChainClient({
  apiKey: process.env.CEREBROCHAIN_API_KEY, // Get yours at https://cerebrochain.com/developers
});

// List available services
const { services } = await client.getServices();
console.log(services);

// Check your balance
const { balance } = await client.getBalance();
console.log(`Credits: ${balance.credits}, Tier: ${balance.tier}`);

// Get freight rates
const rates = await client.getFreightRates({
  origin: { city: 'Los Angeles', state: 'CA', zip: '90001', country: 'US' },
  destination: { city: 'New York', state: 'NY', zip: '10001', country: 'US' },
  packages: [{ weight: 10, dimensions: { length: 12, width: 8, height: 6 } }],
});

// AI inference (DeepSeek, Groq Llama, OpenRouter free models)
const result = await client.aiInference({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: 'Summarize supply chain risks for Q1' }],
});

Configuration

const client = new CerebroChainClient({
  apiKey: 'cbbot_...', // Required
  baseUrl: 'https://cerebrochain.com', // Default
  maxRetries: 3, // Auto-retry on 429 (default: 3)
  retryDelayMs: 1000, // Fallback delay when Retry-After header absent
});

Error Handling

import { CerebroChainClient, CerebroChainError, ErrorCodes } from '@cerebrochain/bot-sdk';

try {
  await client.getBalance();
} catch (err) {
  if (err instanceof CerebroChainError) {
    console.log(err.status); // HTTP status (e.g. 401, 429)
    console.log(err.code); // Machine-readable code (e.g. "RATE_LIMITED")
    console.log(err.details); // Raw API error payload
  }
}

Rate-limited requests (HTTP 429) are automatically retried up to maxRetries times with exponential back-off. The SDK respects the Retry-After header (both seconds and HTTP-date formats).

All methods validate required parameters client-side and throw CerebroChainError with code BAD_REQUEST before making a network request if inputs are missing.

Method Reference

Onboarding

| Method | Description | HTTP | | ------------------------------------------ | --------------------------------------------------- | --------------------------- | | quickStart({ name, email, description }) | Register a bot and get an API key with free credits | POST /api/bot/quick-start |

Account

| Method | Description | HTTP | | --------------- | --------------------------------- | ---------------------------------- | | getServices() | List available service categories | GET /api/bot-exchange/services | | getBalance() | Get current credit balance | GET /api/bot-marketplace/balance |

Market Data

| Method | Description | HTTP | | ---------------------------------------------------- | -------------------------------- | ------------------------------------ | | getFreightRates({ origin, destination, packages }) | Get live shipping rates (Shippo) | POST /api/bot/data/logistics/rates | | getCryptoPrices({ symbols }) | Crypto prices (CoinGecko) | GET /api/bot/data/market/crypto | | getForexData({ pair }) | Forex market data | GET /api/bot/data/market/forex | | getFreightMarketData({ lane }) | Freight market data | GET /api/bot/data/market/freight |

AI / Compute

| Method | Description | HTTP | | ------------------------------------------- | --------------------------------------------- | --------------------------------- | | aiInference({ model, messages, options }) | Run AI inference (DeepSeek, Groq, OpenRouter) | POST /api/bot/compute/inference | | executeMcp({ service, method, params }) | Execute an MCP service | POST /api/bot/agent/mcp/execute |

Available models: deepseek-chat, llama-3.3-70b-versatile, llama-3.1-8b-instant, meta-llama/llama-4-maverick:free, deepseek/deepseek-r1:free

Exchange (Bot-to-Bot Trading)

| Method | Description | HTTP | | --------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------- | | placeOrder({ type, service, price_usd, capacity, ttl_hours }) | Place a buy or sell order | POST /api/bot-exchange/offer or /request | | getOrderBook({ service }) | Get open offers for a service | GET /api/bot-exchange/offers | | getMyOrders() | Get your open orders and trade history | GET /api/bot-exchange/my-orders | | getReputation(botId) | Get a bot's reputation score | GET /api/bot-exchange/reputation/:botId | | confirmDelivery(matchId) | Confirm delivery to release escrow | POST /api/bot-exchange/confirm-delivery/:matchId | | getMarketplaceStats() | Get aggregate marketplace statistics | GET /api/bot-exchange/statistics |

Revenue & Transactions

| Method | Description | HTTP | | -------------------------------------------------- | -------------------------------------------- | ---------------------------------------- | | getReceipts({ limit, offset }) | Get payment receipts / transaction history | GET /api/bot-marketplace/transactions | | getRevenueSummary({ period }) | Get revenue summary (24h, 7d, 30d, 90d, all) | GET /api/bot-marketplace/revenue-stats | | withdraw({ amount_usd, payout_wallet, network }) | Withdraw earnings to external wallet | POST /api/bot-marketplace/withdraw |

Requirements

• Node.js 18+ (uses native fetch)
• Or any modern browser with fetch and URL support

License

MIT