JSPM

@cerebrochain/bot-sdk

1.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • 0
  • Score
    100M100P100Q63520F
  • License MIT

Official JavaScript SDK for the CerebroChain Bot API — zero dependencies, native fetch

Package Exports

  • @cerebrochain/bot-sdk
  • @cerebrochain/bot-sdk/errors

Readme

@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 (Free Tier - No API Key Required)

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

// Free tier: 100 API calls/day with just your wallet address
const client = new CerebroChainClient({
  agentAddress: '0xYourWalletAddress',
});

// Discover services
const catalog = await client.getCatalog();
const card = await client.getAgentCard();
console.log(`Free calls remaining: ${client.freeTierRemaining}`);

Full API Key Setup

const client = new CerebroChainClient({
  apiKey: process.env.CEREBROCHAIN_API_KEY, // Get yours at https://cerebrochain.com/developers
  agentAddress: '0xYourWalletAddress', // Optional: for trust-tier pricing
});

// 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_...', // Optional if using free tier
  agentAddress: '0x...', // ERC-8004 agent address (for free tier + trust pricing)
  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