# @orionprotocol/orion-trading-sdk

> 🛠 An SDK for trading with Orion.

Latest version **1.5.4** (published 2022-03-18) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @orionprotocol/orion-trading-sdk
pnpm add @orionprotocol/orion-trading-sdk
yarn add @orionprotocol/orion-trading-sdk
bun add @orionprotocol/orion-trading-sdk
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.5.4 |
| Published | 2022-03-18 |
| First published | 2021-09-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 7 |
| Unpacked size | 828 KB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 6 |
| Maintainers | orion-protocol, tolyayanot, lambdafxf |
| Keywords | orionprotocol, ethereum, bsc, crypto |

## Links

- npm: https://www.npmjs.com/package/@orionprotocol/orion-trading-sdk
- Repository: https://github.com/orionprotocol/trading-sdk
- Homepage: https://github.com/orionprotocol/trading-sdk#readme
- Issues: https://github.com/orionprotocol/trading-sdk/issues
- npm.io page: https://npm.io/package/@orionprotocol/orion-trading-sdk

## Dependencies (7)

- [ws](https://npm.io/package/ws.md) ^8.2.0
- [axios](https://npm.io/package/axios.md) ^0.21.1
- [ethers](https://npm.io/package/ethers.md) ^5.0.20
- [bignumber.js](https://npm.io/package/bignumber.js.md) ^9.0.1
- [eth-sig-util](https://npm.io/package/eth-sig-util.md) ^3.0.1
- [reconnecting-websocket](https://npm.io/package/reconnecting-websocket.md) ^4.4.0
- [@ethersproject/transactions](https://npm.io/package/@ethersproject/transactions.md) ^5.0.11

## Alternatives

- [@gemini-wallet/core](https://npm.io/package/@gemini-wallet/core.md) — 515.6K weekly downloads
- [utility](https://npm.io/package/utility.md) — 416.6K weekly downloads
- [@primno/dpapi](https://npm.io/package/@primno/dpapi.md) — 7.2K weekly downloads
- [pi-readseek](https://npm.io/package/pi-readseek.md) — 3.7K weekly downloads
- [@emilia-protocol/verify](https://npm.io/package/@emilia-protocol/verify.md) — 1.1K weekly downloads

## Recent versions

- 1.5.4 (latest) — 2022-03-18
- 1.3.5-gaslimit (gaslimit) — 2021-10-08
- 1.5.3 — 2021-12-15
- 1.5.2 — 2021-12-15
- 1.5.1 — 2021-11-25
- 1.5.0 — 2021-11-03
- 1.3.5 — 2021-09-29
- 1.3.4 — 2021-09-27
- 1.3.3 — 2021-09-27

## README

# Orion Trading SDK

[![code style: eslint](https://img.shields.io/badge/code%20style-eslint-green)](https://github.com/standard/eslint-config-standard)
[![Actions Status](https://github.com/orionprotocol/trading-sdk/workflows/CI/badge.svg)](https://github.com/orionprotocol/trading-sdk/workflows/CI/badge.svg)
[![npm version](https://img.shields.io/npm/v/@orionprotocol/orion-trading-sdk/latest.svg)](https://www.npmjs.com/package/@orionprotocol/orion-trading-sdk/v/latest)

**Attention! For the correct work of the SDK, you need to update the package to the latest version and follow updated instructions below.**

## Installation

```sh
npm install @orionprotocol/orion-trading-sdk
```

## Methods with parameters per module
<hr>

### Module *Chain*

***getWalletBalance(ticker)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*ticker* | string | no | empty ticker field return balance for all tokens

@return token balance on wallet (uint)
<hr>

### Module *OrionAggregator*

***createOrder({...params})***

Parameter | Type | Required | Description
--- | --- | --- | ---
*fromCurrency* | string | yes | token symbol
*toCurrency* | string | yes | token symbol
*side* | string | yes | 'buy' or 'sell'
*price* | number | yes | any number
*amount* | number | yes | any number
*priceDeviation* | number | yes | it's percents, 0 < priceDeviation < 50
*needWithdraw* | boolean | no | false by default, feature in process
*chainPrices* | object | no

*chainPrices* is optional (use it if you already knew prices):

Parameter | Type | Required | Description
--- | --- | --- | ---
*gasWei* | string | yes | gas price in wei
*baseAsset* | string/number | yes | aka 'fromCurrency'
*networkAsset* | string/number | yes
*feeAsset* | string/number | yes

@return prepared and signed order

***sendOrder(order, isCreateInternalOrder)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*order* | object | yes | Order object from `createOrder()`
*isCreateInternalOrder* | boolean | no | Execution only in the internal order book; false by default

@return *orderId*

***cancelOrder(orderId)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*orderId* | string | yes |

@return *orderId* of cancelled order

***getOrderById(orderId, owner)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*orderId* | string | yes |
*owner* | string | no | by default owner address is a current wallet address

@return order with requested id

***getTradeHistory({...options})***
Parameter | Type | Required | Description
--- | --- | --- | ---
*baseAsset* | string | no | token address
*quoteAsset* | string | no | token address
*startTime* | number | no |
*endTime* | number | no |
*limit* | number | no | default 1000

@return list of orders

### Module *Exchange*

***getContractBalance(ticker)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*ticker* | string | no | empty ticker field return balance for all tokens

@return token balance on smart contract (bignumber)

***deposit(token, amount)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*token* | string | yes |
*amount* | string | yes |

@return transaction hash

***withdraw(token, amount)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*token* | string | yes |
*amount* | string | yes |

@return transaction hash

<hr>

### Module *WS*

***priceFeedAll()***
- no params

@return subscriber for all tickers price feed

***priceFeedTicker(ticker)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*ticker* | string | yes |

@return subscriber for specific ticker price feed

***orderBooks(pair)***

Parameter | Type | Required | Description
--- | --- | --- | ---
*pair* | string | yes |

@return subscriber for orderbooks

<hr>

## How to use
 **Important note!** you should always wrap your async functions in a try-catch block, so you could handle errors in a right way.
 ```javascript
try {
    // place here your async functions
    /* Example
        const chain = new Chain(privateKey, networkParams)
        await chain.init() // get blockchain info
     */

} catch(error) {
    // handle errors
}
 ```

**First step:** Create base *Chain* instance

```javascript
import { Chain, Constants } from '@orionprotocol/orion-trading-sdk'

// Set params for Chain constructor

const privateKey = 'your_private_key'

// in Constants.NETWORK you should choose mode (MAIN | TEST) and then chain (BSC | ETH)
const networkParams = Constants.NETWORK.TEST.BSC

// By default networkParams is NETWORK.TEST.BSC

try {
    const chain = new Chain(privateKey, networkParams)

    await chain.init() // get blockchain info
} catch (error) {
    // handle error
}

```
In examples below we hide try-catch blocks, because they are wrappers. But you should always use them.

Now you ready to go.

## Examples
(*previous steps are required*)


**Get wallet balance:**
```javascript
const walletBalance = await chain.getWalletBalance('ORN') // by ticker

const walletBalanceSummary = await chain.getWalletBalance() // summary

/*
    Example:
    { ORN: '13890000000000' } // uint
*/
```

**For further operations, network tokens are required to pay for transactions, as well as tokens for deposit / withdrawal / exchange.**

**Deposit token:**
```javascript
import { Exchange } from '@orionprotocol/orion-trading-sdk'

const exchange = new Exchange(chain)

const deposit = await exchange.deposit('ORN', '10')
// Should return transaction object
```

**Get smart contract balance:**
```javascript
const contractBalance = await exchange.getContractBalance('ORN') // by ticker

const contractBalanceSummary = await exchange.getContractBalance() // summary

/*
    Example:
     {
        ORN: {
          total: [BigNumber],
          locked: [BigNumber],
          available: [BigNumber]
        }
      }
*/
```

**Withdraw token:**
```javascript
const withdraw = await exchange.withdraw('ORN', '10')
// Should return transaction object
```
## Work with OrionAggregator:
Creating, sending, canceling orders and getting info

```javascript
import { OrionAggregator } from '@orionprotocol/orion-trading-sdk'

orionAggregator = new OrionAggregator(chain)

// There is no need to call deprecated method orionAggregator.init() now,
// module is ready to use. But this method is left for backward compatibility.

```

**Create, sign and send order to OrionAggregator:**
```javascript
// create order
const order = {
    fromCurrency: 'ORN',
    toCurrency: 'DAI',
    feeCurrency: 'ORN', // available fee tokens you can find in chain.tokensFee
    side: 'sell',   // 'buy' or 'sell'
    price: 12,
    amount: 10,
    priceDeviation: 1,   // it's percents: 0 < priceDeviation < 50
    // 'chainPrices' is optional, use it when prices are already known
    // to increase request speed
    chainPrices: {
        networkAsset: 57,  // // 'networkAsset' price against ORN
        baseAsset: 1,    // 'fromCurrency' price against ORN
        feeAsset: 1,    // 'feeCurrency' price against ORN
        gasWei: '10000000000'
    }
}

// create and sign order
const signedOrder = await orionAggregator.createOrder(order)

// send order
const sentOrderResponse = await orionAggregator.sendOrder(signedOrder)
// Should return order id if successful
```

**Cancel order:**
```javascript
const orderCancelation = await orionAggregator.cancelOrder(sentOrderResponse.orderId)
// Should return order id if cancelation is successful
```

**Get orders history/status:**
```javascript
// getTradeHistory returns list of orders
const history = await orionAggregator.getTradeHistory()

// getOrderById returns order object
const order = await orionAggregator.getOrderById(sentOrderResponse.orderId)
// const status = order.status
```

## Websockets

**Create WS instance:**
```javascript
import { WS, Constants } from '@orionprotocol/orion-trading-sdk'

// Create ws instance

// in Constants.ORION_WS you should choose mode (MAIN | TEST) and then chain (BSC | ETH)
const wsUrl = Constants.ORION_WS.TEST.BSC

// wsUrl by default is ORION_WS.TEST.BSC
const ws = new WS(wsUrl)

// There is no need to call deprecated method ws.init() now,
// module is ready to use. But this method is left for backward compatibility.
```

**To subscribe to the price feed:**
```javascript
// Subscribe for all tickers
const subscriberForAll = ws.priceFeedAll()

// Subscribe for specified ticker
const subscriberForTicker = ws.priceFeedTicker('ORN-USDT')

subscriberForAll.on('message', (message) => {
    // do something with message data
});

subscriberForTicker.on('message', (message) => {
    // do something with message data
});

// Unsubscribe
subscriberForAll.close()
subscriberForTicker.close()
```

**To subscribe to the orderbooks:**
```javascript
// Subscribe for orderbooks
const subscriberForOrderbooks = ws.orderBooks('ORN-USDT')

subscriberForOrderbooks.on('message', (message) => {
    // do something with message data
});

// Unsubscribe
subscriberForOrderbooks.close()
```

## Testing
To run the tests, follow these steps. You must have at least node v10 installed.

Clone repository

```sh
git clone https://github.com/orionprotocol/trading-sdk
```

Move into the trading-sdk working directory

```sh
cd trading-sdk/
```

Install dependencies

```sh
npm install
```




Run tests

```sh
npm run test
```

You should see output with all test passed

## Resources
- **[Changelog](https://github.com/orionprotocol/trading-sdk/CHANGELOG.md)**

---
_Source: https://npm.io/package/@orionprotocol/orion-trading-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._