diff --git a/README.md b/README.md index 290d664..80c7e29 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,283 @@ -# coinbase-api +# Node.js & JavaScript SDK for Coinbase REST APIs & WebSockets -TODO +

+ + + + SDK Logo + + +

+ +[![npm version](https://img.shields.io/npm/v/coinbase-api)][1] +[![npm size](https://img.shields.io/bundlephobia/min/coinbase-api/latest)][1] +[![npm downloads](https://img.shields.io/npm/dt/coinbase-api)][1] +[![Build & Test](https://github.com/tiagosiebler/coinbase-api/actions/workflows/e2etest.yml/badge.svg?branch=master)](https://github.com/tiagosiebler/coinbase-api/actions/workflows/e2etest.yml) +[![last commit](https://img.shields.io/github/last-commit/tiagosiebler/coinbase-api)][1] +[![Telegram](https://img.shields.io/badge/chat-on%20telegram-blue.svg)](https://t.me/nodetraders) + +[1]: https://www.npmjs.com/package/coinbase-api + +Updated & performant JavaScript & Node.js SDK for the Coinbase REST APIs and WebSockets: + +- Supports both retail and institutional REST clients and Websockets: + + - [Advanced Trade](https://docs.cdp.coinbase.com/advanced-trade/docs/welcome) + - [Coinbase App](https://docs.cdp.coinbase.com/coinbase-app/docs/welcome) + - [Coinbase Exchange](https://docs.cdp.coinbase.com/exchange/docs/welcome) + - [Coinbase International Exchange](https://docs.cdp.coinbase.com/intx/docs/welcome) + - [Coinbase Prime](https://docs.cdp.coinbase.com/prime/docs/welcome) + - [Coinbase Commerce](https://docs.cdp.coinbase.com/commerce-onchain/docs/welcome) + +- Complete integration with all REST APIs and WebSockets. +- TypeScript support (with type declarations for most API requests & responses) +- Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows. +- Browser-friendly HMAC signature mechanism. +- Automatically supports both ESM and CJS projects. +- Proxy support via axios integration. +- Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders). + +## Installation + +`npm install --save coinbase-api` + +## Issues & Discussion + +- Issues? Check the [issues tab](https://github.com/tiagosiebler/coinbase-api/issues). +- Discuss & collaborate with other node devs? Join our [Node.js Algo Traders](https://t.me/nodetraders) engineering community on telegram. + + + +## Related projects + +Check out my related JavaScript/TypeScript/Node.js projects: + +- Try my REST API & WebSocket SDKs: + - [Bybit-api Node.js SDK](https://www.npmjs.com/package/bybit-api) + - [Okx-api Node.js SDK](https://www.npmjs.com/package/okx-api) + - [Binance Node.js SDK](https://www.npmjs.com/package/binance) + - [Gateio-api Node.js SDK](https://www.npmjs.com/package/gateio-api) + - [Bitget-api Node.js SDK](https://www.npmjs.com/package/bitget-api) + - [Bitmart-api Node.js SDK](https://www.npmjs.com/package/bitmart-api) +- Try my misc utilities: + - [OrderBooks Node.js](https://www.npmjs.com/package/orderbooks) + - [Crypto Exchange Account State Cache](https://www.npmjs.com/package/accountstate) +- Check out my examples: + - [awesome-crypto-examples Node.js](https://github.com/tiagosiebler/awesome-crypto-examples) + + +## Documentation + +Most methods accept JS objects. These can be populated using parameters specified by Coinbase's API documentation. + +- [Coinbase API Documentation](https://docs.cdp.coinbase.com/product-apis/docs/welcome) +- [REST Endpoint Function List](./docs/endpointFunctionList.md) + + +## Structure + +This project uses typescript. Resources are stored in 2 key structures: + +- [src](./src) - the whole connector written in typescript +- [examples](./examples) - some implementation examples & demonstrations. Contributions are welcome! + +--- + +# Usage + +Create API credentials + +- [Kucoin API Key Management](https://www.kucoin.com/account/api) + +### REST API + +To use any of Kucoin's REST APIs in JavaScript/TypeScript/Node.js, import (or require) the `SpotClient` (for spot and margin APIs) or `FuturesClient` (for futures APIs): + +```javascript +const { SpotClient, FuturesClient } = require('kucoin-api'); + +const client = new SpotClient({ + apiKey: 'apiKeyHere', + apiSecret: 'apiSecretHere', + apiPassphrase: 'apiPassPhraseHere', +}); + +try { + const spotBuyResult = await client.submitOrder({ + clientOid: client.generateNewOrderID(), + side: 'buy', + type: 'market', + symbol: 'BTC-USDT', + size: '0.00001', + }); + console.log('spotBuy ', JSON.stringify(spotBuyResult, null, 2)); + + const spotSellResult = await client.submitOrder({ + clientOid: client.generateNewOrderID(), + side: 'sell', + type: 'market', + symbol: 'BTC-USDT', + size: '0.00001', + }); + console.log('spotSellResult ', JSON.stringify(spotSellResult, null, 2)); +} catch (e) { + console.error(`Req error: `, e); +} +``` + +See [SpotClient](./src/SpotClient.ts) and [FuturesClient](./src/FuturesClient.ts) for further information, or the [examples](./examples/) for lots of usage examples. + +## WebSockets + +All available WebSockets can be used via a shared `WebsocketClient`. The WebSocket client will automatically open/track/manage connections as needed. Each unique connection (one per server URL) is tracked using a WsKey (each WsKey is a string - see [WS_KEY_MAP](src/lib/websocket/websocket-util.ts) for a list of supported values). + +Any subscribe/unsubscribe events will need to include a WsKey, so the WebSocket client understands which connection the event should be routed to. See examples below or in the [examples](./examples/) folder on GitHub. + +Data events are emitted from the WebsocketClient via the `update` event, see example below: + +```javascript +const { WebsocketClient } = require('kucoin-api'); + +const client = new WebsocketClient(); + +client.on('open', (data) => { + console.log('open: ', data?.wsKey); +}); + +// Data received +client.on('update', (data) => { + console.info('data received: ', JSON.stringify(data)); +}); + +// Something happened, attempting to reconenct +client.on('reconnect', (data) => { + console.log('reconnect: ', data); +}); + +// Reconnect successful +client.on('reconnected', (data) => { + console.log('reconnected: ', data); +}); + +// Connection closed. If unexpected, expect reconnect -> reconnected. +client.on('close', (data) => { + console.error('close: ', data); +}); + +// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate" +client.on('response', (data) => { + console.info('response: ', data); + // throw new Error('res?'); +}); + +client.on('exception', (data) => { + console.error('exception: ', { + msg: data.msg, + errno: data.errno, + code: data.code, + syscall: data.syscall, + hostname: data.hostname, + }); +}); + +try { + // Optional: await a connection to be ready before subscribing (this is not necessary) + // await client.connect('futuresPublicV1'); + + /** + * Examples for public futures websocket topics (that don't require authentication). + * + * These should all subscribe via the "futuresPublicV1" wsKey. For detailed usage, refer to the ws-spot-public.ts example. + */ + client.subscribe( + [ + '/contractMarket/tickerV2:XBTUSDM', + '/contractMarket/ticker:XBTUSDM', + '/contractMarket/level2:XBTUSDM', + '/contractMarket/execution:XBTUSDM', + '/contractMarket/level2Depth5:XBTUSDM', + '/contractMarket/level2Depth50:XBTUSDM', + '/contractMarket/limitCandle:XBTUSDTM_1hour', + '/contract/instrument:XBTUSDM', + '/contract/announcement', + '/contractMarket/snapshot:XBTUSDM', + ], + 'futuresPublicV1', + ); +} catch (e) { + console.error(`Subscribe exception: `, e); +} +``` + +See [WebsocketClient](./src/WebsocketClient.ts) for further information and make sure to check the [examples](./examples/) folder for much more detail, especially [ws-spot-public.ts](./examples/ws-spot-public.ts), which explains a lot of detail. + +--- + +## Customise Logging + +Pass a custom logger which supports the log methods `trace`, `info` and `error`, or override methods from the default logger as desired. + +```javascript +const { WebsocketClient, DefaultLogger } = require('kucoin-api'); + +// E.g. customise logging for only the trace level: +const logger = { + // Inherit existing logger methods, using an object spread + ...DefaultLogger, + // Define a custom trace function to override only that function + trace: (...params) => { + if ( + [ + 'Sending ping', + // 'Sending upstream ws message: ', + 'Received pong', + ].includes(params[0]) + ) { + return; + } + console.log('trace', JSON.stringify(params, null, 2)); + }, +}; + +const ws = new WebsocketClient( + { + apiKey: 'apiKeyHere', + apiSecret: 'apiSecretHere', + apiPassphrase: 'apiPassPhraseHere', + }, + logger, +); +``` + +--- + + + +Have my projects helped you? Share the love, there are many ways you can show your thanks: + +- Star & share my projects. +- Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler +- Have an interesting project? Get in touch & invite me to it. +- Or buy me all the coffee: + - ETH(ERC20): `0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C` + + + + +### Contributions & Pull Requests + +Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items. + + + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=tiagosiebler/bybit-api,tiagosiebler/okx-api,tiagosiebler/binance,tiagosiebler/bitget-api,tiagosiebler/bitmart-api,tiagosiebler/gateio-api,tiagosiebler/kucoin-api,tiagosiebler/orderbooks,tiagosiebler/accountstate,tiagosiebler/awesome-crypto-examples&type=Date)](https://star-history.com/#tiagosiebler/bybit-api&tiagosiebler/okx-api&tiagosiebler/binance&tiagosiebler/bitget-api&tiagosiebler/bitmart-api&tiagosiebler/gateio-api&tiagosiebler/kucoin-api&tiagosiebler/orderbooks&tiagosiebler/accountstate&tiagosiebler/awesome-crypto-examples&Date) + +