@zufans/coinbase-advanced-trade/README.md

A comprehensive Node.js SDK for Coinbase Advanced Trade API

# Coinbase Advanced Trade SDK

A comprehensive Node.js SDK for the Coinbase Advanced Trade API, providing easy-to-use methods for trading, account management, and market data retrieval.

## Installation

```bash
npm install @zufans/coinbase-advanced-trade
```

## Quick Start

```javascript
import CoinbaseAdvancedTrade from '@zufans/coinbase-advanced-trade';

// Initialize the client
const client = new CoinbaseAdvancedTrade(
  'your-api-key-name',
  'your-api-secret'
);

// List accounts
const accounts = await client.listAccounts();
console.log(accounts);

// Get product information
const product = await client.getProduct('BTC-USD');
console.log(product);

// Create a market order
const order = await client.createOrder(
  'unique-client-order-id',
  'BTC-USD',
  'BUY',
  {
    market_market_ioc: {
      quote_size: '100.00'
    }
  }
);
console.log(order);
```

## Authentication

You'll need to obtain API credentials from Coinbase:

1. Go to [Coinbase Advanced Trade](https://www.coinbase.com/advanced-trade/keys)
2. Create a new API key
3. Save your API Key Name and Private Key securely

## API Reference

### Initialization

```javascript
const client = new CoinbaseAdvancedTrade(apiKeyName, apiSecret);
```

### Account Methods

#### `listAccounts(params?)`
List trading accounts.

```javascript
const accounts = await client.listAccounts({
  limit: 250,
  cursor: 'optional-cursor'
});
```

#### `getAccount(accountUUID)`
Get details of a specific account.

```javascript
const account = await client.getAccount('account-uuid-here');
```

### Order Methods

#### `createOrder(clientOrderId, productId, side, orderConfiguration, options?)`
Create a new order.

```javascript
// Market order
const marketOrder = await client.createOrder(
  'client-order-id',
  'BTC-USD',
  'BUY',
  {
    market_market_ioc: {
      quote_size: '100.00'
    }
  }
);

// Limit order
const limitOrder = await client.createOrder(
  'client-order-id',
  'BTC-USD',
  'BUY',
  {
    limit_limit_gtc: {
      base_size: '0.001',
      limit_price: '50000.00',
      post_only: false
    }
  }
);
```

#### `cancelOrders(orderIds)`
Cancel one or more orders.

```javascript
const result = await client.cancelOrders(['order-id-1', 'order-id-2']);
```

#### `listOrders(filters?)`
List historical orders with optional filters.

```javascript
const orders = await client.listOrders({
  product_ids: ['BTC-USD'],
  order_status: ['FILLED'],
  limit: 100
});
```

#### `getOrder(orderId, clientOrderId?)`
Get details of a specific order.

```javascript
const order = await client.getOrder('order-id');
```

#### `editOrder(orderId, price, size, clientOrderId?)`
Edit an existing order.

```javascript
const result = await client.editOrder('order-id', '51000.00', '0.002');
```

### Product Methods

#### `listProducts(queryParams?)`
List available trading products.

```javascript
const products = await client.listProducts({
  limit: 100,
  offset: 0
});
```

#### `getProduct(productId)`
Get details of a specific product.

```javascript
const product = await client.getProduct('BTC-USD');
```

#### `getBestBidAsk(productId?, params?)`
Get best bid/ask for products.

```javascript
const bidAsk = await client.getBestBidAsk('BTC-USD');
```

#### `getCandles(productId, queryParams)`
Get historical candle data.

```javascript
const candles = await client.getCandles('BTC-USD', {
  start: Math.floor(Date.now() / 1000) - 86400, // 24 hours ago
  end: Math.floor(Date.now() / 1000),
  granularity: 'ONE_HOUR',
  limit: 24
});
```

Available granularities: `ONE_MINUTE`, `FIVE_MINUTE`, `FIFTEEN_MINUTE`, `THIRTY_MINUTE`, `ONE_HOUR`, `TWO_HOUR`, `SIX_HOUR`, `ONE_DAY`

#### `getMarketTrades(productId, queryParams)`
Get recent market trades.

```javascript
const trades = await client.getMarketTrades('BTC-USD', {
  limit: 100
});
```

### Utility Methods

#### `getKeyPermissions()`
Check API key permissions.

```javascript
const permissions = await client.getKeyPermissions();
```

#### `getCurrency(base)`
Get currency information.

```javascript
const currency = await client.getCurrency('BTC');
```

## Order Configuration Types

The SDK supports all Coinbase Advanced Trade order types:

- **Market Orders**: `market_market_ioc`
- **Limit Orders**: `limit_limit_gtc`, `limit_limit_gtd`, `limit_limit_fok`
- **Stop Limit Orders**: `stop_limit_stop_limit_gtc`, `stop_limit_stop_limit_gtd`
- **Bracket Orders**: `trigger_bracket_gtc`, `trigger_bracket_gtd`

## Error Handling

```javascript
try {
  const order = await client.createOrder(/* ... */);
} catch (error) {
  console.error('Order creation failed:', error.message);
  // Handle error appropriately
}
```

## Individual Function Imports

You can also import individual functions:

```javascript
import { 
  listAccounts, 
  createOrder, 
  getProduct,
  cbToken 
} from '@zufans/coinbase-advanced-trade';

// Use with your own credentials
const accounts = await listAccounts('api-key', 'api-secret');
```

## Requirements

- Node.js 16+
- Valid Coinbase Advanced Trade API credentials

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For API-related questions, refer to the [Coinbase Advanced Trade API Documentation](https://docs.cdp.coinbase.com/advanced-trade/docs/welcome).

For SDK issues, please open an issue on GitHub.