Skip to content

Commit

Permalink
Update readme (#494)
Browse files Browse the repository at this point in the history
* Fix BL3P entry in the readme

* Add alt to logo

* Update README

* VSCode stuff
  • Loading branch information
Johnny A. dos Santos authored and vslee committed Nov 21, 2019
1 parent 7b15124 commit a6cc1ff
Show file tree
Hide file tree
Showing 8 changed files with 227 additions and 59 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -454,3 +454,6 @@ launchSettings.json

## Project specific
**/keys.bin
dist/
data/**
!data/.gitkeep
30 changes: 30 additions & 0 deletions .vscode/launch.template.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"version": "0.2.0",
"configurations": [
{
"name": "CLI: Launch",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "build",
"program": "${workspaceFolder}/src/ExchangeSharpConsole/bin/Debug/netcoreapp3.0/exchange-sharp.dll",
"args": [
// array with the arguments to test the CLI tool
// e.g.
"ws-orderbook", "-e", "bl3p", "-s", "btceur"
],
"cwd": "${workspaceFolder}/data/",
"console": "internalConsole",
"stopAtEntry": false
},
{
// to be used with the CLI tool
// on Debug configuration, all commands accept a --debug flag.
// The program will print to the console the PID that you have to attach to.
// e.g. `$ exchange-sharp ws-orderbook --debug -e bl3p`
"name": "CLI: Attach",
"type": "coreclr",
"request": "attach",
"processId": "${command:pickProcess}"
}
]
}
63 changes: 63 additions & 0 deletions .vscode/tasks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"command": "dotnet",
"type": "process",
"args": [
"build",
"${workspaceFolder}/src/ExchangeSharpConsole/ExchangeSharpConsole.csproj",
"/property:GenerateFullPaths=true",
"/consoleloggerparameters:NoSummary"
],
"problemMatcher": "$msCompile",
"group": {
"kind": "build",
"isDefault": true
}
},
{
"label": "publish",
"command": "dotnet",
"type": "process",
"args": [
"publish",
"${workspaceFolder}/src/ExchangeSharpConsole/ExchangeSharpConsole.csproj",
"-o",
"${workspaceFolder}/dist",
"-c",
"${input:Configuration}",
"/property:GenerateFullPaths=true"
],
"problemMatcher": "$msCompile"
},
{
"label": "test",
"command": "dotnet",
"type": "process",
"args": [
"test",
"${workspaceFolder}/src/ExchangeSharpConsole/ExchangeSharpConsole.csproj",
"/property:GenerateFullPaths=true"
],
"problemMatcher": "$msCompile",
"group": {
"kind": "test",
"isDefault": true
}
}
],
"inputs": [
{
"options": [
"Debug",
"Release"
],
"id": "Configuration",
"type": "pickString",
"default": "Debug",
"description": "The configuration to build",
}
]
}
34 changes: 34 additions & 0 deletions BUILDING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
### Building

#### Required tools
- [.NET Core SDK 3.0](https://dotnet.microsoft.com/download/dotnet-core/3.0) (you can check the exact version on `global.json` in the root folder).

#### Editing (Optional tooling)

On all platforms:
- JetBrains Rider
- VS Code (with C#/Omnisharp extension)
- MonoDevelop

On Windows:
- Visual Studio 2019

On Mac:
- Visual Studio for Mac

### Compiling

All Platforms (command line): `dotnet build ExchangeSharp.sln` \
Windows: Open ExchangeSharp.sln in Visual Studio and build/run \

#### Creating a release version

##### From the command line (bash/powershell):

`dotnet publish src/ExchangeSharpConsole -o $PWD/dist -c Release -r <RID>`

Change `<RID>` to whatever platform you are using. More info [here](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog#using-rids).

##### From Visual Studio

You can also publish from Visual Studio (right click project, select publish), which allows easily changing the platform, .NET core version and self-contained binary settings.
114 changes: 56 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
<img src='logo.png' width='600' />
<img src='logo.png' width='600' alt="Project's logo" />

[![Build Status](https://dev.azure.com/DigitalRuby/DigitalRuby/_apis/build/status/jjxtra_ExchangeSharp?branchName=master)](https://dev.azure.com/DigitalRuby/DigitalRuby/_build/latest?definitionId=5&branchName=master)
[![Build Status](https://dev.azure.com/DigitalRuby/DigitalRuby/_apis/build/status/jjxtra_ExchangeSharp?branchName=master)](https://dev.azure.com/DigitalRuby/DigitalRuby/_build/latest?definitionId=5&branchName=master) [![NuGet](https://img.shields.io/nuget/dt/DigitalRuby.ExchangeSharp.svg)][nuget]

## Overview
ExchangeSharp is a C# console app and framework for trading and communicating with various exchange API end points for cryptocurrency assets. Many exchanges are supported, along with web sockets, withdraws and more! Feel free to visit the discord channel at https://discord.gg/sHCUHH3 and chat with other developers.
ExchangeSharp is a C# **framework/lib** and [console app](#Installing-the-CLI) for trading and communicating with [various](#Exchanges) exchange API end points for cryptocurrency assets. Many exchanges are supported, along with [web sockets](#Websockets), withdraws and more!

Feel free to visit the discord channel at https://discord.gg/sHCUHH3 and chat with other developers.

### Features
- Many exchanges supported with public, private and web socket API
- Easy to use and well documented code and API
- Optional global market symbol normalization, since each exchange has their own way of doing market symbols
- Runs anywhere .NET core will run (Windows 8.1 or newer, MAC, Linux, iOS, Android, Unity 2018+, etc.)
- Runs anywhere .NET Core runs. (Windows, Mac, Linux, Containers, Serverless, iOS, Android, [etc.](https://docs.microsoft.com/en-us/dotnet/core/about))
- Can be used from [many different C# platforms](https://github.com/dotnet/standard/blob/master/docs/versions/netstandard2.0.md#platform-support)
- Has a great [CLI](#Installing-the-CLI) that enables you to use all features from all exchanges right from your command line.

### Exchanges
The following cryptocurrency exchanges are supported:
Expand All @@ -26,7 +30,7 @@ The following cryptocurrency exchanges are supported:
| BitMEX | x | x | R O |
| Bitstamp | x | x | R |
| Bittrex | x | x | T R |
| BL3P | x | | R O |
| BL3P | x | x | R B | Trades stream does not send trade's ids.
| Bleutrade | x | x | |
| Coinbase | x | x | T R |
| Digifinex | x | x | R B |
Expand All @@ -47,94 +51,85 @@ The following cryptocurrency exchanges are supported:
The following cryptocurrency services are supported:
- Cryptowatch (partial)

### Installing the CLI

On *nix systems:
- Run this command `curl https://github.com/jjxtra/ExchangeSharp/raw/master/install-console.sh | sh`

On Windows (or manually):
- Download the [latest binaries](https://github.com/jjxtra/ExchangeSharp/releases/latest) for your OS.
- Unzip it into a folder that is in your environment variable `PATH` (`ctrl` + `shift` + `pause|break` -> Environment Variables)
- Use it from the your preferred command-line emulator (e.g. Powershell, cmd, etc.)
- `exchange-sharp --help` shows all available commands

### Notes
ExchangeSharp uses 'marketSymbol' to refer to markets, or pairs of currencies.
ExchangeSharp uses **`marketSymbol`** to refer to markets, or pairs of currencies.

Please send pull requests if you have made a change that you feel is worthwhile, want a bug fixed or want a new feature. You can also donate to get new features.

### Building
Visual Studio 2017 is recommended. .NET 4.7.2+ or .NET core 2.2+ is required.
If running on Windows, you should use Windows 8.1 or newer.
### [Building/Compiling](./BUILDING.md)

If you must use an older Windows, you'll need to use the Websocket4Net nuget package, and override the web socket implementation by calling
### Websockets

```ExchangeSharp.ClientWebSocket.RegisterWebSocketCreator(() => new ExchangeSharpConsole.WebSocket4NetClientWebSocket());```
If you must use an older Windows (older than win8.1), you'll need to use the [Websocket4Net][websocket4net] nuget package, and override the web socket implementation by calling

See WebSocket4NetClientWebSocket.cs for implementation details.
```
Windows: Open ExchangeSharp.sln in Visual Studio and build/run
Other Platforms: dotnet build ExchangeSharp.sln -f netcoreapp2.1
Ubuntu Release Example: dotnet build ExchangeSharp.sln -f netcoreapp2.1 -c Release -r ubuntu.16.10-x64
```csharp
ExchangeSharp.ClientWebSocket.RegisterWebSocketCreator(
() => new ExchangeSharpConsole.WebSocket4NetClientWebSocket()
);
```

You can also publish from Visual Studio (right click project, select publish), which allows easily changing the platform, .NET core version and self-contained binary settings.
See [`WebSocket4NetClientWebSocket.cs`][websocket4net] for implementation details.

### Nuget
<a href='https://www.nuget.org/packages/DigitalRuby.ExchangeSharp/'>![NuGet](https://img.shields.io/nuget/dt/DigitalRuby.ExchangeSharp.svg)
``` PM> Install-Package DigitalRuby.ExchangeSharp -Version 0.6.3 ```
</a>

### Order Example
```csharp
public static async Task OrderExample()
{
ExchangeKrakenAPI api = new ExchangeKrakenAPI();
ExchangeTicker ticker = await api.GetTickerAsync("XXBTZUSD");
Logger.Info("On the Kraken exchange, 1 bitcoin is worth {0} USD.", ticker.Bid);
#### dotnet CLI
[`dotnet add package DigitalRuby.ExchangeSharp --version 0.6.3`][nuget]

// load API keys created from ExchangeSharpConsole.exe keys mode=create path=keys.bin keylist=public_key,private_key
api.LoadAPIKeys("keys.bin");
#### Package Manager on VS
[`PM> Install-Package DigitalRuby.ExchangeSharp -Version 0.6.3`][nuget]

/// place limit order for 0.01 bitcoin at ticker.Ask USD
ExchangeOrderResult result = await api.PlaceOrderAsync(new ExchangeOrderRequest
{
Amount = 0.01m,
IsBuy = true,
Price = ticker.Ask,
MarketSymbol = "XXBTZUSD"
});
### Examples

// Kraken is a bit funny in that they don't return the order details in the initial request, so you have to follow up with an order details request
// if you want to know more info about the order - most other exchanges don't return until they have the order details for you.
// I've also found that Kraken tends to fail if you follow up too quickly with an order details request, so sleep a bit to give them time to get
// their house in order.
await Task.Delay(500);
result = await api.GetOrderDetailsAsync(result.OrderId);
#### Creating an order

Logger.Info("Placed an order on Kraken for 0.01 bitcoin at {0} USD. Status is {1}. Order id is {2}.", ticker.Ask, result.Result, result.OrderId);
}
```
There's a lot of examples on how to use the API in our [console application](./src/ExchangeSharpConsole/Options). \
e.g.
[`ExampleOption.cs`](./src/ExchangeSharpConsole/Options/ExampleOption.cs)

#### Getting ticker info via Web Sockets

### Web Socket Example
```csharp
public static async Task Main(string[] args)
{
// create a web socket connection to Binance. Note you can Dispose the socket anytime to shut it down.
using var api = new ExchangeBinanceAPI();
// the web socket will handle disconnects and attempt to re-connect automatically.
ExchangeBinanceAPI b = new ExchangeBinanceAPI();
using (var socket = await b.GetTickersWebSocket((tickers) =>
using var socket = await api.GetTickersWebSocket(tickers =>
{
Console.WriteLine("{0} tickers, first: {1}", tickers.Count, tickers.First());
}))
{
Console.WriteLine("Press ENTER to shutdown.");
Console.ReadLine();
}
});

Console.WriteLine("Press ENTER to shutdown.");
Console.ReadLine(true);
}
```

### Logging
ExchangeSharp uses NLog internally currently. To log, use ExchangeSharp.Logger. Do not use Console.WriteLine to log messages.
ExchangeSharp uses NLog internally _currently_. To log, use `ExchangeSharp.Logger`.

Do **not** use `Console.WriteLine` to log messages in the lib project.

Provide your own nlog.config or app.config nlog configuration if you want to change logging settings or turn logging off.
Provide your own `nlog.config` or `app.config` nlog configuration if you want to change logging settings or turn logging off.

### Caching
The ExchageAPI class provides a method caching mechanism. Use MethodCachePolicy to put caching behind public methods, or clear to remove caching. Some methods are cached by default. You can set ExchangeAPI.UseDefaultMethodCachePolicy to false to stop all caching as well.

The `ExchageAPI` class provides a method caching mechanism. Use `MethodCachePolicy` to put caching behind public methods, or clear to remove caching. Some methods are cached by default. You can set `ExchangeAPI.UseDefaultMethodCachePolicy` to `false` to stop all caching as well.

You can also set request cache policy if you want to tweak how the http caching behaves.

### How to contribute
Please read the [contributing guideline](CONTRIBUTING.md) before submitting a pull request.
Please read the [contributing guideline](CONTRIBUTING.md) **before** submitting a **pull request**.

### Consulting
I'm happy to make customizations to the software for you and keep in private repo, email exchangesharp@digitalruby.com.
Expand All @@ -158,3 +153,6 @@ Thanks for visiting!
Jeff Johnson
jeff@digitalruby.com
http://www.digitalruby.com

[nuget]: https://www.nuget.org/packages/DigitalRuby.ExchangeSharp/
[websocket4net]: https://github.com/kerryjiang/WebSocket4Net
1 change: 1 addition & 0 deletions data/.gitkeep
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Just to keep this folder here (this folder can be used to store data without commiting it to git)
39 changes: 39 additions & 0 deletions install-console.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
#!/bin/sh

set -e

if [ -z $INSTALL_DIR ]; then
INSTALL_DIR=/usr/local/bin/
else
INSTALL_DIR="$(realpath -s $INSTALL_DIR)"
fi

OS=
case "$(uname -s)" in
Darwin)
OS=osx
;;
Linux)
OS=linux
;;
CYGWIN*|MINGW32*|MSYS*)
OS=win
;;
*)
echo -e 'Failed to identify the OS.'
return 1
;;
esac

TAG=$(curl -Ssf https://api.github.com/repos/johnnyasantoss/ExchangeSharp/releases/latest | jq -r .name)
echo "Downloading version: '${TAG}'..."

curl -SfL# -o /tmp/exchangesharp.zip "https://github.com/johnnyasantoss/ExchangeSharp/releases/download/${TAG}/${OS}-x64.zip"

unzip -qq -o /tmp/exchangesharp.zip -d /tmp/exchangesharp/

sh -c "set -ex; sudo mv /tmp/exchangesharp/exchange-sharp ${INSTALL_DIR}exchange-sharp"

rm -rf /tmp/exchangesharp.zip /tmp/exchangesharp/

echo "🎉 Installed in ${INSTALL_DIR}exchange-sharp"
2 changes: 1 addition & 1 deletion src/ExchangeSharpConsole/Options/ExampleOption.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ public class ExampleOption : BaseOption, IOptionWithKey
{
public override async Task RunCommand()
{
var api = new ExchangeKrakenAPI();
using var api = new ExchangeKrakenAPI();
var ticker = await api.GetTickerAsync("XXBTZUSD");

Console.WriteLine("On the Kraken exchange, 1 bitcoin is worth {0} USD.", ticker.Bid);
Expand Down

0 comments on commit a6cc1ff

Please sign in to comment.