koin 0.0.3
A simple library for Coinbase Pro
Requires Python: >=3.5
Keywords: meli

# Koin

A simple library for interacting with the Coinbase Pro API.

It was born out of the need to programmatically monitor and trade on Coinbase Pro and it is slowly being developed to cover all of the endpoints supported. The library is currently in Alpha version, which means I am still testing and modifying heavily, I will make my best effort to keep things as stable as possible, but expect features and interfaces to change.

The MIT license is quite straightforward, but I just want to reiterate that this software is provided AS IS with no __warranty__. Obviously automating trading can be dangerous for your pocket, but it is up to you to use this library wisely!

__It is NOT a library for the regular Coinbase product, this is only for Coinbase Pro.__

## Authentication

You need to generate your own `key`, `passphrase` and `secret`. You can do this by going to the web portal at [pro.coinbase.com](https://pro.coinbase.com), clicking on your profile and then going to the API section. You can choose the permissions (View, Transfer, Trade). I recommend isolating permissions to only what you need per app.

You can generate your keys by clicking 'New API Key'. Make sure you note these down in a json with the following structure:

```json
{
 "key":"xxxxx",
 "passphrase":"xxxxxx",
 "secret":"xxxxxxxxxxxxxxxxxx"
}
```

If you save it as `credentials.json` in the folder where your code is, then `Koin` will pick it up. 

```
k = koin.Koin()
```

Otherwise you will need to specify the location of the credentials file.

```
k = koin.Koin(credentials_file = 'credentials/my_coinbase_pro_credentials.json')
```

## Sandbox

I recommend using the sandbox environment before interacting with the production environment. For this you will need to create separate API Keys in the separate Sandbox web portal. You can find it at:

[https://public.sandbox.exchange.coinbase.com/](https://public.sandbox.exchange.coinbase.com/)

Once you have your keys generated and saved in a json, you need to specify its for the sandbox environment as follows:

```
k = koin.Koin(credentials_file = 'sandbox.json', sandbox=True)
```

## Functions

As I mentioned, the aim is to cover all endpoints. As I make them available, I will add them to this section. More information is available from Coinbase Pro on their [API Documentation](https://docs.cloud.coinbase.com/exchange/reference)

### Accounts

Get a list of trading accounts from the profile of the API key

```python
k.accounts()
```

### Market Order

Create a market order which is executed at the current market price. Here you can only specify either the ammount of base currency you want, or the ammount of quote currency you want to use in the trade.
For more information about how trading works, consult the Coinbase Pro documentation.

|Keyword argument|Required|Values|Description|
|---|---|---|---|
|`product_id`|Yes|e.g `'BTC-USD'`|The currency pair you want to trade (base currency - quote currency)|
|`side`|Yes|`'sell'` or `'buy'`|Do you want to buy or sell the base currency|
|`size`|No|`0.5`|The ammount of the base currency you want to trade. You must specify either `size` or `funds`|
|`funds`|No|`58.7`|The ammount of the quote currency you want to use. You must specify either `size` or `funds`|

```python
k.place_market_order(
 product_id = 'ETH-USD',
 side = 'buy',
 size = 0.1
)
```

### Limit Order

Create a limit order which is executed if and when the `price` you specify is reached. For more information about how trading works, consult the Coinbase Pro documentation.

|Keyword argument|Required|Values|Description|
|---|---|---|---|
|`product_id`|Yes|e.g `'BTC-USD'`|The currency pair you want to trade|
|`side`|Yes|`'sell'` or `'buy'`|Is it a buy or sell order|
|`price`|Yes|e.g. `2100.5`|The market price you want to execute at|
|`size`|Yes|`0.5`|The ammount of the base currency you want to trade|
|`time_in_force`|No|`'GTC'`, `'GTT'`, `'IOC'` or `'FOK'`|The time in force policy: Good Til Cancel, Good Til Time, Immediate or Cancel, Fill or Kill. Default is Good til Cancel|
|`cancel_after`|No|`'min'`, `'hour'` or `'day'`|Required when the order is `'GTC'`. This is the ammount of time after which the order is cancelled if not filled|
|`post_only`|No|`'True'` or `'False'`|Post Only is a flag to ensure your limit order is posted to the order book and is not immediatelly fileld|

```python
k.place_limit_order(
 product_id = 'ETH-USD',
 side = 'buy',
 price = 2000,
 size = 0.1
)
```

### Candles

Get historical rates for a product.

|Keyword argument|Required|Values|Description|
|---|---|---|---|
|`product_id`|Yes|e.g `'BTC-USD'`|The currency pair you want to get information for|
|`granularity`|No|`60`, `300`, `900`, `3600`, `21600` or `86400`|The size of the bucket for each candle returned. Default is `60`|
|`start`|No|e.g `1629331200`|The start time (in epoch) for the period you want to query|
|`end`|No|e.g `1629331200`|The end time (in epoch) for the period you want to query|


```python
k.candles(
 product_id = 'ETH-USD',
 granularity = 900
)