@cerebrochain/bot-sdk

Official JavaScript SDK for the CerebroChain Bot API: logistics and market data, AI inference, MCP tools, account credits and agent discovery. Zero dependencies; uses native fetch (Node.js 18+ or any modern browser).

Install

npm install @cerebrochain/bot-sdk

Quick start

curl

# Forex rates on the free tier (no key needed)
curl https://cerebrochain.com/api/bot/data/market/forex

# The same call with your API key
curl -H "X-API-Key: cbbot_your_api_key" \
  https://cerebrochain.com/api/bot/data/market/forex

JavaScript

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

const client = new CerebroChainClient({ apiKey: process.env.CEREBROCHAIN_API_KEY });

const forex = await client.getForexData();
console.log(forex.data);

const rates = await client.getFreightRates({ origin: '10001', destination: '90210', weight: 2 });
console.log(rates);

Get an API key

const { api_key, credits } = await new CerebroChainClient().quickStart({ name: 'acme-router' });

curl -X POST https://cerebrochain.com/api/bot/quick-start \
  -H "Content-Type: application/json" \
  -d '{"bot_identifier":"acme-router"}'

API key, free tier and credits

• The API key travels only in the X-API-Key header. The SDK never puts it in a URL or a request body.
• Free tier: calls made without an API key get 100 calls/day per caller IP. client.freeTierRemaining holds the count from the last X-Free-Tier-Remaining response header.
• Credits: with an API key, priced calls draw down your prepaid credits. Buy credits by card at https://app.cerebrochain.com/settings/billing. getBalance() and getReceipts() show the balance and every charge.
• A call that neither the free tier nor your credits can cover is refused with HTTP 402 (ErrorCodes.PAYMENT_REQUIRED).

Client options

const client = new CerebroChainClient({
  apiKey: 'cbbot_your_api_key', // optional; omit for the free tier
  baseUrl: 'https://cerebrochain.com', // default
  maxRetries: 3, // automatic retries on 429 (honors Retry-After)
  retryDelayMs: 1000, // back-off base when Retry-After is absent
});

Method reference

Every method returns a Promise of the parsed JSON response and rejects with a CerebroChainError. ? marks an optional field.

Onboarding

| Method | Description | Endpoint | | ------------------------------------------- | ------------------------------------------------------------ | --------------------------- | | quickStart({ name, botType?, platform? }) | Register a bot; the response carries api_key and credits | POST /api/bot/quick-start |

Account (API key required)

| Method | Description | Endpoint | | ------------------------------------------------ | ---------------------------------------------------- | --------------------------------------- | | getBalance() | Prepaid credit balance | GET /api/bot-marketplace/balance | | getReceipts({ limit = 20, offset = 0, type? }) | Credit transactions (purchases and per-call charges) | GET /api/bot-marketplace/transactions |

Market and logistics data

| Method | Description | Endpoint | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | getForexData() | Forex (currency) rates; takes no parameters | GET /api/bot/data/market/forex | | getFreightMarketData({ origin, destination, weight? }) | Freight market rates for a US lane (ZIP codes; weight in lb) | GET /api/bot/data/market/freight | | getFreightRates({ origin, destination, weight?, length?, width?, height? }) | Live parcel rates between two US ZIP codes (weight in lb, dimensions in in) | GET /api/bot/data/logistics/rates | | getCommodityPrices({ symbol? }) | EIA energy prices: symbol is crude-oil-wti, crude-oil-brent, natural-gas or diesel; omit for all four | GET /api/bot/data/commodity/prices | | getEconomicIndicators({ indicator?, limit? }) | Economic indicators (limit observations, default 12) | GET /api/bot/data/economic/indicators |

Compute

| Method | Description | Endpoint | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | aiInference({ messages \| input, model?, options? }) | AI inference from chat messages or a single input prompt; options.maxTokens (max 2000), options.temperature | POST /api/bot/compute/inference |

MCP tools

| Method | Description | Endpoint | | ---------------------------------------------- | -------------------------------------------------------------- | --------------------------------- | | getMcpServices() | The MCP services and tools a bot can call | GET /api/bot/agent/mcp/services | | executeMcp({ service, capability, params? }) | Run one tool (e.g. customs-clearance-mcp / calculate_duty) | POST /api/bot/agent/mcp/execute |

Discovery (no API key needed)

| Method | Description | Endpoint | | -------------------------------------------------------------- | ------------------ | ----------------------------- | | getAgentCard() | Agent card | GET /.well-known/agent.json | | getCatalog() | Service catalog | GET /api/agent/catalog | | searchServices(query, { capability?, maxPrice?, minPrice? }) | Search the catalog | GET /api/agent/search |

Error handling

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

try {
  await client.getBalance();
} catch (err) {
  if (err instanceof CerebroChainError) {
    console.error(err.status, err.code, err.details);
    if (err.code === ErrorCodes.PAYMENT_REQUIRED) {
      // Buy credits at https://app.cerebrochain.com/settings/billing
    }
  }
}

Error codes: BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, SERVER_ERROR, NETWORK_ERROR, UNKNOWN_ERROR. Methods that check their own inputs (quickStart, getFreightRates, aiInference, executeMcp) reject with BAD_REQUEST before sending anything. The error classes are also exported from @cerebrochain/bot-sdk/errors.

Breaking changes in 2.0.0

2.0.0 keeps only methods whose endpoint exists today, called with the HTTP method and parameters the server actually reads. CerebroChain retired its bot-to-bot exchange and its digital-asset features, so these 1.x methods are removed:

• getServices(), placeOrder(), getOrderBook(), getMyOrders(), getReputation(botId), getMarketplaceStats(), confirmDelivery(): the bot exchange (/api/bot-exchange/*) is retired.
• getRevenueSummary(): /api/bot-marketplace/revenue-stats no longer exists.
• getCryptoPrices(): that market series is retired.
• getPricing(), getAgentReputation(), getLeaderboard(): /api/agent/pricing, /api/agent/reputation/:address and /api/agent/leaderboard are deleted.
• The agentAddress option and the X-Agent-Address header: the free tier is keyed by caller IP. apiKey is now optional.

These methods changed to match their endpoints:

• getFreightRates sends a GET with origin, destination, weight, length, width and height query parameters. It used to POST a packages body, which the endpoint does not accept.
• getFreightMarketData takes { origin, destination, weight } instead of { lane }.
• getForexData() takes no parameters (pair was ignored).
• executeMcp takes capability instead of method. Requests without capability were refused.
• aiInference sends options as a nested object, so maxTokens and temperature now take effect. model is optional, and a single input string may replace messages.
• quickStart takes { name, botType, platform }. email and description were never read.

Added: getCommodityPrices(), getEconomicIndicators(), the type filter on getReceipts(), and the capability and minPrice filters on searchServices().

License

MIT