{"id":13733989,"url":"https://github.com/scientistnik/btsdex","last_synced_at":"2025-05-08T10:30:50.259Z","repository":{"id":31507255,"uuid":"128110318","full_name":"scientistnik/btsdex","owner":"scientistnik","description":"Package for work with BitShares DEX","archived":false,"fork":false,"pushed_at":"2024-12-15T09:01:53.000Z","size":344,"stargazers_count":21,"open_issues_count":0,"forks_count":28,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-15T10:19:42.267Z","etag":null,"topics":["bitshares"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scientistnik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-04T19:21:45.000Z","updated_at":"2024-12-15T09:01:58.000Z","dependencies_parsed_at":"2024-11-15T02:32:24.335Z","dependency_job_id":"e6f606cc-b07e-4a75-9574-546a79534048","html_url":"https://github.com/scientistnik/btsdex","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scientistnik%2Fbtsdex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scientistnik%2Fbtsdex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scientistnik%2Fbtsdex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scientistnik%2Fbtsdex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scientistnik","download_url":"https://codeload.github.com/scientistnik/btsdex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253045577,"owners_count":21845728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitshares"],"created_at":"2024-08-03T03:00:51.556Z","updated_at":"2025-05-08T10:30:49.868Z","avatar_url":"https://github.com/scientistnik.png","language":"JavaScript","funding_links":[],"categories":["Libraries"],"sub_categories":["JavaScript Libraries"],"readme":"# btsdex\n\nPackage for work with BitShares DEX.\nThe main class in the package is `BitShares`. All you need is in it. There are a couple more helper classes, but they are not really designed for use outside of the `BitShares` class.\n\nThe `BitShares` class consists of static methods intended for working with the BitShares public blockchain API. Using the BitShares class, you can create an object whose methods provide access to the private part of the BitShares blockchain API.\n\n## Setup\n\n### If you use `npm`\nThis library can be obtained through npm:\n```\n$ npm install btsdex\n```\nIf you want use [REPL-mode](#repl-mode):\n```\n$ npm install -g btsdex\n```\n\n### If you use `browser`\nInclude [this](https://github.com/scientistnik/btsdex/releases) in html-file:\n```\n\u003cscript src=\"btsdex.min.js\"\u003e\u003c/script\u003e\n```\nAfter that in console available `BitShares` class.\n\n## Usage\n\n__btsdex__ package contain class `BitShares`: \n```js\nconst BitShares = require('btsdex')\n```\nTo connect to the BitShares network, you must call `connect` method:\n```js\nawait BitShares.connect();\n```\nBy default, `BitShares` connected to `wss://dex.iobanker.com/ws`. If you want set another node to connect:\n```js\nawait BitShares.connect(\"wss://dex.iobanker.com/ws\")\n```\n\nYou can also connect to the network using the [event system](#event-system).\n\n### Public API\n\nAfter the connection, you can use any public method from [official documentation](http://dev.bitshares.works/en/master/api/blockchain_api.html) (if the method is still relevant!).\n\n#### Database API\n\nTo access the [Database API](http://dev.bitshares.works/en/master/api/blockchain_api/database.html), you can use the __BitShares.db__ object.\n\nAn example of methods from the Database API:\n\n[__get_objects(const vector \u003cobject_id_type\u003e \u0026 ids) const__](http://dev.bitshares.works/en/master/api/blockchain_api/database.html#_CPPv3NK8graphene3app12database_api11get_objectsERK6vectorI14object_id_typeE)\n\n[__list_assets(const string \u0026 lower_bound_symbol, uint32_t limit) const__](http://dev.bitshares.works/en/master/api/blockchain_api/database.html#_CPPv3NK8graphene3app12database_api11list_assetsERK6string8uint32_t)\n\n\nTo use them:\n```js\nlet obj = await BitShares.db.get_objects([\"1.3.0\"])\nlet bts = await BitShares.db.list_assets(\"BTS\", 100)\n```\n\n#### History API\n\nTo access the [Account History API](http://dev.bitshares.works/en/master/api/blockchain_api/history.html), you can use the __BitShares.history__ object.\n\nExample of a method from the Account History API:\n\n[__get_account_history (account_id_type account, operation_history_id_type stop = operation_history_id_type (), unsigned limit = 100, operation_history_id_type start = operation_history_id_type ()) const__](http://dev.bitshares.works/en/master/api/blockchain_api/history.html#_CPPv3NK8graphene3app11history_api19get_account_historyEKNSt6stringE25operation_history_id_typej25operation_history_id_type)\n\nTo use it:\n```js\nlet ops = await BitShares.history.get_account_history(\"1.2.849826\", \"1.11.0\", 10, \"1.11.0\")\n```\n\n### Private API\n\nIf you want to have access to account operations, you need to create a BitShares object. \n\nIf you know `privateActiveKey`:\n```js\nlet acc = new BitShares(\u003caccountName\u003e, \u003cprivateActiveKey\u003e)\n```\nor if you know `password`:\n```js\nlet acc = BitShares.login(\u003caccountName\u003e, \u003cpassword\u003e)\n```\nor if you have `bin`-file:\n```js\nlet buffer = fs.readFileSync(\u003cbin-file path\u003e);\nlet acc = BitShares.loginFromFile(buffer, \u003cwallet-password\u003e, \u003caccountName\u003e)\n```\n\nWhile this object can not much: buy, sell, transfer, cancel order, asset reserve, asset issue and more.\n\nSignatures of methods:\n```js\nacc.buy(buySymbol, baseSymbol, amount, price, fill_or_kill = false, expire = \"2020-02-02T02: 02: 02\")\nacc.sell(sellSymbol, baseSymbol, amount, price, fill_or_kill = false, expire = \"2020-02-02T02: 02: 02\")\nacc.cancelOrder(id)\nacc.transfer(toName, assetSymbol, amount, memo)\nacc.assetIssue(toName, assetSymbol, amount, memo)\nacc.assetReserve(assetSymbol, amount)\n```\n\nExamples of using:\n```js\nawait acc.buy(\"HONEST.BTC\", \"BTS\", 0.002, 140000)\nawait acc.sell(\"BTS\", \"HONEST.USD\", 187, 0.24)\nawait acc.transfer(\"scientistnik\", \"BTS\", 10)\nawait acc.assetIssue(\"scientistnik\", \"ABC\", 10)\nawait acc.assetReserve(\"ABC\", 12)\n```\n\nIf you want to send tokens with memo and get `acc` from `constructor` (use `new BitShares()`), then before that you need to set a private memo-key:\n```js\nbot.setMemoKey(\u003cprivateMemoKey\u003e)\nawait bot.transfer(\"scientistnik\", \"HONEST.USD\", 10, \"Thank you for BTSDEX!\")\n```\n### Transaction Builder\n\nEach private transaction is considered accepted after being included in the block. Blocks are created every 3 seconds. If we need to perform several operations, their sequential execution can take considerable time. Fortunately, several operations can be included in a single transaction. For this you need to use transaction builder.\n\nFor create new transaction:\n```js\nlet tx = BitShares.newTx([\u003cactivePrivateKey\u003e,...])\n```\nor if you have account object `acc`:\n```js\nlet tx = acc.newTx()\n```\n\nFor get operation objects:\n```js\nlet operation1 = await acc.transferOperation(\"scientistnik\", \"BTS\", 10)\nlet operation2 = await acc.assetIssueOperation(\"scientistnik\", \"ABC\", 10)\n...\n```\nAdded operation to transaction:\n```js\ntx.add(operation1)\ntx.add(operation2)\n...\n```\nIf you want to know the cost of the transaction:\n```js\nlet cost = await tx.cost()\nconsole.log(cost) // { BTS: 1.234 }\n```\n\nAfter broadcast transaction:\n```js\nawait tx.broadcast()\n```\nor\n```js\nawait acc.broadcast(tx)\n```\n\nIf you know what fields the transaction you need consists of and the operation name, you can use the transaction builder for executing the transaction.\n\nThe account property has a lot more operations available than an instance of the bitshares class.\n\nAn example of using transaction builder for executing 'account_create' operation:\n```js\nlet BitShares = require(\"btsdex\")\n\nBitShares.subscribe(\"connected\", start)\n\nasync function start() {\n  let acc = await BitShares.login(\u003caccountName\u003e, \u003cpassword\u003e)\n\n  let params = {\n    fee: {amount: 0, asset_id: \"1.3.0\"},\n    name: \"trade-bot3\",\n    registrar: \"1.2.21058\",\n    referrer: \"1.2.21058\",\n    referrer_percent: 5000,\n    owner: {\n      weight_threshold: 1,\n      account_auths: [],\n      key_auths: [[\u003cownerPublicKey\u003e, 1]],\n      address_auths: []\n    },\n    active: {\n      weight_threshold: 1,\n      account_auths: [],\n      key_auths: [[\u003cactivePublicKey\u003e, 1]],\n      address_auths: []\n    },\n    options: {\n      memo_key: \u003cmemoPublicKey\u003e,\n      voting_account: \"1.2.5\",\n      num_witness: 0,\n      num_committee: 0,\n      votes: []\n    },\n    extensions: []\n  };\n\n  let tx = acc.newTx()\n  tx.account_create(params) // 'account_create' is the operation name\n  await tx.broadcast()\n}\n```\n\n\n### Event system\nVery often we have to expect, when there will be some action in the blockchain, to which our software should respond. The idea of ​​reading each block and viewing all the operations in it, seemed to me ineffective. Therefore, this update adds an event system.\n\n#### Event types\n\nAt the moment, __BTSDEX__ has three types of events:\n* `connected` - works once after connecting to the blockchain;\n* `block` - it works when a new block is created in the blockchain;\n* `account` - occurs when the specified account is changed (balance change).\n\nFor example:\n```js\nconst BitShares = require(\"btsdex\");\n\nBitShares.subscribe('connected', startAfterConnected);\nBitShares.subscribe('block', callEachBlock);\nBitShares.subscribe('account', changeAccount, 'trade-bot');\n\nasync function startAfterConnected() {/* is called once after connecting to the blockchain */}\nasync function callEachBlock(obj) {/* is called with each block created */}\nasync function changeAccount(array) {/* is called when you change the 'trade-bot' account */}\n```\n\n##### The `connected` event\n\nThis event is triggered once, after connecting to the blockchain. Any number of functions can be subscribed to this event and all of them will be called after connection.\n\n```js\nBitShares.subscribe('connected', firstFunction);\nBitShares.subscribe('connected', secondFunction);\n```\n\nAnother feature of the event is that when you first subscription call the method `BitShares.connect()`, i.e. will be an automatic connection. If by this time the connection to the blockchain has already been connected, then it will simply call the function.\n\nNow it's not necessary to explicitly call `BitShares.connect()`, it's enough to subscribe to the `connected` event.\n\n```js\nconst BitShares = require(\"btsdex\");\n\nBitShares.subscribe('connected', start);\n\nasync function start() {\n  // something is happening here\n}\n```\n\n##### The `block` event\n\nThe `block` event is triggered when a new block is created in the blockchain. The first event subscription automatically creates a subscription to the `connected` event, and if this is the first subscription, it will cause a connection to the blockchain.\n\n```js\nconst BitShares = require(\"btsdex\");\n\nBitShares.subscribe('block', newBlock);\n\n// need to wait ~ 10-15 seconds\nasync function newBlock(obj) {\n  console.log(obj); // [{id: '2.1.0', head_block_number: 17171083, time: ...}]\n}\n```\n\nAs you can see from the example, an object with block fields is passed to all the signed functions.\n\n##### The `account` event\n\nThe `account` event is triggered when certain changes occur (balance changes). These include:\n* If the account sent someone one of their assets\n* If an asset has been sent to an account\n* If the account has created an order\n* If the account order was executed (partially or completely), or was canceled.\n\nThe first subscriber to `account` will call a `block` subscription, which in the end will cause a connection to the blockchain.\n\nExample code:\n```js\nconst BitShares = require(\"btsdex\");\n\nBitShares.subscribe('account', changeAccount, 'scientistnik');\n\nasync function changeAccount (array) {\n  console.log(array); // [{id: '1.11.37843675', block_num: 17171423, op: ...}, {...}]\n}\n```\nIn all the signed functions, an array of account history objects is transferred, which occurred since the last event.\n\n### REPL-mode\n\nIf you install `btsdex`-package in global storage, you may start `btsdex` exec script:\n```js\n$ btsdex\n\u003e|\n```\nThis command try autoconnect to mainnet BitShares. If you want to connect on testnet, try this:\n```js\n$ btsdex --testnet\n\u003e|\n```\nor use `--node` key:\n```js\n$ btsdex --node wss://dex.iobanker.com/ws\n\u003e|\n```\n\nIt is nodejs REPL with several variables:\n- `BitShares`, main class `BitShares` package\n- `login`, function to create object of class `BitShares`\n- `generateKeys`, to generateKeys from login and password\n- `accounts`, is analog `BitShares.accounts`\n- `assets`, is analog `BitShares.assets`\n- `db`, is analog `BitShares.db`\n- `history`, is analog `BitShares.hostory`\n- `network`, is analog `BitShares.network`\n- `fees`, is analog `BitShares.fees`\n\n#### For example\n\n```js\n$ btsdex\n\u003e assets[\"bts\"].then(console.log)\n```\n\n#### Shot request\n\nIf need call only one request, you may use `--account`, `--asset`, `--block`, `--object`, `--history` or `--transfer` keys in command-line:\n```js\n$ btsdex --account \u003c'name' or 'id' or 'last number in id'\u003e\n{\n  \"id\": \"1.2.5992\",\n  \"membership_expiration_date\": \"1970-01-01T00:00:00\",\n  \"registrar\": \"1.2.37\",\n  \"referrer\": \"1.2.21\",\n  ...\n}\n$ btsdex --asset \u003c'symbol' or 'id' or 'last number in id'\u003e\n{\n  \"id\": \"1.3.0\",\n  \"symbol\": \"BTS\",\n  \"precision\": 5,\n  ...\n}\n$ btsdex --block [\u003cnumber\u003e]\nblock_num: 4636380\n{\n  \"previous\": \"0046bedba1317d146dd6afbccff94412d76bf094\",\n  \"timestamp\": \"2018-10-01T13:09:40\",\n  \"witness\": \"1.6.41\",\n  ...\n}\n$ btsdex --object 1.2.3\n{\n  \"id\": \"1.2.3\",\n  \"membership_expiration_date\": \"1969-12-31T23:59:59\",\n  \"registrar\": \"1.2.3\",\n  \"referrer\": \"1.2.3\",\n  ...\n}\n$ btsdex --history \u003caccount\u003e [\u003climit\u003e] [\u003cstart\u003e] [\u003cstop\u003e]\n[\n  {\n    \"id\": \"1.11.98179\",\n    \"op\": [\n      0,\n  ...\n}]\n$ btsdex --transfer \u003cfrom\u003e \u003cto\u003e \u003camount\u003e \u003casset\u003e [--key]\nTransfered \u003camount\u003e \u003casset\u003e from '\u003cfrom\u003e' to '\u003cto\u003e' with memo '\u003cmemo\u003e'\n```\n\n### Helper classes\nThere are a couple more helper classes, such as __BitShares.assets__ and __BitShares.accounts__:\n```js\nlet usd = await BitShares.assets.usd;\nlet btc = await BitShares.assets[\"HONEST.BTC\"];\nlet bts = await BitShares.assets[\"bts\"];\n\nlet iam = await BitShares.accounts.scientistnik;\nlet tradebot = await BitShares.accounts[\"trade-bot\"];\n```\nThe returned objects contain all the fields that blockchain returns when the given asset or account name is requested.\n\n### Some examples\nThe below example can be used to broadcast any transaction to the BitShares Blockchain using API node hence you can use any BitShares Public API node, you will just need to replace parameters under **params** and the operation name **asset_update** in below example with your desired transaction parameters and its operation name. Use the below links to determine your desired operation name and needed parameters along with their required order. Below transaction example serialization can be found here [Serialization](https://github.com/bitshares/btsdex/blob/master/packages/serializer/src/operations.js) as you will need to honor the order of [Operation](https://github.com/bitshares/bitshares-core/blob/master/libraries/protocol/include/graphene/protocol/operations.hpp) parameters along with their sub parameters which are present in below example **new_options** note that some of parameters or sub parameters are optional:\n\n```js\nconst BitShares = require(\"btsdex\");\nBitShares.connect(\"wss://dex.iobanker.com/ws\"); # replace wss://dex.iobanker.com/ws with API node if you want to use another BitShares API node\nBitShares.subscribe('connected', startAfterConnected);\n\nasync function startAfterConnected() {\nlet acc = await new BitShares(\"username\", \"password\"); # replace with your username and password\n\n# Below are required parameters and structure for the example of operation *asset_update*; every different operation would required different parameters and structure\n\n# Finding what data to use in these parameters would require understanding of how BitShares Blockchain works, for example *issuer* is referred to the ID *1.2.1787259* of owner account of an Asset, use telegram [BitShares Development](https://t.me/BitSharesDEV) group to ask about required parameters.\n\nlet params = {\n    fee: {amount: 0, asset_id: \"1.3.0\"},\n    \"issuer\":\"1.2.1787259\",\n    \"asset_to_update\":\"1.3.5537\", \n    \"new_options\": {\n     \"max_supply\": \"1000000000000000\", \n     \"market_fee_percent\": 0, \n     \"max_market_fee\": \"0\", \n     \"min_market_fee\": 0, \n     \"issuer_permissions\": 79, \n     \"flags\": 6, \n     \"core_exchange_rate\": {\n      \"base\": {\"amount\": 500000, \"asset_id\": \"1.3.0\"}, \n      \"quote\": {\"amount\": 10000, \"asset_id\": \"1.3.5537\"}\n      }, \n    \"whitelist_authorities\": [], \n    \"blacklist_authorities\": [], \n    \"whitelist_markets\": [], \n    \"blacklist_markets\": [],\n    \"description\": \"{\\\"main\\\":\\\"Your Asset Info\\\",\\\"market\\\":\\\"Your Market info\\\"}\", \n    \"extensions\": {\"taker_fee_percent\": 10}\n    }\n}\n\nlet tx = acc.newTx();\ntx.asset_update(params); # Replace asset_update with your desired operation name\nawait tx.broadcast();\nconsole.log(tx);\n}\n```\n\nAnother example for getting account orders information: \n\n```js\nconst BitShares = require('btsdex')\nKEY = 'privateActiveKey'\n\nBitShares.subscribe('connected', startAfterConnected)\n\nasync function startAfterConnected() {\n  let bot = new BitShares('trade-bot', KEY)\n\n  let iam = await BitShares.accounts['trade-bot'];\n  let orders = await BitShares.db.get_full_accounts([iam.id], false);\n  \n  orders = orders[0][1].limit_orders;\n  let order = orders[0].sell_price;\n  console.log(order)\n}\n```\n\n## Documentation\nFor more information, look [wiki](https://scientistnik.github.io/btsdex) or in `docs`-folder.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub. For communication, you can use the Telegram-channel [btdex](https://t.me/btsdex).\n\n`master`-branch use for new release. For new feature use `dev` branch. All pull requests are accepted in `dev` branch.\n\n## License\n\nThe package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscientistnik%2Fbtsdex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscientistnik%2Fbtsdex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscientistnik%2Fbtsdex/lists"}