Advanced TradeSpotUS FuturesInternational PerpetualsPublic WebSocketsPrivate WebSocketsSandboxes

Coinbase API JavaScript Tutorial for Node.js

Build Coinbase integrations with Advanced Trade REST API calls, public and private WebSocket streams, safe order previews, reconnect recovery, sandbox guidance, and proxy support.

Start Building npm package GitHub

first-coinbase-api-call.js

public REST API

import { CBAdvancedTradeClient } from 'coinbase-api';

const client = new CBAdvancedTradeClient();

async function main() {
  try {
    const serverTime = await client.getServerTime();
    console.log('Server time:', serverTime.iso);
  } catch (error) {
    console.error('Server time request failed:', error);
  }

  try {
    const product = await client.getPublicProduct({
      product_id: 'BTC-USD',
    });
    console.log('BTC-USD price:', product.price);
    console.log('Base increment:', product.base_increment);
    console.log('Price increment:', product.price_increment);
  } catch (error) {
    console.error('Product request failed:', error);
  }

  try {
    const orderBook = await client.getPublicProductBook({
      product_id: 'BTC-USD',
      limit: 5,
    });
    console.log('Best bid:', orderBook.pricebook.bids[0]);
    console.log('Best ask:', orderBook.pricebook.asks[0]);
  } catch (error) {
    console.error('Order book request failed:', error);
  }

  const end = Math.floor(Date.now() / 1000);
  const start = end - 60 * 60;

  try {
    const candles = await client.getPublicProductCandles({
      product_id: 'BTC-USD',
      start: String(start),
      end: String(end),
      granularity: 'FIVE_MINUTE',
      limit: 12,
    });
    console.log('Latest candle:', candles.candles[0]);
  } catch (error) {
    console.error('Candles request failed:', error);
  }

  try {
    const marketTrades = await client.getPublicMarketTrades({
      product_id: 'BTC-USD',
      limit: 10,
    });
    console.log('Latest trade:', marketTrades.trades[0]);
    console.log('Best bid:', marketTrades.best_bid);
    console.log('Best ask:', marketTrades.best_ask);
  } catch (error) {
    console.error('Market trades request failed:', error);
  }
}

main();

API surface map

Choose the Coinbase client for the job

Start with Advanced Trade for retail trading, then use a specialized client only when the account belongs to another Coinbase API product.

Your app

Bot, dashboard, worker, tool

Any Node.js or JavaScript-compatible service that needs Coinbase market data, account state, order management, payments, or reconciliation.

npm package

npm install coinbase-api

CBAdvancedTradeClient

Advanced Trade products, accounts, orders, portfolios, derivatives, conversions, fees, and payment methods

WebsocketClient

Advanced Trade, Exchange, International, and Prime WebSocket subscriptions

CBAppClient

Coinbase App accounts, addresses, transactions, deposits, withdrawals, and public prices

CBExchangeClient

Institutional Exchange market data, accounts, orders, profiles, reports, loans, and transfers

CBInternationalClient

International instruments, portfolios, orders, positions, loans, and transfers

CBPrimeClient

Prime portfolios, balances, orders, activities, allocations, wallets, and transactions

CBCommerceClient

Legacy Commerce charges, checkouts, and events

Coinbase APIs

Advanced Trade REST API calls

Advanced Trade public and private streams

Coinbase App account and transfer calls

Exchange and International institutional APIs

Prime trading and custody APIs

Legacy Commerce APIs

Request routing

Product, portfolio, connection, and API family are separate choices

Keep these values explicit so each request reaches the intended Coinbase product and account.

Product ID

product_id: 'BTC-USD'

Select an Advanced Trade Spot, futures, or perpetual product.

Product metadata

base_increment and price_increment

Apply current size and price rules before an order request.

Portfolio

portfolio_uuid

Scope balances, positions, and permissions to the intended portfolio.

Client order ID

client_order_id

Give an application-owned order a stable identifier.

WebSocket connection

WS_KEY_MAP.advTradeMarketData

Route a subscription to the correct public or private connection.

API family

CBAdvancedTradeClient

Select the REST API and authentication model used by the account.

What this tutorial covers

What to get right in a Coinbase integration

Start with Advanced Trade public data, then add credentials, private state, streams, safe validation, network configuration, and recovery.

Advanced Trade REST API calls

Read endpoint-specific response objects and let the SDK generate JWTs for private requests.

Public and private WebSocket streams

Select the correct connection with WS_KEY_MAP and distinguish acknowledgements from updates.

Safe order previews

Validate a current order configuration without submitting it to the matching engine.

API families, sandboxes, and proxies

Match the client to the Coinbase account, then configure the intended environment and network route.

Start building

First REST API calls, streams, order preview, recovery, and proxies

Run one focused JavaScript example at a time, then add production controls around the same clients.

1import { CBAdvancedTradeClient } from 'coinbase-api';2 3const client = new CBAdvancedTradeClient();4 5async function main() {6  try {7    const serverTime = await client.getServerTime();8    console.log('Server time:', serverTime.iso);9  } catch (error) {10    console.error('Server time request failed:', error);11  }12 13  try {14    const product = await client.getPublicProduct({15      product_id: 'BTC-USD',16    });17    console.log('BTC-USD price:', product.price);18    console.log('Base increment:', product.base_increment);19    console.log('Price increment:', product.price_increment);20  } catch (error) {21    console.error('Product request failed:', error);22  }23 24  try {25    const orderBook = await client.getPublicProductBook({26      product_id: 'BTC-USD',27      limit: 5,28    });29    console.log('Best bid:', orderBook.pricebook.bids[0]);30    console.log('Best ask:', orderBook.pricebook.asks[0]);31  } catch (error) {32    console.error('Order book request failed:', error);33  }34 35  const end = Math.floor(Date.now() / 1000);36  const start = end - 60 * 60;37 38  try {39    const candles = await client.getPublicProductCandles({40      product_id: 'BTC-USD',41      start: String(start),42      end: String(end),43      granularity: 'FIVE_MINUTE',44      limit: 12,45    });46    console.log('Latest candle:', candles.candles[0]);47  } catch (error) {48    console.error('Candles request failed:', error);49  }50 51  try {52    const marketTrades = await client.getPublicMarketTrades({53      product_id: 'BTC-USD',54      limit: 10,55    });56    console.log('Latest trade:', marketTrades.trades[0]);57    console.log('Best bid:', marketTrades.best_bid);58    console.log('Best ask:', marketTrades.best_ask);59  } catch (error) {60    console.error('Market trades request failed:', error);61  }62}63 64main();

1import { CBAdvancedTradeClient } from 'coinbase-api';2 3async function main() {4  if (5    !process.env.COINBASE_API_KEY_NAME ||6    !process.env.COINBASE_API_PRIVATE_KEY7  ) {8    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');9    return;10  }11 12  const client = new CBAdvancedTradeClient({13    apiKey: process.env.COINBASE_API_KEY_NAME,14    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,15  });16 17  try {18    const permissions = await client.getApiKeyPermissions();19    console.log('Can view:', permissions.can_view);20    console.log('Can trade:', permissions.can_trade);21    console.log('Can transfer:', permissions.can_transfer);22    console.log('Portfolio:', permissions.portfolio_uuid);23  } catch (error) {24    console.error('Permission request failed:', error);25  }26 27  try {28    const accounts = await client.getAccounts({29      limit: 10,30    });31    console.log('Accounts:', accounts.accounts);32    console.log('More accounts available:', accounts.has_next);33  } catch (error) {34    console.error('Account request failed:', error);35  }36 37  try {38    const openOrders = await client.getOrders({39      order_status: ['OPEN'],40      limit: 20,41    });42    console.log('Open orders:', openOrders.orders);43    console.log('More orders available:', openOrders.has_next);44  } catch (error) {45    console.error('Open-order request failed:', error);46  }47 48  try {49    const fills = await client.getFills({50      product_ids: ['BTC-USD'],51      limit: 20,52    });53    console.log('Recent BTC-USD fills:', fills.fills);54    console.log('Next cursor:', fills.cursor);55  } catch (error) {56    console.error('Fill request failed:', error);57  }58}59 60main();

1import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';2 3function main() {4  const ws = new WebsocketClient();5 6  ws.on('open', ({ wsKey }) => {7    console.log('WebSocket opened:', wsKey);8  });9 10  ws.on('response', (response) => {11    console.log(12      'WebSocket response:',13      response.wsKey,14      response.channel,15      response.events,16    );17  });18 19  ws.on('update', (update) => {20    console.log(21      'WebSocket update:',22      update.wsKey,23      update.channel,24      update.events,25    );26  });27 28  ws.on('reconnect', ({ wsKey }) => {29    console.log('Reconnecting:', wsKey);30  });31 32  ws.on('reconnected', ({ wsKey }) => {33    console.log('Reconnected:', wsKey);34  });35 36  ws.on('close', ({ wsKey }) => {37    console.log('WebSocket closed:', wsKey);38  });39 40  ws.on('exception', (error) => {41    console.error('WebSocket exception:', error);42  });43 44  try {45    ws.subscribe(46      {47        topic: 'ticker',48        payload: {49          product_ids: ['BTC-USD'],50        },51      },52      WS_KEY_MAP.advTradeMarketData,53    );54  } catch (error) {55    console.error('Ticker subscription failed:', error);56  }57 58  try {59    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);60  } catch (error) {61    console.error('Heartbeat subscription failed:', error);62  }63 64  process.once('SIGINT', () => {65    ws.closeAll();66  });67}68 69main();

1import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';2 3function main() {4  if (5    !process.env.COINBASE_API_KEY_NAME ||6    !process.env.COINBASE_API_PRIVATE_KEY7  ) {8    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');9    return;10  }11 12  const ws = new WebsocketClient({13    apiKey: process.env.COINBASE_API_KEY_NAME,14    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,15  });16 17  ws.on('open', ({ wsKey }) => {18    console.log('Private WebSocket opened:', wsKey);19  });20 21  ws.on('response', (response) => {22    console.log(23      'Private WebSocket response:',24      response.wsKey,25      response.channel,26      response.events,27    );28  });29 30  ws.on('update', (update) => {31    console.log('Private update:', update.wsKey, update.channel, update.events);32  });33 34  ws.on('reconnect', ({ wsKey }) => {35    console.log('Private WebSocket reconnecting:', wsKey);36  });37 38  ws.on('reconnected', ({ wsKey }) => {39    console.log('Private WebSocket reconnected:', wsKey);40  });41 42  ws.on('close', ({ wsKey }) => {43    console.log('Private WebSocket closed:', wsKey);44  });45 46  ws.on('exception', (error) => {47    console.error('Private WebSocket exception:', error);48  });49 50  try {51    ws.subscribe(52      {53        topic: 'user',54        payload: {55          product_ids: ['BTC-USD'],56        },57      },58      WS_KEY_MAP.advTradeUserData,59    );60  } catch (error) {61    console.error('User subscription failed:', error);62  }63 64  try {65    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeUserData);66  } catch (error) {67    console.error('Heartbeat subscription failed:', error);68  }69 70  process.once('SIGINT', () => {71    ws.closeAll();72  });73}74 75main();

1import { CBAdvancedTradeClient } from 'coinbase-api';2 3async function main() {4  if (5    !process.env.COINBASE_API_KEY_NAME ||6    !process.env.COINBASE_API_PRIVATE_KEY7  ) {8    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');9    return;10  }11 12  const client = new CBAdvancedTradeClient({13    apiKey: process.env.COINBASE_API_KEY_NAME,14    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,15  });16 17  let product;18 19  try {20    product = await client.getPublicProduct({21      product_id: 'BTC-USD',22    });23    console.log('Minimum quote size:', product.quote_min_size);24  } catch (error) {25    console.error('Product request failed:', error);26    return;27  }28 29  if (30    !product.quote_min_size ||31    !Number.isFinite(Number(product.quote_min_size)) ||32    Number(product.quote_min_size) <= 033  ) {34    console.error('BTC-USD returned an invalid quote_min_size.');35    return;36  }37 38  try {39    const preview = await client.previewOrder({40      product_id: 'BTC-USD',41      side: 'BUY',42      order_configuration: {43        market_market_ioc: {44          quote_size: product.quote_min_size,45        },46      },47    });48 49    console.log('Validation errors:', preview.errs);50    console.log('Warnings:', preview.warning);51    console.log('Order total:', preview.order_total);52    console.log('Commission total:', preview.commission_total);53    console.log('Best bid:', preview.best_bid);54    console.log('Best ask:', preview.best_ask);55    console.log('Preview ID:', preview.preview_id);56  } catch (error) {57    console.error('Order preview failed:', error);58  }59}60 61main();

1import {2  CBAdvancedTradeClient,3  WebsocketClient,4  WS_KEY_MAP,5} from 'coinbase-api';6 7async function main() {8  if (9    !process.env.COINBASE_API_KEY_NAME ||10    !process.env.COINBASE_API_PRIVATE_KEY11  ) {12    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');13    return;14  }15 16  const credentials = {17    apiKey: process.env.COINBASE_API_KEY_NAME,18    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,19  };20 21  const rest = new CBAdvancedTradeClient(credentials);22  const ws = new WebsocketClient(credentials);23 24  let accountState;25 26  ws.on('update', (update) => {27    console.log('Private update:', update.channel, update.events);28  });29 30  ws.on('reconnected', async ({ wsKey }) => {31    if (wsKey !== WS_KEY_MAP.advTradeUserData) {32      return;33    }34 35    let accountsResponse;36    let ordersResponse;37    let fillsResponse;38 39    try {40      accountsResponse = await rest.getAccounts({41        limit: 250,42      });43    } catch (error) {44      console.error('Account recovery failed:', error);45      return;46    }47 48    try {49      ordersResponse = await rest.getOrders({50        order_status: ['OPEN'],51        limit: 250,52      });53    } catch (error) {54      console.error('Open-order recovery failed:', error);55      return;56    }57 58    try {59      fillsResponse = await rest.getFills({60        product_ids: ['BTC-USD'],61        limit: 100,62      });63    } catch (error) {64      console.error('Fill recovery failed:', error);65      return;66    }67 68    const replacement = {69      accounts: accountsResponse.accounts,70      openOrders: ordersResponse.orders,71      recentFills: fillsResponse.fills,72      recoveredAt: new Date().toISOString(),73    };74 75    accountState = replacement;76    console.log('Private state recovered:', accountState.recoveredAt);77  });78 79  ws.on('exception', (error) => {80    console.error('WebSocket exception:', error);81  });82 83  try {84    ws.subscribe(85      {86        topic: 'user',87        payload: {88          product_ids: ['BTC-USD'],89        },90      },91      WS_KEY_MAP.advTradeUserData,92    );93  } catch (error) {94    console.error('User subscription failed:', error);95  }96 97  try {98    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeUserData);99  } catch (error) {100    console.error('Heartbeat subscription failed:', error);101  }102 103  process.once('SIGINT', () => {104    ws.closeAll();105  });106}107 108main();

1import { HttpsProxyAgent } from 'https-proxy-agent';2import {3  CBAdvancedTradeClient,4  WebsocketClient,5  WS_KEY_MAP,6} from 'coinbase-api';7 8async function main() {9  if (!process.env.COINBASE_PROXY_URL) {10    console.error('Set COINBASE_PROXY_URL.');11    return;12  }13 14  const proxyAgent = new HttpsProxyAgent(process.env.COINBASE_PROXY_URL);15 16  const rest = new CBAdvancedTradeClient(17    {},18    {19      httpsAgent: proxyAgent,20      proxy: false,21    },22  );23 24  const ws = new WebsocketClient({25    wsOptions: {26      agent: proxyAgent,27    },28  });29 30  try {31    const serverTime = await rest.getServerTime();32    console.log('REST API through proxy:', serverTime.iso);33  } catch (error) {34    console.error('Proxied REST API request failed:', error);35  }36 37  ws.on('open', ({ wsKey }) => {38    console.log('Proxied WebSocket opened:', wsKey);39  });40 41  ws.on('response', (response) => {42    console.log(43      'Proxied WebSocket response:',44      response.wsKey,45      response.channel,46    );47  });48 49  ws.on('update', (update) => {50    console.log(51      'Proxied WebSocket update:',52      update.wsKey,53      update.channel,54      update.events,55    );56  });57 58  ws.on('exception', (error) => {59    console.error('Proxied WebSocket exception:', error);60  });61 62  try {63    ws.subscribe(64      {65        topic: 'ticker',66        payload: {67          product_ids: ['BTC-USD'],68        },69      },70      WS_KEY_MAP.advTradeMarketData,71    );72  } catch (error) {73    console.error('Proxied ticker subscription failed:', error);74  }75 76  try {77    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);78  } catch (error) {79    console.error('Proxied heartbeat subscription failed:', error);80  }81 82  process.once('SIGINT', () => {83    ws.closeAll();84  });85}86 87main();

1import { SocksProxyAgent } from 'socks-proxy-agent';2import {3  CBAdvancedTradeClient,4  WebsocketClient,5  WS_KEY_MAP,6} from 'coinbase-api';7 8async function main() {9  if (!process.env.COINBASE_SOCKS_PROXY_URL) {10    console.error('Set COINBASE_SOCKS_PROXY_URL.');11    return;12  }13 14  const proxyAgent = new SocksProxyAgent(process.env.COINBASE_SOCKS_PROXY_URL);15 16  const rest = new CBAdvancedTradeClient(17    {},18    {19      httpsAgent: proxyAgent,20      proxy: false,21    },22  );23 24  const ws = new WebsocketClient({25    wsOptions: {26      agent: proxyAgent,27    },28  });29 30  try {31    const serverTime = await rest.getServerTime();32    console.log('REST API through SOCKS5:', serverTime.iso);33  } catch (error) {34    console.error('SOCKS5 REST API request failed:', error);35  }36 37  ws.on('open', ({ wsKey }) => {38    console.log('SOCKS5 WebSocket opened:', wsKey);39  });40 41  ws.on('response', (response) => {42    console.log('SOCKS5 WebSocket response:', response.wsKey, response.channel);43  });44 45  ws.on('update', (update) => {46    console.log(47      'SOCKS5 WebSocket update:',48      update.wsKey,49      update.channel,50      update.events,51    );52  });53 54  ws.on('exception', (error) => {55    console.error('SOCKS5 WebSocket exception:', error);56  });57 58  try {59    ws.subscribe(60      {61        topic: 'ticker',62        payload: {63          product_ids: ['BTC-USD'],64        },65      },66      WS_KEY_MAP.advTradeMarketData,67    );68  } catch (error) {69    console.error('SOCKS5 ticker subscription failed:', error);70  }71 72  try {73    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);74  } catch (error) {75    console.error('SOCKS5 heartbeat subscription failed:', error);76  }77 78  process.once('SIGINT', () => {79    ws.closeAll();80  });81}82 83main();

Workflow diagrams

REST API, WebSocket, and order-preview workflows

REST API results, subscription acknowledgements, stream updates, and order previews carry different information.

REST API request flow

Choose the Advanced Trade method, let the SDK sign private requests, then read the endpoint-specific result.

Choose product and methodYour code

Call the SDK clientYour code

Route and sign if privateSDK handles

Receive endpoint responseCoinbase

Use returned fieldsYour code

WebSocket subscription flow

Choose a topic and wsKey, let the SDK connect and authenticate when needed, then process acknowledgements and updates separately.

Choose topic and wsKeyYour code

Call subscribeYour code

Connect and sign if privateSDK handles

Receive subscriptions responseEvent

Process update eventsYour code

Safe order-preview flow

Read current product rules, preview the order, inspect validation results, and stop without submitting an order.

Read product metadataYour code

Build order configurationYour code

Call previewOrderYour code

Inspect errors and totalsCoinbase

Stop before submissionYour code

Production rollout

Before a Coinbase integration trades unattended

Credentials, product rules, response handling, WebSocket continuity, recovery, and network behavior must all be predictable.

Keep API keys server-side and grant only the permissions each process needs.

Keep product ID, portfolio, API family, and wsKey explicit in code and logs.

Set client_order_id on application-owned orders so retries and restarts can reconcile them.

Read product increments, minimum sizes, status flags, and venue before validating an order.

Check both HTTP errors and operation-level success fields on order-management responses.

Treat an accepted write as pending until a private stream or REST API query confirms state.

Subscribe to heartbeats and reload private state after stream gaps.

Keep the system clock synchronized and respect current Coinbase rate limits.

Monitor proxy reachability, latency, and egress IP when a proxy is enabled.

Choose your path

Jump to the Coinbase workflow you are building

Browse all examples

Start with REST API calls

Make public market calls, add credentials, then inspect accounts and order state.

Open section

Stream live data

Subscribe to public ticker data and private Advanced Trade order updates.

Open section

Understand order management

Preview an order safely, then learn how submission, lookup, cancellation, and confirmation fit together.

Open section

Configure connectivity

Match the client to the Coinbase environment, then add an HTTP or SOCKS proxy when required.

Open section

Build around Coinbase products and account state

This tutorial covers the Coinbase API pieces developers usually need first: Advanced Trade REST API calls, public and private streams, safe order previews, API environments, proxies, and reconnect recovery.

This tutorial uses coinbase-api, Siebly's Node.js and JavaScript SDK for Coinbase. This guide will primarily walk you through using the Coinbase Advanced Trade APIs & WebSockets for public market data, authenticated account access, WebSocket streams, and safe order previews.

The SDK handles REST API authentication, short-lived JWT creation, product-specific WebSocket routing, private subscription signing, reconnects, and resubscriptions. It also provides focused clients for Coinbase App, Exchange, International Exchange, Prime, and legacy Commerce APIs.

Key links

Coinbase JavaScript SDK by Siebly: coinbase-api
npm package: coinbase-api
GitHub repository: tiagosiebler/coinbase-api
SDK examples: Coinbase SDK examples
SDK endpoint map: Coinbase JavaScript endpoint reference
Official documentation: Coinbase Developer Documentation
Advanced Trade REST API: Advanced Trade API endpoints
Advanced Trade WebSockets: WebSocket overview
API authentication: Coinbase App API key authentication
Trading-system terms: Siebly glossary
More JavaScript SDKs: Siebly.io

Why use `coinbase-api`?

Private Advanced Trade REST API requests use short-lived JSON Web Tokens signed with a Coinbase Developer Platform API key. Private WebSocket subscriptions also need a fresh JWT, and each subscription must reach the correct Coinbase connection.

coinbase-api handles those mechanics and provides a focused client for each API family, so you can focus on your integration without excessive plumbing efforts:

Client	Use it for
`CBAdvancedTradeClient`	Advanced Trade products, accounts, orders, portfolios, derivatives, fees, and converts
`WebsocketClient`	Advanced Trade, Exchange, International, and Prime WebSocket streams
`CBAppClient`	Coinbase App accounts, addresses, transactions, deposits, withdrawals, and prices
`CBExchangeClient`	Institutional Exchange market data, trading, profiles, reports, loans, and transfers
`CBInternationalClient`	International instruments, portfolios, orders, positions, loans, and transfers
`CBPrimeClient`	Prime portfolios, balances, orders, activities, allocations, wallets, and transactions
`CBCommerceClient`	Legacy Commerce charges, checkouts, and events

The Advanced Trade product group is the right starting point for most developers automating their own Coinbase trading account. The other REST API clients use different account products, credentials, permissions, and sometimes an API passphrase. These are typically catered more towards institutional users.

Install the SDK

npm install coinbase-api

The examples use standard ES module imports. The package also supports CommonJS projects.

Create Coinbase API keys

Public Advanced Trade REST API calls and public WebSocket streams do not need credentials. Private calls and the private user stream need a Coinbase Developer Platform secret API key.

Store the key name and private key in environment variables:

COINBASE_API_KEY_NAME
COINBASE_API_PRIVATE_KEY

The key name is the API key identifier returned by Coinbase. For ECDSA keys it normally has the form organizations/{organization_id}/apiKeys/{key_id}. The private key is the secret signing key, not a Coinbase account password.

coinbase-api accepts the current ECDSA PEM and base64 Ed25519 key formats and detects the signing algorithm automatically. Preserve the private key exactly, including PEM boundaries and line breaks when using an ECDSA key.

When creating a key:

Grant view permission for private account reads and order previews.
Grant trade only to a process that will place or manage orders.
Grant transfer or receive only when the process genuinely needs those actions.
Restrict the key to the intended portfolio.
Add an IP allowlist when the process has stable outbound addresses.
Keep the private key in a server-side secret store and never send it to browser code.

Nothing executable in this tutorial needs transfer or withdrawal access. The order example uses previewOrder() and does not submit an order.

Advanced Trade and Coinbase App keys do not use an API passphrase. Coinbase Exchange, International Exchange, and Prime credentials use a separate API key, secret, and passphrase.

Coinbase products and request vocabulary

Several values determine which market, account, and connection a request uses:

Field or value	Example	Meaning
Product ID	`BTC-USD`	Hyphen-separated trading product with BTC as the base and USD as the quote currency
`base_increment`	Product metadata	Smallest supported change to a base-currency size
`quote_increment`	Product metadata	Smallest supported change to a quote-currency size
`price_increment`	Product metadata	Smallest supported change to an order price
`base_min_size`	Product metadata	Minimum supported base-currency size
`quote_min_size`	Product metadata	Minimum supported quote-currency size
Product status flags	`status`, `trading_disabled`, `limit_only`	Current restrictions that affect valid order requests
Product type and venue	`product_type`, `product_venue`	Distinguish Spot, US futures, and International perpetual products
Portfolio ID	`portfolio_uuid`	Portfolio that owns balances, permissions, orders, or derivative positions
Client order ID	`client_order_id`	Application-owned custom order ID
Order configuration	`market_market_ioc`, `limit_limit_gtc`	Order type, size, time in force, price, and post-only behavior
WebSocket key	`WS_KEY_MAP.advTradeMarketData`	WebSocket key selecting the connection

Advanced Trade REST API methods return the endpoint body directly. There is no shared success envelope. Products are objects, accounts and orders are arrays nested inside response objects, and candles are objects inside a candles array.

Start building: first calls and streams

Run each example on its own. Start with public market data, then add credentials, private state, streams, and an order preview.

1. Make public REST API calls

Public calls need no API key.

import { CBAdvancedTradeClient } from 'coinbase-api';

const client = new CBAdvancedTradeClient();

async function main() {
  try {
    const serverTime = await client.getServerTime();
    console.log('Server time:', serverTime.iso);
  } catch (error) {
    console.error('Server time request failed:', error);
  }

  try {
    const product = await client.getPublicProduct({
      product_id: 'BTC-USD',
    });
    console.log('BTC-USD price:', product.price);
    console.log('Base increment:', product.base_increment);
    console.log('Price increment:', product.price_increment);
  } catch (error) {
    console.error('Product request failed:', error);
  }

  try {
    const orderBook = await client.getPublicProductBook({
      product_id: 'BTC-USD',
      limit: 5,
    });
    console.log('Best bid:', orderBook.pricebook.bids[0]);
    console.log('Best ask:', orderBook.pricebook.asks[0]);
  } catch (error) {
    console.error('Order book request failed:', error);
  }

  const end = Math.floor(Date.now() / 1000);
  const start = end - 60 * 60;

  try {
    const candles = await client.getPublicProductCandles({
      product_id: 'BTC-USD',
      start: String(start),
      end: String(end),
      granularity: 'FIVE_MINUTE',
      limit: 12,
    });
    console.log('Latest candle:', candles.candles[0]);
  } catch (error) {
    console.error('Candles request failed:', error);
  }

  try {
    const marketTrades = await client.getPublicMarketTrades({
      product_id: 'BTC-USD',
      limit: 10,
    });
    console.log('Latest trade:', marketTrades.trades[0]);
    console.log('Best bid:', marketTrades.best_bid);
    console.log('Best ask:', marketTrades.best_ask);
  } catch (error) {
    console.error('Market trades request failed:', error);
  }
}

main();

The methods return different object shapes:

Method	Successful result
`getServerTime()`	Object containing `iso`, `epochSeconds`, and `epochMillis`
`getPublicProduct()`	One product object
`getPublicProductBook()`	Object containing `pricebook`, whose `bids` and `asks` are arrays of price-level objects
`getPublicProductCandles()`	Object containing a `candles` array
`getPublicMarketTrades()`	Object containing `trades`, `best_bid`, and `best_ask`

Each candle has named start, low, high, open, close, and volume fields. Prices, quantities, increments, and timestamps are commonly strings. Keep exchange values as strings until a calculation requires a deliberate conversion.

2. Make private REST API calls

The private client uses the same Advanced Trade class with a key name and private key. The SDK creates and signs a new JWT for each private request.

import { CBAdvancedTradeClient } from 'coinbase-api';

async function main() {
  if (
    !process.env.COINBASE_API_KEY_NAME ||
    !process.env.COINBASE_API_PRIVATE_KEY
  ) {
    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');
    return;
  }

  const client = new CBAdvancedTradeClient({
    apiKey: process.env.COINBASE_API_KEY_NAME,
    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
  });

  try {
    const permissions = await client.getApiKeyPermissions();
    console.log('Can view:', permissions.can_view);
    console.log('Can trade:', permissions.can_trade);
    console.log('Can transfer:', permissions.can_transfer);
    console.log('Portfolio:', permissions.portfolio_uuid);
  } catch (error) {
    console.error('Permission request failed:', error);
  }

  try {
    const accounts = await client.getAccounts({
      limit: 10,
    });
    console.log('Accounts:', accounts.accounts);
    console.log('More accounts available:', accounts.has_next);
  } catch (error) {
    console.error('Account request failed:', error);
  }

  try {
    const openOrders = await client.getOrders({
      order_status: ['OPEN'],
      limit: 20,
    });
    console.log('Open orders:', openOrders.orders);
    console.log('More orders available:', openOrders.has_next);
  } catch (error) {
    console.error('Open-order request failed:', error);
  }

  try {
    const fills = await client.getFills({
      product_ids: ['BTC-USD'],
      limit: 20,
    });
    console.log('Recent BTC-USD fills:', fills.fills);
    console.log('Next cursor:', fills.cursor);
  } catch (error) {
    console.error('Fill request failed:', error);
  }
}

main();

getAccounts() and getOrders() expose pagination fields alongside their arrays. getFills() returns its fills array and an optional cursor. Follow the returned cursor when the application needs more than one page.

HTTP failures are rejected as parsed errors containing the status, response body, headers, and request context. Credentials are omitted from those parsed error objects. Order-management methods can also return a successful HTTP response whose operation-level success field is false, so both layers must be checked.

Use the Advanced Trade market-data connection for public channels. Subscribe to heartbeats alongside the ticker so the connection remains active when another channel has no updates.

import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';

function main() {
  const ws = new WebsocketClient();

  ws.on('open', ({ wsKey }) => {
    console.log('WebSocket opened:', wsKey);
  });

  ws.on('response', (response) => {
    console.log(
      'WebSocket response:',
      response.wsKey,
      response.channel,
      response.events,
    );
  });

  ws.on('update', (update) => {
    console.log(
      'WebSocket update:',
      update.wsKey,
      update.channel,
      update.events,
    );
  });

  ws.on('reconnect', ({ wsKey }) => {
    console.log('Reconnecting:', wsKey);
  });

  ws.on('reconnected', ({ wsKey }) => {
    console.log('Reconnected:', wsKey);
  });

  ws.on('close', ({ wsKey }) => {
    console.log('WebSocket closed:', wsKey);
  });

  ws.on('exception', (error) => {
    console.error('WebSocket exception:', error);
  });

  try {
    ws.subscribe(
      {
        topic: 'ticker',
        payload: {
          product_ids: ['BTC-USD'],
        },
      },
      WS_KEY_MAP.advTradeMarketData,
    );
  } catch (error) {
    console.error('Ticker subscription failed:', error);
  }

  try {
    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);
  } catch (error) {
    console.error('Heartbeat subscription failed:', error);
  }

  process.once('SIGINT', () => {
    ws.closeAll();
  });
}

main();

A message whose channel is subscriptions is the subscription acknowledgement. Market snapshots and later changes arrive through update, where each event has a channel-specific shape and a type such as snapshot or update.

The SDK adds wsKey to emitted events so one handler can identify the source connection. After an unexpected disconnect, it reconnects and restores tracked subscriptions.

The private user-data connection provides order and position updates for the authenticated account. The SDK signs each subscription with a fresh JWT.

import { WebsocketClient, WS_KEY_MAP } from 'coinbase-api';

function main() {
  if (
    !process.env.COINBASE_API_KEY_NAME ||
    !process.env.COINBASE_API_PRIVATE_KEY
  ) {
    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');
    return;
  }

  const ws = new WebsocketClient({
    apiKey: process.env.COINBASE_API_KEY_NAME,
    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
  });

  ws.on('open', ({ wsKey }) => {
    console.log('Private WebSocket opened:', wsKey);
  });

  ws.on('response', (response) => {
    console.log(
      'Private WebSocket response:',
      response.wsKey,
      response.channel,
      response.events,
    );
  });

  ws.on('update', (update) => {
    console.log('Private update:', update.wsKey, update.channel, update.events);
  });

  ws.on('reconnect', ({ wsKey }) => {
    console.log('Private WebSocket reconnecting:', wsKey);
  });

  ws.on('reconnected', ({ wsKey }) => {
    console.log('Private WebSocket reconnected:', wsKey);
  });

  ws.on('close', ({ wsKey }) => {
    console.log('Private WebSocket closed:', wsKey);
  });

  ws.on('exception', (error) => {
    console.error('Private WebSocket exception:', error);
  });

  try {
    ws.subscribe(
      {
        topic: 'user',
        payload: {
          product_ids: ['BTC-USD'],
        },
      },
      WS_KEY_MAP.advTradeUserData,
    );
  } catch (error) {
    console.error('User subscription failed:', error);
  }

  try {
    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeUserData);
  } catch (error) {
    console.error('Heartbeat subscription failed:', error);
  }

  process.once('SIGINT', () => {
    ws.closeAll();
  });
}

main();

The first user messages contain the account's current open orders, followed by later order changes. Coinbase can split a large initial snapshot across multiple messages. Preserve the event type and sequence information when building local account state.

An eligible derivatives account can also subscribe to futures_balance_summary through WS_KEY_MAP.advTradeUserData. Keep that subscription separate from user because Coinbase requires one channel per subscription request.

Private order updates provide private stream confirmation after a write. A subscription acknowledgement only confirms the stream subscription, not an order state.

5. Preview a Spot order with the REST API

previewOrder() validates an order configuration and returns estimated totals, commission, market prices, warnings, and validation errors. It does not submit an order to the matching engine.

This example reads the current BTC-USD minimum quote size and uses it for a market-buy preview.

import { CBAdvancedTradeClient } from 'coinbase-api';

async function main() {
  if (
    !process.env.COINBASE_API_KEY_NAME ||
    !process.env.COINBASE_API_PRIVATE_KEY
  ) {
    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');
    return;
  }

  const client = new CBAdvancedTradeClient({
    apiKey: process.env.COINBASE_API_KEY_NAME,
    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
  });

  let product;

  try {
    product = await client.getPublicProduct({
      product_id: 'BTC-USD',
    });
    console.log('Minimum quote size:', product.quote_min_size);
  } catch (error) {
    console.error('Product request failed:', error);
    return;
  }

  if (
    !product.quote_min_size ||
    !Number.isFinite(Number(product.quote_min_size)) ||
    Number(product.quote_min_size) <= 0
  ) {
    console.error('BTC-USD returned an invalid quote_min_size.');
    return;
  }

  try {
    const preview = await client.previewOrder({
      product_id: 'BTC-USD',
      side: 'BUY',
      order_configuration: {
        market_market_ioc: {
          quote_size: product.quote_min_size,
        },
      },
    });

    console.log('Validation errors:', preview.errs);
    console.log('Warnings:', preview.warning);
    console.log('Order total:', preview.order_total);
    console.log('Commission total:', preview.commission_total);
    console.log('Best bid:', preview.best_bid);
    console.log('Best ask:', preview.best_ask);
    console.log('Preview ID:', preview.preview_id);
  } catch (error) {
    console.error('Order preview failed:', error);
  }
}

main();

The preview endpoint needs view permission. Check errs before using any estimate. Warnings may describe conditions that do not make the request invalid, while an error means the configuration cannot currently be accepted.

preview_id identifies this preview result. Passing it to a later order request does not remove the need to validate current product rules and check the order response. This tutorial stops after the preview and never calls submitOrder().

Work with the Advanced Trade REST API

Understand response shapes

Advanced Trade REST API methods return the endpoint body. The top-level shape depends on the method:

Operation	Main response fields
List accounts	`accounts`, `has_next`, `cursor`, `size`
List orders	`orders`, `has_next`, optional `cursor` and `sequence`
List fills	`fills`, optional `cursor`
Product book	`pricebook`, with `bids`, `asks`, and `time`
Product candles	`candles`
Market trades	`trades`, `best_bid`, `best_ask`
Submit order	`success`, `success_response`, `error_response`, `order_configuration`
Cancel orders	`results`, with one result for each requested order ID
Preview order	`errs`, `warning`, totals, sizes, market prices, and `preview_id`

Do not assume that a successful HTTP status means an order-management operation succeeded. For example, submitOrder() can return success: false with details under error_response.

Read account and order state

The private methods used most often for account state are:

Method	Purpose
`getApiKeyPermissions()`	Read the key's current permissions and portfolio scope
`getAccounts()`	List currency accounts, available balances, and holds
`getAccount()`	Read one currency account
`getOrders()`	List orders using product, status, side, type, and time filters
`getOrder()`	Read one order by exchange order ID
`getFills()`	List fills by product, order, trade, time, or cursor
`getTransactionSummary()`	Read current volume and fee-tier information

Use cursors until the required history window is complete. Keep product IDs, order IDs, client order IDs, and cursor values with the data they identify.

Understand Advanced Trade order management

Advanced Trade order commands use CBAdvancedTradeClient. The WebsocketClient provides streams and does not send order commands.

Choose an order configuration

The request's order_configuration contains one order type. Common configurations include:

Configuration	Use
`market_market_ioc`	Market order using a base or quote size
`limit_limit_gtc`	Limit order that remains active until filled or cancelled
`limit_limit_gtd`	Limit order with an expiry time
`limit_limit_fok`	Limit order that must fill completely and immediately or be cancelled
`sor_limit_ioc`	Smart order-router limit order with immediate-or-cancel behavior
Stop and bracket configurations	Conditional exits and attached risk controls

A limit_limit_gtc configuration can set post_only: true. A post-only order is rejected or cancelled rather than immediately taking liquidity. It can still fill after resting on the book, so it is not a risk-free live test.

Always apply current base_increment, quote_increment, price_increment, minimum sizes, maximum sizes, and product status flags. Derivative products add contract, margin, session, and eligibility rules.

Use client order IDs

Call client.generateNewOrderId() when an application will submit an order. The SDK generates an identifier with its required cbnode prefix. If a supplied client_order_id does not have that prefix, the SDK adds it and logs a warning.

Persist both the custom order ID and Coinbase order ID. The client order ID lets a process reconcile an uncertain request after a timeout or restart.

Follow the order lifecycle

The main REST API methods are:

Method	Operation
`previewOrder()`	Validate and estimate an order without submitting it
`submitOrder()`	Submit a new order
`getOrder()`	Query one order
`getOrders()`	List matching orders
`updateOrderPreview()`	Preview an order edit
`updateOrder()`	Edit an eligible order
`cancelOrders()`	Request cancellation for one or more order IDs

For a submitted order:

Check the HTTP request outcome.
Check the returned success field.
Read the Coinbase order ID from success_response only when success is true.
Treat the result as pending confirmation.
Confirm the final state through the private user stream or getOrder().

If a write times out without a clear result, query by the known Coinbase order ID or reconcile the client order ID before retrying. Blindly submitting the same intent again can create a second live order.

Know what WebSockets do

coinbase-api does not expose a WebsocketAPIClient for Coinbase because its supported Coinbase WebSocket interfaces are subscription feeds. Use:

WebsocketClient for market and account updates.
CBAdvancedTradeClient for preview, submit, edit, query, and cancel commands.

A subscription response acknowledges a channel. It is not an order acknowledgement and does not confirm account state.

Explore other Advanced Trade groups

The Advanced Trade client covers more than Spot orders:

Group	Representative methods
Authenticated market data	`getProducts()`, `getProduct()`, `getBestBidAsk()`, `getProductBook()`
Portfolios	`getPortfolios()`, `getPortfolioBreakdown()`, `createPortfolio()`, `updatePortfolio()`
Fees	`getTransactionSummary()`
Converts	`submitConvertQuote()`, `getConvertTrade()`, `commitConvertTrade()`
Payment methods	`getPaymentMethods()`, `getPaymentMethod()`
US futures	`getFuturesBalanceSummary()`, `getFuturesPositions()`, `getFuturesSweeps()`
Futures margin	`getIntradayMarginSetting()`, `getCurrentMarginWindow()`
International perpetuals	`getPerpetualsPortfolioSummary()`, `getPerpetualsPositions()`, `getPortfoliosBalances()`
International collateral	`allocatePortfolio()`, `updateMultiAssetCollateral()`

US futures and International perpetual products are available only to eligible accounts and jurisdictions. Read product metadata and account state rather than assuming that a product visible in public data is tradable by the authenticated portfolio.

For the full method-to-endpoint map, use the Coinbase SDK endpoint reference.

Build with Coinbase WebSocket streams

Choose the correct WebSocket key

Each wsKey identifies one Coinbase WebSocket connection:

WebSocket key	Authentication	Use
`WS_KEY_MAP.advTradeMarketData`	Public	Advanced Trade ticker, level 2, trades, candles, and status
`WS_KEY_MAP.advTradeUserData`	Required	Advanced Trade user orders and futures balance summaries
`WS_KEY_MAP.exchangeMarketData`	Public	Coinbase Exchange market-data feed
`WS_KEY_MAP.exchangeDirectMarketData`	Required	Coinbase Exchange direct market-data feed
`WS_KEY_MAP.internationalMarketData`	Required	Coinbase International market-data feed
`WS_KEY_MAP.primeMarketData`	Required	Coinbase Prime market-data feed

Pass WS_KEY_MAP values explicitly. This keeps connection routing visible and prevents a topic from reaching the wrong API family.

Use the Advanced Trade channels

Channel	Authentication	Main use
`heartbeats`	Public	Keep subscriptions open and detect missed heartbeat counts
`ticker`	Public	Price, volume, and best bid or ask changes
`ticker_batch`	Public	Batched ticker changes
`market_trades`	Public	Recent trade updates
`level2`	Public	Order-book snapshots and updates
`candles`	Public	Five-minute candle updates
`status`	Public	Product and currency status
`user`	Required	Current open orders and later order or position changes
`futures_balance_summary`	Required	Futures balance changes for eligible accounts

Coinbase requires one channel per Advanced Trade subscription request. Send separate subscribe() calls when a process needs ticker and heartbeat data.

Treat responses and updates differently

The SDK emits:

open when a connection is ready.
response for subscription responses and exchange errors.
update for snapshots and later channel data.
reconnect when it begins restoring a dropped connection.
reconnected after the replacement connection opens.
close when a connection closes.
exception for connection, parsing, signing, or subscription failures.

Keep each event's wsKey, channel, sequence_num, and event type. A subscriptions response confirms the requested channel is active. It does not replace the initial channel snapshot or later updates.

Recover private state after a reconnect

Automatic reconnection restores the socket and cached subscriptions. It cannot prove that every private event was received before or during the gap. Rebuild the affected account state through the REST API after advTradeUserData reconnects.

This example reloads accounts, open orders, and recent BTC-USD fills sequentially. It replaces local state only when all three reads succeed.

import {
  CBAdvancedTradeClient,
  WebsocketClient,
  WS_KEY_MAP,
} from 'coinbase-api';

async function main() {
  if (
    !process.env.COINBASE_API_KEY_NAME ||
    !process.env.COINBASE_API_PRIVATE_KEY
  ) {
    console.error('Set COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY.');
    return;
  }

  const credentials = {
    apiKey: process.env.COINBASE_API_KEY_NAME,
    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
  };

  const rest = new CBAdvancedTradeClient(credentials);
  const ws = new WebsocketClient(credentials);

  let accountState;

  ws.on('update', (update) => {
    console.log('Private update:', update.channel, update.events);
  });

  ws.on('reconnected', async ({ wsKey }) => {
    if (wsKey !== WS_KEY_MAP.advTradeUserData) {
      return;
    }

    let accountsResponse;
    let ordersResponse;
    let fillsResponse;

    try {
      accountsResponse = await rest.getAccounts({
        limit: 250,
      });
    } catch (error) {
      console.error('Account recovery failed:', error);
      return;
    }

    try {
      ordersResponse = await rest.getOrders({
        order_status: ['OPEN'],
        limit: 250,
      });
    } catch (error) {
      console.error('Open-order recovery failed:', error);
      return;
    }

    try {
      fillsResponse = await rest.getFills({
        product_ids: ['BTC-USD'],
        limit: 100,
      });
    } catch (error) {
      console.error('Fill recovery failed:', error);
      return;
    }

    const replacement = {
      accounts: accountsResponse.accounts,
      openOrders: ordersResponse.orders,
      recentFills: fillsResponse.fills,
      recoveredAt: new Date().toISOString(),
    };

    accountState = replacement;
    console.log('Private state recovered:', accountState.recoveredAt);
  });

  ws.on('exception', (error) => {
    console.error('WebSocket exception:', error);
  });

  try {
    ws.subscribe(
      {
        topic: 'user',
        payload: {
          product_ids: ['BTC-USD'],
        },
      },
      WS_KEY_MAP.advTradeUserData,
    );
  } catch (error) {
    console.error('User subscription failed:', error);
  }

  try {
    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeUserData);
  } catch (error) {
    console.error('Heartbeat subscription failed:', error);
  }

  process.once('SIGINT', () => {
    ws.closeAll();
  });
}

main();

For a complete implementation, paginate until the required recovery window is covered. A production state owner should also buffer new private updates while recovery is running, apply the replacement snapshot, and then replay updates newer than the snapshot boundary.

See:

Choose the Coinbase API family

The package covers several Coinbase products. Their credentials and account models are not interchangeable.

Client	Representative coverage
`CBAdvancedTradeClient`	Retail trading, portfolios, Spot, US futures, International perpetuals, fees, and converts
`CBAppClient`	Coinbase App accounts, addresses, transactions, deposits, withdrawals, and public prices
`CBExchangeClient`	Institutional Exchange products, accounts, orders, fills, profiles, reports, loans, and transfers
`CBInternationalClient`	International instruments, portfolios, balances, positions, orders, fills, loans, and transfers
`CBPrimeClient`	Prime portfolios, balances, orders, allocations, activities, wallets, and transactions
`CBCommerceClient`	Legacy Commerce charges, checkouts, and events

Use Advanced Trade for a normal Coinbase retail trading account. Coinbase Exchange, International Exchange, and Prime require the matching institutional account and credentials.

CBCommerceClient maps the legacy api.commerce.coinbase.com charge and checkout endpoints. Coinbase now directs new payment integrations toward Coinbase Business Checkouts. Review the official Commerce-to-Checkouts migration guide before starting a new payments integration.

Connect to live APIs and sandboxes

Each Coinbase client has its own default REST API host. The WebSocket client selects a host from the requested wsKey.

API or environment	REST API host	WebSocket host or guidance
Advanced Trade live	`https://api.coinbase.com`	`wss://advanced-trade-ws.coinbase.com` for market data
Advanced Trade private stream	`https://api.coinbase.com`	`wss://advanced-trade-ws-user.coinbase.com`
Advanced Trade static sandbox	`https://api-sandbox.coinbase.com`	No Advanced Trade sandbox WebSocket
Coinbase App live	`https://api.coinbase.com`	No Coinbase App stream in this SDK
Coinbase Exchange live	`https://api.exchange.coinbase.com`	`wss://ws-feed.exchange.coinbase.com` or the authenticated direct feed
Coinbase Exchange sandbox	`https://api-public.sandbox.exchange.coinbase.com`	`wss://ws-feed-public.sandbox.exchange.coinbase.com` or its direct sandbox feed
International Exchange live	`https://api.international.coinbase.com`	`wss://ws-md.international.coinbase.com`
International Exchange sandbox	`https://api-n5e1.coinbase.com`	`wss://ws-md.n5e2.coinbase.com`
Coinbase Prime live	`https://api.prime.coinbase.com`	`wss://ws-feed.prime.coinbase.com`
Legacy Commerce live	`https://api.commerce.coinbase.com`	No Commerce stream in this SDK

The Advanced Trade static sandbox returns predefined mock responses for a limited set of account and order endpoints. It does not run a matching engine and is not a funded trading environment.

useSandbox: true is supported by CBExchangeClient and CBInternationalClient, and by the matching Exchange or International WebSocket connections. Sandbox credentials are separate from production credentials.

Do not set useSandbox: true on CBAdvancedTradeClient or an Advanced Trade WebSocket connection. Use public live data and previewOrder() for the safe Advanced Trade workflow in this tutorial.

Official environment references:

Coinbase does not expose one generic region switch for every API family. Account type, portfolio access, jurisdiction, and product eligibility determine the available APIs and products. A proxy does not change those rules.

Use a proxy with the REST API and WebSockets

A proxy can provide a stable egress IP, an approved corporate network route, or controlled network failover. It changes the network path to Coinbase, not the selected API family, account permissions, jurisdiction, or product eligibility.

See Using a proxy with Siebly SDKs for the general networking pattern.

HTTP or HTTPS proxy

Install the proxy agent:

npm install coinbase-api https-proxy-agent

Pass the agent through the second REST API client argument and through wsOptions.agent for WebSockets.

import { HttpsProxyAgent } from 'https-proxy-agent';
import {
  CBAdvancedTradeClient,
  WebsocketClient,
  WS_KEY_MAP,
} from 'coinbase-api';

async function main() {
  if (!process.env.COINBASE_PROXY_URL) {
    console.error('Set COINBASE_PROXY_URL.');
    return;
  }

  const proxyAgent = new HttpsProxyAgent(process.env.COINBASE_PROXY_URL);

  const rest = new CBAdvancedTradeClient(
    {},
    {
      httpsAgent: proxyAgent,
      proxy: false,
    },
  );

  const ws = new WebsocketClient({
    wsOptions: {
      agent: proxyAgent,
    },
  });

  try {
    const serverTime = await rest.getServerTime();
    console.log('REST API through proxy:', serverTime.iso);
  } catch (error) {
    console.error('Proxied REST API request failed:', error);
  }

  ws.on('open', ({ wsKey }) => {
    console.log('Proxied WebSocket opened:', wsKey);
  });

  ws.on('response', (response) => {
    console.log(
      'Proxied WebSocket response:',
      response.wsKey,
      response.channel,
    );
  });

  ws.on('update', (update) => {
    console.log(
      'Proxied WebSocket update:',
      update.wsKey,
      update.channel,
      update.events,
    );
  });

  ws.on('exception', (error) => {
    console.error('Proxied WebSocket exception:', error);
  });

  try {
    ws.subscribe(
      {
        topic: 'ticker',
        payload: {
          product_ids: ['BTC-USD'],
        },
      },
      WS_KEY_MAP.advTradeMarketData,
    );
  } catch (error) {
    console.error('Proxied ticker subscription failed:', error);
  }

  try {
    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);
  } catch (error) {
    console.error('Proxied heartbeat subscription failed:', error);
  }

  process.once('SIGINT', () => {
    ws.closeAll();
  });
}

main();

httpsAgent carries HTTPS REST API requests through the proxy. proxy: false prevents Axios from adding a second proxy layer. HttpsProxyAgent accepts both HTTP and HTTPS proxy URLs.

For authenticated traffic, add credentials to the same constructors:

import { HttpsProxyAgent } from 'https-proxy-agent';
import { CBAdvancedTradeClient, WebsocketClient } from 'coinbase-api';

function main() {
  if (
    !process.env.COINBASE_PROXY_URL ||
    !process.env.COINBASE_API_KEY_NAME ||
    !process.env.COINBASE_API_PRIVATE_KEY
  ) {
    console.error(
      'Set COINBASE_PROXY_URL, COINBASE_API_KEY_NAME, and COINBASE_API_PRIVATE_KEY.',
    );
    return;
  }

  const proxyAgent = new HttpsProxyAgent(process.env.COINBASE_PROXY_URL);

  const privateRest = new CBAdvancedTradeClient(
    {
      apiKey: process.env.COINBASE_API_KEY_NAME,
      apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
    },
    {
      httpsAgent: proxyAgent,
      proxy: false,
    },
  );

  const privateWs = new WebsocketClient({
    apiKey: process.env.COINBASE_API_KEY_NAME,
    apiSecret: process.env.COINBASE_API_PRIVATE_KEY,
    wsOptions: {
      agent: proxyAgent,
    },
  });

  console.log(
    'Private REST API and WebSocket clients are configured:',
    Boolean(privateRest),
    Boolean(privateWs),
  );
}

main();

This only constructs the authenticated clients. It does not make a private request, open a private stream, or submit an order.

SOCKS5 proxy

Install:

npm install coinbase-api socks-proxy-agent

Use the same constructor positions with SocksProxyAgent.

import { SocksProxyAgent } from 'socks-proxy-agent';
import {
  CBAdvancedTradeClient,
  WebsocketClient,
  WS_KEY_MAP,
} from 'coinbase-api';

async function main() {
  if (!process.env.COINBASE_SOCKS_PROXY_URL) {
    console.error('Set COINBASE_SOCKS_PROXY_URL.');
    return;
  }

  const proxyAgent = new SocksProxyAgent(process.env.COINBASE_SOCKS_PROXY_URL);

  const rest = new CBAdvancedTradeClient(
    {},
    {
      httpsAgent: proxyAgent,
      proxy: false,
    },
  );

  const ws = new WebsocketClient({
    wsOptions: {
      agent: proxyAgent,
    },
  });

  try {
    const serverTime = await rest.getServerTime();
    console.log('REST API through SOCKS5:', serverTime.iso);
  } catch (error) {
    console.error('SOCKS5 REST API request failed:', error);
  }

  ws.on('open', ({ wsKey }) => {
    console.log('SOCKS5 WebSocket opened:', wsKey);
  });

  ws.on('response', (response) => {
    console.log('SOCKS5 WebSocket response:', response.wsKey, response.channel);
  });

  ws.on('update', (update) => {
    console.log(
      'SOCKS5 WebSocket update:',
      update.wsKey,
      update.channel,
      update.events,
    );
  });

  ws.on('exception', (error) => {
    console.error('SOCKS5 WebSocket exception:', error);
  });

  try {
    ws.subscribe(
      {
        topic: 'ticker',
        payload: {
          product_ids: ['BTC-USD'],
        },
      },
      WS_KEY_MAP.advTradeMarketData,
    );
  } catch (error) {
    console.error('SOCKS5 ticker subscription failed:', error);
  }

  try {
    ws.subscribe('heartbeats', WS_KEY_MAP.advTradeMarketData);
  } catch (error) {
    console.error('SOCKS5 heartbeat subscription failed:', error);
  }

  process.once('SIGINT', () => {
    ws.closeAll();
  });
}

main();

Proxy checks

Keep proxy URLs and credentials in environment variables or a secret manager.
URL-encode proxy usernames and passwords when composing a URL from separate values.
Make sure the proxy egress IP matches the API key's IP allowlist.
Test a public REST API request and public WebSocket subscription before private authentication.
Monitor REST API latency, WebSocket connection time, and reconnect frequency.
Treat HTTP 407 responses, TLS failures, and repeated reconnects as network faults.
Do not log complete proxy URLs because they may contain credentials.
Keep the host clock synchronized because private request JWTs are time-sensitive.
The SDK does not rotate proxy endpoints.

Production checklist

Keep request time accurate

Advanced Trade JWTs are short-lived. Keep the host clock synchronized and alert on clock drift before it causes authentication failures.

Respect rate limits and caching

Coinbase applies REST API, WebSocket connection, and message limits. Public Advanced Trade REST API endpoints can also use a short cache. Use WebSockets for continuously changing prices and books, follow current response headers, and back off after rate-limit responses.

Apply current product rules

Read product metadata before validating an order. Apply the current increments, minimum and maximum sizes, trading status, venue, product type, session details, and account eligibility.

Do not assume that the rules for BTC-USD apply to another Spot, futures, or perpetual product.

Use client order IDs

Generate and persist a unique client_order_id for each application-owned order. Store it with the Coinbase order ID, product, side, configuration, requested size, and creation time.

Confirm final state

An accepted write is not proof of a fill, cancellation, or final order status. Confirm through the private user stream or a REST API query.

After an uncertain timeout, reconcile known identifiers before retrying.

Keep WebSocket streams healthy

Subscribe to heartbeats alongside other Advanced Trade channels. Monitor sequence numbers, heartbeat counters, exceptions, reconnects, and time since the last update.

Reload the affected account state after a private stream gap.

Scope credentials and network access

Keep API keys and proxy credentials out of source control, browser bundles, logs, and error reporting. Grant only the required permissions and portfolio access. Use stable allowlisted egress IPs where practical.

API keys in this guide are for a server acting on its own Coinbase account. An application acting for other Coinbase users should use Coinbase's current OAuth flow rather than collecting users' private API keys.

Shut down connections

Call closeAll() during controlled process shutdown. Use unsubscribe() only when a long-running process should stop selected topics while keeping a connection active.

FAQ

Does `coinbase-api` work with plain JavaScript?

Yes. Every example in this tutorial is plain JavaScript. The package also publishes TypeScript declarations for projects that use them.

Which REST API client should I use?

Use CBAdvancedTradeClient for a normal Coinbase retail trading account. Use the App, Exchange, International, Prime, or Commerce client only when the Coinbase account and workflow belong to that API family.

What are `COINBASE_API_KEY_NAME` and `COINBASE_API_PRIVATE_KEY`?

The key name identifies a Coinbase Developer Platform secret API key. The private key signs requests and subscriptions. It is not the Coinbase account password.

Does Advanced Trade use an API passphrase?

No. Advanced Trade and Coinbase App use a key name and private signing key. Exchange, International Exchange, and Prime credentials include a separate API passphrase.

Can I use ECDSA and Ed25519 keys?

coinbase-api supports both current Coinbase key formats and detects the signing algorithm from the private key. Preserve the complete ECDSA PEM or base64 Ed25519 value.

Why do Advanced Trade REST API responses have different shapes?

The SDK returns each endpoint body directly. A product is one object, accounts are under accounts, orders are under orders, candles are under candles, and trades are under trades.

Why can an order response fail with an HTTP success status?

Some order-management endpoints report operation-level success inside the response body. Check success, then read success_response or error_response as appropriate.

What is the difference between Advanced Trade and Coinbase Exchange?

Advanced Trade is the normal Coinbase trading API for retail users. Coinbase Exchange is an institutional API product with separate accounts, credentials, permissions, hosts, and market structure.

Does Advanced Trade have a sandbox?

Coinbase provides a static Advanced Trade sandbox with predefined mock responses for selected account and order endpoints. It does not run a matching engine. useSandbox: true is not supported by CBAdvancedTradeClient.

Does `previewOrder()` place an order?

No. It validates and estimates the request but does not submit it to the matching engine. Check errs and warning before using its estimates.

Why is there no Coinbase `WebsocketAPIClient`?

The Coinbase WebSocket interfaces supported by this SDK are subscription feeds. Use WebsocketClient for streams and the matching REST API client for order commands.

What does the first private `user` update contain?

Coinbase sends current open-order snapshots before later changes. Large snapshots can be split across multiple messages, so process event types and sequence information rather than treating the first message as complete.

Why should I subscribe to `heartbeats`?

Heartbeats keep quiet Advanced Trade subscriptions open and expose a counter that can help detect missed messages.

What should happen after a private WebSocket reconnect?

Restore the subscription, then reload affected account state through the REST API. Replace local state only after the required reads complete and reconcile updates received during recovery.

What causes timestamp or signature errors?

Common causes include clock drift, an incorrectly stored private key, lost PEM line breaks, a key for the wrong API family, insufficient portfolio permissions, or a proxy sending traffic from an unexpected IP.

Can a proxy change Coinbase product availability?

No. A proxy changes the network route. It does not change the API family, account region, jurisdiction, portfolio permissions, or product eligibility.

Can I use API keys for other Coinbase users?

API key authentication is for server-side access to an account you control. Use Coinbase's current OAuth guidance when an application needs authorization from other users.

Coinbase API JavaScript Tutorial for Node.js

Choose the Coinbase client for the job

Product, portfolio, connection, and API family are separate choices

What to get right in a Coinbase integration

Advanced Trade REST API calls

Public and private WebSocket streams

Safe order previews

API families, sandboxes, and proxies

First REST API calls, streams, order preview, recovery, and proxies

REST API, WebSocket, and order-preview workflows

REST API request flow

WebSocket subscription flow

Safe order-preview flow

Before a Coinbase integration trades unattended

Jump to the Coinbase workflow you are building

Start with REST API calls

Stream live data

Understand order management

Configure connectivity

Build around Coinbase products and account state

Why use coinbase-api?

Install the SDK

Create Coinbase API keys

Coinbase products and request vocabulary

Start building: first calls and streams

1. Make public REST API calls

2. Make private REST API calls

3. Subscribe to public Advanced Trade WebSocket streams

4. Subscribe to the private Advanced Trade user stream

5. Preview a Spot order with the REST API

Work with the Advanced Trade REST API

Understand response shapes

Read account and order state

Understand Advanced Trade order management

Choose an order configuration

Use client order IDs

Follow the order lifecycle

Know what WebSockets do

Explore other Advanced Trade groups

Build with Coinbase WebSocket streams

Choose the correct WebSocket key

Use the Advanced Trade channels

Treat responses and updates differently

Recover private state after a reconnect

Choose the Coinbase API family

Connect to live APIs and sandboxes

Use a proxy with the REST API and WebSockets

HTTP or HTTPS proxy

SOCKS5 proxy

Proxy checks

Production checklist

Keep request time accurate

Respect rate limits and caching

Apply current product rules

Use client order IDs

Confirm final state

Keep WebSocket streams healthy

Scope credentials and network access

Shut down connections

FAQ

Does coinbase-api work with plain JavaScript?

Which REST API client should I use?

What are COINBASE_API_KEY_NAME and COINBASE_API_PRIVATE_KEY?

Does Advanced Trade use an API passphrase?

Can I use ECDSA and Ed25519 keys?

Why do Advanced Trade REST API responses have different shapes?

Why can an order response fail with an HTTP success status?

What is the difference between Advanced Trade and Coinbase Exchange?

Does Advanced Trade have a sandbox?

Does previewOrder() place an order?

Why is there no Coinbase WebsocketAPIClient?

What does the first private user update contain?

Why should I subscribe to heartbeats?

What should happen after a private WebSocket reconnect?

What causes timestamp or signature errors?

Can a proxy change Coinbase product availability?

Can I use API keys for other Coinbase users?

Next steps

Coinbase SDK page

Coinbase examples

Why use `coinbase-api`?

Does `coinbase-api` work with plain JavaScript?

What are `COINBASE_API_KEY_NAME` and `COINBASE_API_PRIVATE_KEY`?

Does `previewOrder()` place an order?

Why is there no Coinbase `WebsocketAPIClient`?

What does the first private `user` update contain?

Why should I subscribe to `heartbeats`?