TypeScript SDK Reference

@tokenbot-org/sdk — the typed client the tokenbot CLI itself is built on.

This page was previously titled “Node.js SDK”. There is only one SDK and it is TypeScript; see Overview.

---

Setup

npm install @tokenbot-org/sdk @tokenbot-org/cli-core

import { SignedHttpClient, unlockIdentity } from '@tokenbot-org/cli-core';
import { TokenbotSdk } from '@tokenbot-org/sdk';

const privateKey = unlockIdentity(encryptedKey, salt, passphrase);

const sdk = new TokenbotSdk({
  http: new SignedHttpClient({ apiUrl: 'https://api.tokenbot.com', publicKey, privateKey }),
  graphqlUrl: 'https://gql-api.tokenbot.com/graphql',
  wsUrl: 'wss://gql-api.tokenbot.com/graphql',
});

wsUrl is only needed for *Watch subscription methods. Omit it and calling one throws SdkError rather than failing at the socket.

---

sdk.strategies

await sdk.strategies.list();
await sdk.strategies.get(id);
await sdk.strategies.create(input);       // CreateStrategyInput
await sdk.strategies.update(id, input);   // UpdateStrategyInput — partial
await sdk.strategies.delete(id);

CreateStrategyInput:

Field	Required	Notes
exchangeAccountId	✅
name	✅
description
isPublic
configuration		free-form object
riskLevel		string or number
maxDrawdown, maxAllocation, monthlyFee		numbers

sdk.copiers

await sdk.copiers.list();
await sdk.copiers.get(id);
await sdk.copiers.create(input);              // CreateCopierInput
await sdk.copiers.update(id, input);          // partial
await sdk.copiers.link(strategyId, copierId);
await sdk.copiers.unlink(strategyId, copierId);
await sdk.copiers.delete(id);

CreateCopierInput requires strategyId, exchangeAccountId, name and allocationPercentage (0–100, clamped server-side). copySettings is optional and free-form.

Note link / unlink take positional (strategyId, copierId) — the opposite convention from the CLI, which uses --strategy / --copier flags.

sdk.trades

await sdk.trades.list({ filter: { symbol: 'BTC/USDT', dateRange: 'ALL', limit: 100 } });
await sdk.trades.get(id);

Two behaviours worth knowing before you trust a result:

• dateRange defaults to MONTH server-side when omitted. Pass 'ALL' explicitly to search full history, or you’ll silently get only the last month.
• symbol is filtered client-side — graphql-api has no symbol filter — so it is applied to the page the server returned, not the whole history. Combine it with a generous limit.

Other filter fields: strategyId(s), exchangeAccountId(s), tradePairIds, status(es), side(s), fromDate, toDate, minProfit, maxProfit, search, limit, page.

sdk.exchanges

await sdk.exchanges.listAccounts();
await sdk.exchanges.getAccount(id);
await sdk.exchanges.createAccount(input);
await sdk.exchanges.deleteAccount(id);
await sdk.exchanges.listSupported();

CreateExchangeAccountInput requires exchangeName, tradingType, apiKey and apiSecret; accountName, apiPassphrase and apiPassword are optional (some venues need one of the latter two).

Note the field is exchangeName, not exchange.

createAccount registers credentials server-side so the platform can act on your behalf. That is a different trust model from the CLI’s local keys store — see Exchange Accounts.

sdk.webhooks

await sdk.webhooks.list();
await sdk.webhooks.create(input);
await sdk.webhooks.delete(id);
await sdk.webhooks.test(id);

sdk.apiKeys

await sdk.apiKeys.list();
await sdk.apiKeys.create(input);   // secret returned exactly once
await sdk.apiKeys.revoke(id);

sdk.identity

await sdk.identity.whoami();
await sdk.identity.getChallenge();
await sdk.identity.register(input);

sdk.settings

await sdk.settings.get();
await sdk.settings.update(input);

sdk.rewards

await sdk.rewards.summary();
await sdk.rewards.referralCode();

sdk.mm — subscriptions

Subscription-only. Requires wsUrl.

for await (const snapshot of sdk.mm.orderBookWatch({ exchangeId: 'mexc', symbol: 'TBOT/USDT' })) {
  console.log(snapshot.bids[0], snapshot.asks[0]);
  break; // `break` tears the socket down cleanly
}

sdk.admin

Admin-only GraphQL operations. Calling one against a deployment that doesn’t expose the endpoint throws SdkAdminEndpointMissingError rather than a generic failure.

---

Error handling

import { SdkAuthError, SdkNotFoundError, SdkValidationError } from '@tokenbot-org/sdk';

try {
  await sdk.strategies.get(id);
} catch (err) {
  if (err instanceof SdkNotFoundError) return null;
  if (err instanceof SdkAuthError) throw new Error('identity rejected — re-run tokenbot init');
  if (err instanceof SdkValidationError) throw new Error('API returned an unexpected shape');
  throw err;
}

All errors extend SdkError. See Overview for the full list.

---

See also

• Examples
• Overview