{"_id":"@aymantaybi/binance-connector-node","name":"@aymantaybi/binance-connector-node","dist-tags":{"latest":"2.0.0-rc.4"},"versions":{"2.0.0-rc.4":{"name":"@aymantaybi/binance-connector-node","version":"2.0.0-rc.4","description":"This is a lightweight library that works as a connector to the Binance public API.","main":"src/index.js","scripts":{"jsdoc":"jsdoc -c conf.json && ./docs_src/docs.sh","jsdoc:win":"jsdoc -c conf.json && npx jsdoc --readme ./docs_src/gettingStarted.md src/modules/blvt.js && node ./docs_src/generateDoc.js && RD /S /Q out","test":"jest --testPathIgnorePatterns=__tests__/websocket/subscription.test.js","test:watch":"jest --watchAll","standard":"standard","standard:fix":"standard --fix ","prepare":"husky install"},"repository":{"type":"git","url":"git+https://github.com/aymantaybi/binance-connector-node.git"},"engines":{"node":">=12.22.3","npm":">=6.14.13"},"keywords":["Binance","API"],"author":{"name":"aymantaybi"},"license":"MIT","bugs":{"url":"https://github.com/aymantaybi/binance-connector-node/issues"},"homepage":"https://github.com/aymantaybi/binance-connector-node#readme","devDependencies":{"clean-jsdoc-theme":"^3.2.7","husky":"^6.0.0","jest":"^28.1.2","jsdoc":"^3.6.7","marked":"^4.0.12","nock":"^13.0.2","standard":"^16.0.4"},"dependencies":{"axios":"^0.27.2","ws":"^8.8.1"},"jest":{"testMatch":["**/__tests__/**/*.test.js"]},"standard":{"ignore":["/docs/**/*.js"]},"gitHead":"88dc66e60abee65a3237c3b2160bf7f1c1242e98","_id":"@aymantaybi/binance-connector-node@2.0.0-rc.4","_nodeVersion":"16.17.0","_npmVersion":"8.19.2","dist":{"integrity":"sha512-5ZkmRsBRNFX3CplM8NQLFrK7AA2252/xk02KxCNtjqtgyGVkGKeTSn9c8At1hwP/prEIeui3V47AgpSbF+5w6g==","shasum":"5539698480eb0f98959eb3af2ec8d7ddb9c81ccf","tarball":"https://registry.npmjs.org/@aymantaybi/binance-connector-node/-/binance-connector-node-2.0.0-rc.4.tgz","fileCount":34,"unpackedSize":195442,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC4UOQDOdpZHJNMDYFB/WXJhMaXlqkMa1Om6eTejxecWwIhANWN+vF0lae4woWcvzTEmAYV+tIhAmglttIIOEoXZieG"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjyS+aACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmq13BAAhRCL9qRttX3h35RGvjro9rdR7BPpe9aXndAV4JkENyutX84f\r\n2900PGcvnLSzP2x17xQXaULPrecO80L08ChvHjQdvBzJSWJy14SMyDuYbFdg\r\nx37DtVMuQuIp1/E9wL5Wl2+KqdXtf7gBwJfpPvNYrR9W/uMIoohKgSIPdmpF\r\nLfU1g8yXG5W25Ps1UM5n5W28ca6HoY8v0wKxVbqyebZX0Oy0Eom1m5XeNLKh\r\n4FbWT26Vv7RQLSCwyu8JrlaS0UdL/bgDBKoMW1QcKkedPk/oJDqinJ7GWaDt\r\n6d00wzAkFqhGrvpvwLJdP3cLYxeI/0FeuY8ZcNJUq/LzIb0VL8XfmkYRLwst\r\ntMjsVRTvx9fV7mdoJWqHqGwiY/UwgNFpf2tIvAxYcyxuY2ogKdmpEP6SJrCa\r\nKV+AUOhHeCvRk+a1cTA58FaLxnydFp6amPZCBF+KdY+BXRMWohFSeQO8KzdR\r\nl6RqAenXN8WYU01Wwjy838nwFCTLG/FeW648Y0R/JYIoIM54IAsn9jm8OLVE\r\nqyIiv124Vg7O8MvnFrZBO33LOtUHcP6ET0Kq7okJsaRoRoVHD8O35ukQx9Pf\r\nJnF9kwYzwyAD/SoFKCGDaKtPtE/2L5RDiMwatDhOaIj96lp306WvE2gITaDh\r\nlHc5pVcZCSNFmLc2dqT9yFiJa9e6mVbZ/jA=\r\n=pnBJ\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"aymantaybi","email":"taybiayman0@gmail.com"},"directories":{},"maintainers":[{"name":"aymantaybi","email":"taybiayman0@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/binance-connector-node_2.0.0-rc.4_1674129306023_0.5115065352856014"},"_hasShrinkwrap":false}},"time":{"created":"2023-01-19T11:55:05.966Z","2.0.0-rc.4":"2023-01-19T11:55:06.243Z","modified":"2023-01-19T11:55:06.440Z"},"maintainers":[{"name":"aymantaybi","email":"taybiayman0@gmail.com"}],"description":"This is a lightweight library that works as a connector to the Binance public API.","homepage":"https://github.com/aymantaybi/binance-connector-node#readme","keywords":["Binance","API"],"repository":{"type":"git","url":"git+https://github.com/aymantaybi/binance-connector-node.git"},"author":{"name":"aymantaybi"},"bugs":{"url":"https://github.com/aymantaybi/binance-connector-node/issues"},"license":"MIT","readme":"# Binance connector in Nodejs\n\n[![npm version](https://badge.fury.io/js/%40binance%2Fconnector.svg)](https://badge.fury.io/js/%40binance%2Fconnector)\n[![Node version](https://img.shields.io/node/v/%40binance%2Fconnector.svg?style=flat)](http://nodejs.org/download/)\n[![Standard-Js](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\nThis is a lightweight library that works as a connector to [Binance public API](https://github.com/binance/binance-spot-api-docs). It’s designed to be simple, clean, and easy to use with minimal dependencies.\n\n- Supported APIs:\n    - `/api/*`\n    - `/sapi/*`\n    - Spot Websocket Market Stream\n    - Spot User Data Stream\n- Inclusion of test cases and examples\n- Customizable base URL\n- Support request timeout and HTTP proxy (since v2)\n- Response metadata can be displayed\n- Customizable Logger\n\n\n## Installation\n\n```bash\nnpm install @binance/connector\n```\n\n## Documentation\n\n[https://binance.github.io/binance-connector-node/](https://binance.github.io/binance-connector-node/)\n\n## RESTful APIs\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst apiKey = ''\nconst apiSecret = ''\nconst client = new Spot(apiKey, apiSecret)\n\n// Get account information\nclient.account().then(([error, data, response]) => console.log(error, data, response))\n\n// Place a new order\nclient.newOrder('BNBUSDT', 'BUY', 'LIMIT', {\n  price: '350',\n  quantity: 1,\n  timeInForce: 'GTC'\n}).then(([error, data, response]) => console.log(error, data, response))\n```\n\nPlease find `examples` folder to check for more endpoints.\n\n## RSA Key based Authentication\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst apiKey = ''\nconst apiSecret = '' // has no effect when RSA private key is provided\n\n// load private key\nconst privateKey = fs.readFileSync('/Users/john/ssl/private_key_encrypted.pem')\nconst privateKeyPassphrase = 'password'\n\nconst client = new Spot(apiKey, apiSecret, {\n  privateKey,\n  privateKeyPassphrase // only used for encrypted key\n})\n\n// Get account information\nclient.account().then(([error, data, response]) => console.log(error, data, response))\n```\n\n### Testnet\n\nWhile `/sapi/*` endpoints don't have testnet environment yet, `/api/*` endpoints can be tested in\n[Spot Testnet](https://testnet.binance.vision/). You can use it by changing the base URL:\n\n```javascript\n// provide the testnet base url\nconst client = new Spot(apiKey, apiSecret, { baseURL: 'https://testnet.binance.vision'})\n```\n\n### Base URL\n\nIf `base_url` is not provided, it defaults to `api.binance.com`.\n\nIt's recommended to pass in the `base_url` parameter, even in production as Binance provides alternative URLs in case of performance issues:\n\n- `https://api1.binance.com`\n- `https://api2.binance.com`\n- `https://api3.binance.com`\n\n### Optional Parameters\n\nOptional parameters are encapsulated to a single object as the last function parameter.\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst apiKey = ''\nconst apiSecret = ''\nconst client = new Spot(apiKey, apiSecret)\n\nclient.account({ recvWindow: 2000 }).then(([error, data, response]) => console.log(error, data, response))\n\n```\n\n### Timeout\n\nIt's easy to set timeout in milliseconds in request. If the request take longer than timeout, the request will be aborted. If it's not set, there will be no timeout.\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst apiKey = ''\nconst apiSecret = ''\nconst client = new Spot(apiKey, apiSecret, { timeout: 1000 })\n\nclient.account()\n  .then(([error, data, response]) => console.log(error, data, response))\n  .catch(error => client.logger.error(error.message))\n```\n\n### Proxy\n\nThe `axios` package is used as the http client in this library. A proxy settings is passed into `axios` directly, the details can be found at [here](https://github.com/axios/axios#request-config):\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst apiKey = ''\nconst apiSecret = ''\nconst client = new Spot(apiKey, apiSecret,\n  {\n    proxy: {\n      protocol: 'https',\n      host: '127.0.0.1',\n      port: 9000,\n      auth: {\n        username: 'proxy_user',\n        password: 'password'\n      }\n    }\n  }\n)\n```\n\nYou may have a HTTP proxy, that can bring the problem that you need to make a HTTPS connection through the HTTP proxy.  You can do that by build a HTTPS-over-HTTP tunnel by npm package [tunnel](https://www.npmjs.com/package/tunnel), and then pass the turnnel agent to `httpsAgent` in `axios`.\n\n```javascript\nconst tunnel = require('tunnel')\n\nconst agent = tunnel.httpsOverHttp({\n  proxy: {\n    host: \"127.0.0.1\",\n    port: 3128\n  }\n})\n\nconst client = new Spot(null, null,\n  {\n    baseURL: \"https://api.binance.com\",\n    httpsAgent: agent\n  }\n)\n\nclient.time()\n  .then(([error, data, response]) => console.log(error, data, response))\n\n```\n[This comment](https://github.com/axios/axios/issues/925#issuecomment-359982190) provides more details.\n\n### Response Metadata\n\nThe Binance API server provides weight usages in the headers of each response. This information can be fetched from `headers` property. `x-mbx-used-weight` and `x-mbx-used-weight-1m` show the total weight consumed within 1 minute.\n\n```\n// client initialization is skipped\n\nclient.exchangeInfo().then(response => client.logger.log(response.headers['x-mbx-used-weight-1m']))\n\n```\n\n### Custom Logger Integration\n\n```javascript\nconst Spot = require('@binance/connector')\nconst fs = require('fs')\nconst { Console } = require('console')\n\n// make sure the logs/ folder is created beforehand\nconst output = fs.createWriteStream('./logs/stdout.log')\nconst errorOutput = fs.createWriteStream('./logs/stderr.log')\n\nconst logger = new Console({ stdout: output, stderr: errorOutput })\nconst client = new Spot('', '', {logger: logger})\n\nclient.exchangeInfo().then(([error, data, response]) => console.log(error, data, response))\n// check the output file\n\n```\n\nThe default logger defined in the package is [Node.js Console class](https://nodejs.org/api/console.html). Its output is sent to `process.stdout` and `process.stderr`, same as the global console.\n\n### Error\n\nThere are 2 types of error that may be returned from the API server and the user has to handle it properly:\n\n- `Client error`\n  - This is thrown when server returns `4XX`, it's an issue from client side.\n  - The following properties may be helpful to resolve the issue:\n    - Response header - Please refer to `Response Metadata` section for more details.\n    - HTTP status code\n    - Error code - Server's error code, e.g. `-1102`\n    - Error message - Server's error message, e.g. `Unknown order sent.`\n    - Request config - Configuration send to the server, which can include URL, request method and headers.\n\n  ```\n  // client initialization is skipped\n  client.exchangeInfo({ symbol: 'invalidSymbol' })\n    .then(([error, data, response]) => console.log(error, data, response))\n    .catch(err => {\n      client.logger.error(err.response.headers) // full response header\n      client.logger.error(err.response.status) // HTTP status code 400\n      client.logger.error(err.response.data) // includes both error code and message\n      client.logger.error(err.response.config) // includes request's config\n    })\n\n  ```\n\n- `Server error`\n  - This is thrown when server returns `5XX`, it's an issue from server side.\n\n\n## Websocket\n\n```javascript\nconst { Spot } = require('@binance/connector')\n\nconst client = new Spot('', '', {\n  wsURL: 'wss://testnet.binance.vision' // If optional base URL is not provided, wsURL defaults to wss://stream.binance.com:9443\n})\n\nconst callbacks = {\n  open: () => client.logger.log('open'),\n  close: () => client.logger.log('closed'),\n  message: data => client.logger.log(data)\n}\nconst aggTrade = client.aggTradeWS('bnbusdt', callbacks)\n\n// unsubscribe the stream above\nsetTimeout(() => client.unsubscribe(aggTrade), 3000)\n\n// support combined stream\nconst combinedStreams = client.combinedStreams(['btcusdt@miniTicker', 'ethusdt@ticker'], callbacks)\n```\n\n\nMore websocket examples are available in the `examples` folder\n\n### Unsubscribe a Stream\n\nUnsubscription is achieved by closing the connection. If this method is called without any connection established, the console will output a message `No connection to close.`\n\n```javascript\n// client initialization is skipped\nconst wsRef = client.aggTradeWS('bnbusdt', callbacks)\n\n// The connection (bnbusdt@aggTrade) is closed after 3 secs.\nsetTimeout(() => client.unsubscribe(wsRef), 3000)\n\n```\n\n### Auto Reconnect\n\nIf there is a close event not initiated by the user, the reconnection mechanism will be triggered in 5 secs.\n\n### Ping Server\n\nIt is possible to ping server from client, and expect to receive a PONG message.\n\n```javascript\n\nconst { Console } = require('console')\nconst { Spot } = require('@binance/connector')\n\nconst logger = new Console({ stdout: process.stdout, stderr: process.stderr });\nconst client = new Spot('', '', { logger })\n\nconst callbacks = {\n  open: () => logger.info('open'),\n  close: () => logger.info('closed'),\n  message: data => logger.info(data)\n}\n\nconst wsRef = client.userData('the_listen_key', callbacks)\n\nsetInterval(() => {\n  client.pingServer(wsRef)\n}, 1000 * 10)\n\n```\n\n### Custom Logger Integration\n\n```javascript\nconst { Console } = require('console')\nconst fs = require('fs')\nconst Spot = require('@binance/connector')\n\nconst output = fs.createWriteStream('./logs/stdout.log')\nconst errorOutput = fs.createWriteStream('./logs/stderr.log')\n\n// make sure the logs/ folder is created beforehand\nconst logger = new Console({ stdout: output, stderr: errorOutput })\nconst client = new Spot('', '', {logger})\n\nconst callbacks = {\n  open: () => client.logger.log('open'),\n  close: () => client.logger.log('closed'),\n  message: data => client.logger.log(data)\n}\n\nconst wsRef = client.aggTradeWS('bnbusdt', callbacks)\nsetTimeout(() => client.unsubscribe(wsRef), 5000)\n// check the output file\n\n```\n\nThe default logger defined in the package is [Node.js Console class](https://nodejs.org/api/console.html). Its output is sent to `process.stdout` and `process.stderr`, same as the global console.\n\nNote that when the connection is initialized, the console outputs a list of callbacks in the form of `listen to event: <event_name>`.\n\n## Test\n\n```bash\nnpm install\n\nnpm run test\n\n```\n\n## Limitation\n\nFutures and Vanilla Options APIs are not supported:\n\n  - `/fapi/*`\n  - `/dapi/*`\n  - `/vapi/*`\n  -  Associated Websocket Market and User Data Streams\n\n## License\nMIT","readmeFilename":"README.md"}