SDK Overview

@tokenbot-org/sdk is a typed TypeScript client wrapping TokenBot’s REST and GraphQL APIs. It is the same SDK the tokenbot CLI is built on.

There is one SDK, and it is TypeScript. The standalone Python and Node SDK repositories were retired on 2026-06-28. If you need TokenBot from another language, call the REST API or GraphQL API directly — both use the same signed-request scheme described below.

Install

Published to GitHub Packages, so you need an .npmrc pointing the @tokenbot-org scope there:

@tokenbot-org:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

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

@tokenbot-org/cli-core is a peer concern, not an optional extra: it owns identity, passphrase handling and the signed HTTP transport. The SDK is deliberately stateless and takes a pre-constructed SignedHttpClient.

Authentication

The SDK does not take an API-key string. Every request is signed with a secp256k1 private key over a canonical string, and the server verifies the signature. There is no shared bearer secret to leak.

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

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

const http = new SignedHttpClient({
  apiUrl: 'https://api.tokenbot.com',
  publicKey,
  privateKey,
});

const sdk = new TokenbotSdk({
  http,
  graphqlUrl: 'https://gql-api.tokenbot.com/graphql',
  wsUrl: 'wss://gql-api.tokenbot.com/graphql', // only needed for *Watch subscriptions
});

graphqlUrl matters. REST and GraphQL are deployed on different hosts, and rest-api has no /graphql passthrough — sending GraphQL through the REST transport 404s. When you pass graphqlUrl, the SDK re-points a copy of the signed transport at that origin, preserving your identity.

The easiest way to get a keypair is tokenbot init, which writes an encrypted identity to ~/.tokenbot/config.json.

Namespaces

Namespace	Transport	Methods
`sdk.strategies`	GraphQL	`list`, `get`, `create`, `update`, `delete`
`sdk.copiers`	GraphQL	`list`, `get`, `create`, `update`, `link`, `unlink`, `delete`
`sdk.trades`	GraphQL	`list`, `get`
`sdk.exchanges`	REST	`listAccounts`, `getAccount`, `createAccount`, `deleteAccount`, `listSupported`
`sdk.webhooks`	REST	`list`, `create`, `delete`, `test`
`sdk.apiKeys`	REST	`list`, `create`, `revoke`
`sdk.identity`	REST	`whoami`, `getChallenge`, `register`
`sdk.settings`	REST	`get`, `update`
`sdk.rewards`	GraphQL	`summary`, `referralCode`
`sdk.admin`	GraphQL	admin-only operations
`sdk.mm`	graphql-ws	`orderBookWatch` (subscription)

Errors

Every failure is a typed subclass of SdkError:

Error	Meaning
`SdkAuthError`	signature rejected, or identity not registered
`SdkPermissionError`	authenticated but not allowed
`SdkNotFoundError`	no such resource
`SdkValidationError`	response failed schema validation
`SdkHttpError`	non-2xx with no more specific mapping
`SdkGraphqlError`	GraphQL returned an `errors` array
`SdkNetworkError`	transport failed before a response
`SdkAdminEndpointMissingError`	admin endpoint absent on the target deployment

Responses are validated against schemas, so a shape change surfaces as SdkValidationError at the boundary rather than as an undefined field somewhere downstream.

SDK Overview

Install

Authentication

Namespaces

Errors

Next