@coinbase-sample/prime-sdk-ts

Coinbase Prime API TypeScript SDK

Overview

Welcome to the Coinbase Prime API TypeScript SDK. This TypeScript project provides a comprehensive, type-safe interface to the Coinbase Prime API with multiple consumption patterns optimized for different use cases.

License

The Prime Typescript SDK sample library is free and open source and released under the Apache License, Version 2.0.

The application and code are only available for demonstration purposes.

🚀 Quick Start

Installation

npm install @coinbase-sample/prime-sdk-ts

Basic Usage (Recommended)

The SDK provides a modular client with lazy-loaded services for the best developer experience:

import { CoinbasePrimeClientWithServices } from '@coinbase-sample/prime-sdk-ts';

// Create client from environment variables
const client = CoinbasePrimeClientWithServices.fromEnv();

// Access services directly - no manual instantiation needed!
const portfolios = await client.portfolios.listPortfolios();
const orders = await client.orders.listPortfolioOrders({ portfolioId: 'your-id' });
const wallets = await client.wallets.listWallets({ portfolioId: 'your-id' });

Environment Setup

Copy env.example to .env and populate with your values:

cp env.example .env

Then edit .env with your actual credentials:

# API Credentials (JSON format)
PRIME_CREDENTIALS={"AccessKey":"your-access-key","SecretKey":"your-secret-key","Passphrase":"your-passphrase"}

# Required IDs
ENTITY_ID=your-entity-id
PORTFOLIO_ID=your-portfolio-id
WALLET_ID=your-wallet-id

📚 Usage Examples

List Portfolios

const portfolios = await client.portfolios.listPortfolios();
console.log(portfolios.portfolios);

Get Assets

const assets = await client.assets.listAssets({ 
  entityId: portfolioId 
});
console.log(assets.assets);

Create Order

import { OrderSide, OrderType } from '@coinbase-sample/prime-sdk-ts';

const order = await client.orders.createOrder({
  portfolioId: 'your-portfolio-id',
  productId: 'BTC-USD',
  side: OrderSide.BUY,
  type: OrderType.MARKET,
  baseQuantity: '0.001'
});
console.log(order.orderId);

See the example folder for more robust examples for many of the available services and endpoints.

🔧 Configuration Options

Pagination Control

The SDK provides powerful pagination controls at both the client and request level:

const client = CoinbasePrimeClientWithServices.fromEnv(undefined, {
  maxPages: 5,        // Max pages to fetch automatically
  maxItems: 1000,     // Max total items across all pages
  defaultLimit: 100   // Items per page
});

// Or per-request
const response = await client.transactions.listPortfolioTransactions(
  { portfolioId, limit: 50 },
  { maxPages: 10, maxItems: 500 }
);

Advanced Pagination Methods

All paginated responses include powerful methods for manual pagination control:

// Get the first page
const firstPage = await client.transactions.listPortfolioTransactions({ portfolioId });

// Check if there are more pages
if (firstPage.hasNext()) {
  console.log('More data available');
}

// Get the next page manually
const secondPage = await firstPage.next();

// Fetch ALL remaining pages and combine the data
const allTransactions = await firstPage.fetchAll(
  undefined,  // options
  (page, totalItems) => console.log(`Fetched page ${page}, total items: ${totalItems}`)
);

// Example: Manual pagination loop
let currentPage = firstPage;
while (currentPage.hasNext()) {
  console.log(`Processing ${currentPage.transactions.length} transactions`);
  currentPage = await currentPage.next();
}

Pagination Methods

Method	Description	Returns
hasNext()	Check if more pages are available	boolean
next()	Fetch the next page	Promise<Response | null>
fetchAll()	Fetch all remaining pages and combine data	Promise<DataArray[]>
getNextCursor()	Get the next page cursor	string | undefined

📦 Alternative Import Patterns

While the modular client (CoinbasePrimeClientWithServices) is recommended for most use cases, the SDK provides additional import patterns optimized for specific scenarios:

🎯 For Bundle Size Optimization

Manual Client (@coinbase-sample/prime-sdk-ts/manual)

When you need full control over service instantiation:

import { CoinbasePrimeClient, OrdersService, WalletsService } from '@coinbase-sample/prime-sdk-ts/manual';

const client = CoinbasePrimeClient.fromEnv();
const orders = new OrdersService(client);
const wallets = new WalletsService(client);

// Only the services you import are included in your bundle

Ultra-Minimal Client (@coinbase-sample/prime-sdk-ts/client)

For services-only patterns (97% smaller bundles):

import { CoinbasePrimeClient } from '@coinbase-sample/prime-sdk-ts/client';
import { OrdersService } from '@coinbase-sample/prime-sdk-ts/services';

const client = CoinbasePrimeClient.fromEnv();
const orders = new OrdersService(client);
// Total bundle: ~3kb (perfect for microservices)

📊 Bundle Size Comparison

Import Pattern	Bundle Size	Use Case
Modular Client (recommended)	~30kb	Best developer experience
Manual Client	~90kb	Full control, all services available
Services + Client	~6kb	Custom implementations
Individual Service	~3kb	Microservices, Lambda functions

🎨 Type-Only Imports

For shared libraries or type definitions:

import type { CreateOrderRequest, OrderSide } from '@coinbase-sample/prime-sdk-ts/types';
// 0kb runtime - perfect for shared type libraries

🤔 When to Use Which?

• 🏆 Modular Client: Default choice - best DX, good performance
• ⚡ Manual Client: Need all services, want explicit control
• 🎯 Services-Only: Microservices, custom clients, minimal bundles
• 📦 Individual Services: Lambda functions, single-purpose apps
• 📝 Types-Only: Shared libraries, type definitions

🛠️ Development

Installation

git clone https://github.com/coinbase-samples/prime-sdk-ts.git
cd prime-sdk-ts
npm install

Build

npm run build

Run Examples

The SDK includes comprehensive examples in the example/ directory:

# Set up environment (copy env.example to .env first)
cp env.example .env
# Edit .env with your actual entityId, portfolioId, and walletId

# Run examples
node example/listPortfolios.js
node example/createOrder.js
node example/listWallets.js TRADING

🧪 TypeScript Support

The SDK is built with TypeScript and provides full type safety:

import { 
  CoinbasePrimeClientWithServices, 
  OrderSide, 
  OrderType,
  CreateOrderRequest 
} from '@coinbase-sample/prime-sdk-ts';

const client = CoinbasePrimeClientWithServices.fromEnv();

// Full IntelliSense and type checking
const request: CreateOrderRequest = {
  portfolioId: 'your-id',
  productId: 'BTC-USD',
  side: OrderSide.BUY,  // Enum with autocomplete
  type: OrderType.MARKET,
  baseQuantity: '0.001'
};

const order = await client.orders.createOrder(request);
// Response is fully typed - no manual type assertions needed

Changelog

[0.6.4] - 2025-SEP-03

Fixed

• Updated core-ts to improve query param array handling
• Fixed query param naming of symbol to symbols for ListPortfolioBalancesRequest
• Fixed GetPaymentMethodRequest type to include paymentMethodId

Added

📚 Comprehensive Service Examples

• Complete SDK Examples: Added 50+ working examples across all services
  • Full CRUD operations for portfolios, futures, orders, transactions, and more
  • Consistent error handling and multiline console output formatting
  • Flexible CLI arguments with sensible defaults and environment variable support