Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tiagosiebler/coinbase-api/llms.txt
Use this file to discover all available pages before exploring further.
This guide walks you through installing coinbase-api, configuring credentials, and making your first authenticated REST and WebSocket calls. By the end you will have a working Node.js script that fetches your Coinbase accounts and subscribes to live ticker updates.
This quickstart uses CBAdvancedTradeClient as the example. The same patterns apply to every other client in the SDK. See the Authentication guide for credential setup details for Exchange, International, and Prime clients. The package ships precompiled ESM and CJS builds — no build step required in your project.
For Advanced Trade and App APIs: Coinbase issues a CDP API key, which downloads as a cdp_api_key.json file containing a name and privateKey field. Both ECDSA and ED25519 key types are supported.
For Exchange, International, and Prime APIs: Coinbase issues an API key + secret + passphrase combination.
Store your credentials as environment variables — never hard-code them in source files.
export API_KEY_NAME="organizations/your-org-id/apiKeys/your-key-id"
export API_PRIVATE_KEY="-----BEGIN EC PRIVATE KEY-----
...
-----END EC PRIVATE KEY-----"
The SDK gives you two ways to supply credentials for JWT-based clients (CBAdvancedTradeClient and CBAppClient).
TypeScript
import { CBAdvancedTradeClient } from 'coinbase-api';
// Option A: pass the downloaded cdp_api_key.json as an object
const cdpApiKey = {
name: 'organizations/13232211d-d7e2-d7e2-d7e2-d7e2d7e2d7e2/apiKeys/d7e2d7e2-d7e2-d7e2-d7e2-d7e2d7e2d7e2',
privateKey:
'-----BEGIN EC PRIVATE KEY-----\nADFGHmkgnjdfg16k165kuu1k...\n-----END EC PRIVATE KEY-----\n',
};
const clientViaJson = new CBAdvancedTradeClient({ cdpApiKey });
// Option B: pass key name as `apiKey` and private key as `apiSecret` directly
const client = new CBAdvancedTradeClient({
apiKey: process.env.API_KEY_NAME!,
apiSecret: process.env.API_PRIVATE_KEY!,
});
JavaScript
const { CBAdvancedTradeClient } = require('coinbase-api');
// Option A: pass the downloaded cdp_api_key.json as an object
const cdpApiKey = {
name: 'organizations/13232211d-d7e2-d7e2-d7e2-d7e2d7e2d7e2/apiKeys/d7e2d7e2-d7e2-d7e2-d7e2-d7e2d7e2d7e2',
privateKey:
'-----BEGIN EC PRIVATE KEY-----\nADFGHmkgnjdfg16k165kuu1k...\n-----END EC PRIVATE KEY-----\n',
};
const clientViaJson = new CBAdvancedTradeClient({ cdpApiKey });
// Option B: pass key name as `apiKey` and private key as `apiSecret` directly
const client = new CBAdvancedTradeClient({
apiKey: process.env.API_KEY_NAME || 'insert_api_key_here',
apiSecret: process.env.API_PRIVATE_KEY || 'insert_api_secret_here',
});
Both ECDSA (PEM-formatted -----BEGIN EC PRIVATE KEY-----) and ED25519 (base64 string) key formats are detected automatically — you do not need to configure the key type manually.
Make your first REST call
TypeScript
import { CBAdvancedTradeClient } from 'coinbase-api';
const client = new CBAdvancedTradeClient({
apiKey: process.env.API_KEY_NAME!,
apiSecret: process.env.API_PRIVATE_KEY!,
});
async function main() {
// Fetch up to 10 accounts
const accounts = await client.getAccounts({ limit: 10 });
console.log('Accounts:', accounts);
// Fetch details for the first account
if (accounts.accounts.length > 0) {
const accountId = accounts.accounts[0].uuid;
const details = await client.getAccount({ account_id: accountId });
console.log('Account details:', details);
}
// Submit a market sell order
const order = await client.submitOrder({
product_id: 'BTC-USDT',
side: 'SELL',
client_order_id: client.generateNewOrderId(),
order_configuration: {
market_market_ioc: { base_size: '0.001' },
},
});
console.log('Order result:', order);
}
main().catch(console.error);
JavaScript
const { CBAdvancedTradeClient } = require('coinbase-api');
const client = new CBAdvancedTradeClient({
apiKey: process.env.API_KEY_NAME || 'insert_api_key_here',
apiSecret: process.env.API_PRIVATE_KEY || 'insert_api_secret_here',
});
async function main() {
// Fetch up to 10 accounts
const accounts = await client.getAccounts({ limit: 10 });
console.log('Accounts:', accounts);
// Fetch details for the first account
if (accounts.accounts.length > 0) {
const accountId = accounts.accounts[0].uuid;
const details = await client.getAccount({ account_id: accountId });
console.log('Account details:', details);
}
// Submit a market sell order
const order = await client.submitOrder({
product_id: 'BTC-USDT',
side: 'SELL',
client_order_id: client.generateNewOrderId(),
order_configuration: {
market_market_ioc: { base_size: '0.001' },
},
});
console.log('Order result:', order);
}
main().catch(console.error);
generateNewOrderId() is a utility method on every REST client that produces a unique, prefixed client_order_id string. Coinbase requires this field on every order submission.
Subscribe to WebSocket data
TypeScript
import { WebsocketClient } from 'coinbase-api';
// Public market data — no credentials required
const ws = new WebsocketClient();
ws.on('open', (data) => console.log('Connected:', data?.wsKey));
ws.on('update', (data) => console.log(new Date(), 'Data:', JSON.stringify(data)));
ws.on('reconnect', (data) => console.log('Reconnecting...', data));
ws.on('reconnected', (data) => console.log('Reconnected:', data?.wsKey));
ws.on('close', (data) => console.error('Closed:', data));
ws.on('exception', (data) => console.error('Error:', data));
// Subscribe to BTC-USD and ETH-USD ticker on the Advanced Trade market data feed
ws.subscribe(
{
topic: 'ticker',
payload: { product_ids: ['BTC-USD', 'ETH-USD'] },
},
'advTradeMarketData',
);
// Subscribe to authenticated user order updates
const privateWs = new WebsocketClient({
apiKey: process.env.API_KEY_NAME!,
apiSecret: process.env.API_PRIVATE_KEY!,
});
privateWs.on('update', (data) => console.log('User event:', data));
privateWs.subscribe('user', 'advTradeUserData');
JavaScript
const { WebsocketClient } = require('coinbase-api');
// Public market data — no credentials required
const ws = new WebsocketClient();
ws.on('open', (data) => console.log('Connected:', data?.wsKey));
ws.on('update', (data) => console.log(new Date(), 'Data:', JSON.stringify(data)));
ws.on('reconnect', (data) => console.log('Reconnecting...', data));
ws.on('reconnected', (data) => console.log('Reconnected:', data?.wsKey));
ws.on('close', (data) => console.error('Closed:', data));
ws.on('exception', (data) => console.error('Error:', data));
// Subscribe to BTC-USD and ETH-USD ticker on the Advanced Trade market data feed
ws.subscribe(
{
topic: 'ticker',
payload: { product_ids: ['BTC-USD', 'ETH-USD'] },
},
'advTradeMarketData',
);
// Subscribe to authenticated user order updates
const privateWs = new WebsocketClient({
apiKey: process.env.API_KEY_NAME || 'insert_api_key_here',
apiSecret: process.env.API_PRIVATE_KEY || 'insert_api_secret_here',
});
privateWs.on('update', (data) => console.log('User event:', data));
privateWs.subscribe('user', 'advTradeUserData');
The WebsocketClient automatically manages connection lifecycle: it sends heartbeat pings, detects dropped connections, reconnects, and replays all subscriptions without any extra code on your side.
ESM vs CJS imports
Both module systems are fully supported. The correct build is selected automatically by Node.js at runtime.
// ESM — TypeScript, .mjs files, or projects with "type": "module"
import { CBAdvancedTradeClient, WebsocketClient } from 'coinbase-api';
// CJS — traditional require-based projects
const { CBAdvancedTradeClient, WebsocketClient } = require('coinbase-api');
Next Steps
