Global derivatives
Use CBAdvancedTradeGlobalClient for Coinbase Global derivatives. For spot trading, use the Advanced Trade guide. Access requires product eligibility and the appropriate account permissions.
Setup
Install the package with npm install coinbase-api. Save each example with the filename shown below and run it with Node.js 24. For private examples, put the named credentials in a private .env file excluded from Git and use node --env-file=.env filename.ts. Keep account output private.
Public REST
CBAdvancedTradeGlobalClient targets https://drb.coinbase.com. Its methods send JSON-RPC requests over HTTP and return the unwrapped result. Public instrument discovery needs no key. Save as global-market-data.ts and run node global-market-data.ts:
import { CBAdvancedTradeGlobalClient } from 'coinbase-api';
async function main() {
const client = new CBAdvancedTradeGlobalClient();
const instruments = await client.getInstruments({ currency: 'BTC' });
console.log(instruments);
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});Use the returned instrument names for Global requests. Do not replace them with Advanced Trade spot product IDs such as BTC-USD. Global prices and sizes are JSON numbers, order enums are lowercase, and label is not a unique equivalent of client_order_id. Build requests with the Global types rather than copying an Advanced Trade order.
Public WebSocket subscriptions
Use WS_KEY_MAP.advTradeGlobalMarketData for public streams at streams.drb.coinbase.com. Global channel parameters belong in the topic string, not an Advanced Trade product_ids payload. Select an instrument returned by the discovery request above; public intervals include 100ms and agg2, while raw requires authentication.
Save as global-stream.ts and run node global-stream.ts:
import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';
const ws = new WebsocketClient();
ws.on('update', (event) => {
console.log(event);
});
ws.on('response', (event) => {
console.log('Subscription response:', event);
});
ws.on('exception', (error) => {
console.error('WebSocket exception:', error);
});
ws.on('reconnect', (event) => {
console.log('Reconnecting:', event);
});
ws.on('reconnected', (event) => {
console.log('Reconnected:', event);
});
// Replace this with an instrument returned by getInstruments().
ws.subscribe('ticker.BTC_USDC-PERPETUAL.100ms', WS_KEY_MAP.advTradeGlobalMarketData);
function stop() {
ws.closeAll();
}
process.once('SIGINT', stop);
process.once('SIGTERM', stop);The example runs until Ctrl+C. Verify the subscription response and implement the channel's snapshot/update rules before building local state. connectAll() does not open Global feeds; subscriptions connect on demand.
Private REST and order management
For private HTTP calls, provide the eligible CDP key name and private key. The SDK exchanges a fresh signed JWT through public/auth, caches the returned Bearer token and refreshes it when needed. Token rejection invalidates cached authorization; the failed operation is not automatically replayed. Reconcile uncertain writes before retrying.
Read account state with getAccountSummary() and getPositions() for the required currency. Use getOpenOrders() to initialize open-order state. These methods use Global parameters and return types, not the Advanced Trade account schema.
Set COINBASE_GLOBAL_API_KEY to your CDP key name and COINBASE_GLOBAL_API_SECRET to its complete private key. Preserve the original key header, footer and line breaks; the REST client normalizes escaped \n sequences, and the private-stream example normalizes them explicitly. Save as global-account.ts and run with your .env file:
import { CBAdvancedTradeGlobalClient } from 'coinbase-api';
function requiredEnvVar(name: string) {
const value = process.env[name];
if (!value) {
throw new Error(`Set ${name}.`);
}
return value;
}
async function main() {
const client = new CBAdvancedTradeGlobalClient({
apiKey: requiredEnvVar('COINBASE_GLOBAL_API_KEY'),
apiSecret: requiredEnvVar('COINBASE_GLOBAL_API_SECRET'),
});
const summary = await client.getAccountSummary({ currency: 'USDC' });
console.log(summary);
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});For live trading, submitBuy() and submitSell() submit Global orders, getOrderState() resolves a specific unknown order, and cancelOrder() requests cancellation. Submission and cancellation change live orders. Save exchange order IDs, inspect results and use private updates to track execution. A non-unique label alone is not sufficient duplicate protection.
Private WebSocket subscriptions
Use WS_KEY_MAP.advTradeGlobalUserData on drb.coinbase.com. The SDK authenticates through public/auth before private/subscribe, renews the session and restores subscriptions after authenticating a replacement connection.
Save as global-private-stream.ts and run with the same Global environment variables:
import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';
function requiredEnvVar(name: string) {
const value = process.env[name];
if (!value) {
throw new Error(`Set ${name}.`);
}
return value;
}
const ws = new WebsocketClient({
apiKey: requiredEnvVar('COINBASE_GLOBAL_API_KEY'),
apiSecret: requiredEnvVar('COINBASE_GLOBAL_API_SECRET').replace(/\\n/g, '\n'),
});
ws.on('update', (event) => {
console.log(event);
});
ws.on('response', (event) => {
console.log('Subscription response:', event);
});
ws.on('exception', (error) => {
console.error('WebSocket exception:', error);
});
ws.on('reconnect', (event) => {
console.log('Reconnecting:', event);
});
ws.on('reconnected', (event) => {
console.log('Reconnected:', event);
});
ws.subscribe(
['user.orders.future.USDC.100ms', 'user.trades.future.USDC.100ms', 'user.portfolio.USDC'],
WS_KEY_MAP.advTradeGlobalUserData,
);
function stop() {
ws.closeAll();
}
process.once('SIGINT', stop);
process.once('SIGTERM', stop);This example observes USDC futures order, trade and portfolio changes without placing an order. Adapt currency and product kind to your account. Update account state from these events; use REST for initial state and specific gaps rather than polling. Mark state stale on reconnect; reconnected alone does not prove authentication, subscription or state recovery has completed. See Account State.
Global WebSocket API
WebsocketAPIClient provides awaitable Global JSON-RPC methods. This public, one-shot example reads server time and closes its connection. Save as global-ws-api.ts and run node global-ws-api.ts:
import { WebsocketAPIClient } from 'coinbase-api';
async function main() {
const client = new WebsocketAPIClient();
try {
const response = await client.getTime();
console.log(response.result);
} finally {
client.getWSClient().closeAll();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});advTradeGlobalWSAPI is a dedicated request-response connection, separate from private subscriptions even though both use drb.coinbase.com. Read response.result; unlike the Global HTTP client, this API returns the envelope. getWSClient() exposes the underlying event and connection client. connectWSAPI() can establish an authenticated session before your first request; public calls do not require this authentication step.
Private calls authenticate the socket automatically. The SDK manages session renewal and can reauthenticate after reconnect. wsAPITimeout controls the reply wait after sending (default 10 seconds); connection and authentication are handled separately. Pending requests are rejected if their connection is lost. reauthWSAPIOnReconnect defaults to enabled for a previously authenticated API session. A new session does not establish the outcome of a command sent on the old one.
Errors and uncertain outcomes
JSON-RPC protocol errors reject even when carried by HTTP 200. Inspect their code and message, not only HTTP status. HTTP error parsing is controlled by parseExceptions; Global credential redaction and rejected-token invalidation still apply when parsing is disabled.
WebSocket API calls reject on protocol errors, reply timeout or connection failure. A timed-out trading command is not automatically safe to retry. Preserve its identifiers and reconcile its outcome from private events and targeted account/order reads before issuing a replacement.
Global has no mapped sandbox. See the Global client reference and WebSocket API reference for supported methods.