# Python

[GitHub](https://github.com/velodataorg/velo-python), [PyPi](https://pypi.org/project/velodata/)

### Examples

<details>

<summary>Quick Start</summary>

```python
from velodata import lib as velo

# new velo client
client = velo.client('api_key')

# get futures and pick one
future = client.get_futures()[0] 

# get futures columns and pick two
columns = client.get_futures_columns()[:2]

# last 10 minutes in 1 minute resolution
params = {
      'type': 'futures',
      'columns': columns,
      'exchanges': [future['exchange']],
      'products': [future['product']],
      'begin': client.timestamp() - 1000 * 60 * 11,
      'end': client.timestamp(),
      'resolution': '1m'
    }
    
# returns dataframe
print(client.get_rows(params))
```

</details>

<details>

<summary>Aggregated Spot CVD</summary>

```python
from velodata import lib as velo

day_in_ms = 1000 * 60 * 60 * 24

# new velo client
client = velo.client('api_key')

# from one day ago in 10 minute resolution
params = {
      'type': 'spot',
      'columns': ['buy_dollar_volume', 'sell_dollar_volume'],
      'exchanges': ['coinbase', 'binance', 'bybit-spot'],
      'products': ['ETHUSDT', 'ETH-USD'],
      'begin': client.timestamp() - day_in_ms,
      'end': client.timestamp(),
      'resolution': '10m'
    }
    
# returns dataframe
df = client.get_rows(params)

# aggregate all exchanges
df = df.groupby(df['time']).sum(numeric_only=True)

# compute volume delta
df['delta'] = df['buy_dollar_volume'] - df['sell_dollar_volume']

# cumulative
print(df['delta'].cumsum())
```

</details>

<details>

<summary>OI-Weighted Funding Rate</summary>

```python
from velodata import lib as velo

hour_in_ms = 1000 * 60 * 60

# new velo client
client = velo.client('api_key')

# from one hour ago in 1 minute resolution
params = {
      'type': 'futures',
      'columns': ['funding_rate', 'coin_open_interest_close'],
      'exchanges': ['binance-futures', 'bybit', 'okex-swap'],
      'coins': ['SOL'],
      'begin': client.timestamp() - hour_in_ms,
      'end': client.timestamp(),
      'resolution': '1m'
    }
    
# returns dataframe
df = client.get_rows(params)

# oi-weighted funding = SUM(funding*OI) / SUM(OI)
df['funding_rate'] = df['funding_rate'] * df['coin_open_interest_close']
df = df.groupby(df['time']).sum(numeric_only=True)
df['funding_rate'] = df['funding_rate'] / df['coin_open_interest_close']

print(df['funding_rate'])
```

</details>

<details>

<summary>Spot-Vol Correlation</summary>

```python
from velodata import lib as velo

day_in_ms = 1000 * 60 * 60 * 24

# new velo client
client = velo.client('api_key')

# from 5 days ago in 1 hour resolution
params = {
      'type': 'options',
      'columns': ['dvol_close', 'index_price'],
      'exchanges': ['deribit'],
      'products': ['BTC'],
      'begin': client.timestamp() - day_in_ms * 5,
      'end': client.timestamp(),
      'resolution': '1h'
    }
    
# returns dataframe
df = client.get_rows(params)

# simple rolling 24 hour correlation
print(
df['dvol_close'].pct_change().rolling(24).corr(df['index_price'].pct_change())
)
```

</details>

<details>

<summary>Futures Basis</summary>

*Special case: \`3m\_basis\_ann\` is available for BTC and ETH. To request this data, do not specify products, exchanges, or any additional columns*

```python
from velodata import lib as velo

day_in_ms = 1000 * 60 * 60 * 24

# new velo client
client = velo.client('api_key')

# from 5 days ago in 1 hour resolution
params = {
      'type': 'futures',
      'columns': ['3m_basis_ann'],
      'coins': ['BTC', 'ETH'],
      'begin': client.timestamp() - day_in_ms * 5,
      'end': client.timestamp(),
      'resolution': '1h'
    }
    
# returns dataframe
print(client.get_rows(params))
```

</details>

<details>

<summary>Large Request</summary>

Both `get_rows` and `stream_rows` handle batching of large requests automatically, but if you wish to receive batch responses individually rather than in one final DataFrame you should use `stream_rows`.

```python
from velodata import lib as velo

day_in_ms = 1000 * 60 * 60 * 24

# new velo client
client = velo.client('api_key')

# from 5 days ago in 1 minute resolution
# 2 columns * 4 products * 1 exchange * 7200 rows = 57600 values
params = {
      'type': 'futures',
      'columns': ['open_price', 'close_price'],
      'exchanges': ['binance-futures'],
      'products': ['LTCUSDT', 'ETCUSDT', 'BCHUSDT', 'SOLUSDT'],
      'begin': client.timestamp() - day_in_ms * 5,
      'end': client.timestamp(),
      'resolution': '1m'
    }
    
# creates 3 batches (57600 values / 22500 limit)
batches = client.batch_rows(params)  

# prints each batch as it finishes
for df in client.stream_rows(batches):
  print(df) 
```

</details>

<details>

<summary>Orderbook Data</summary>

The `depth` function returns orderbook depth data in snapshots with the specified resolution over the specified time period.&#x20;

```python
from velodata import lib as velo

day_in_ms = 1000 * 60 * 60 * 24

# new velo client
client = velo.client('api_key')

# pick a supported future
futures = client.get_futures()
futures_with_orderbook_data = [f for f in futures if f['depth']]
future = futures_with_orderbook_data[0]

# last 24 hours in 5 minute resolution
params = {
      'exchange': future['exchange'],
      'product': future['product'],
      'begin': client.timestamp() - day_in_ms,
      'end': client.timestamp(),
      'resolution': '5m'
    }

# prints orderbook at each timestamp as it finishes
for df in client.depth(params):
  print(df) 
```

</details>

***

### Helper Methods

* Key status: `get_status()`
* Supported futures: `get_futures(delisted=False)`
* Supported options: `get_options()`
* Supported spot pairs: `get_spot(delisted=False)`
* Supported futures columns: `get_futures_columns()`
* Supported options columns: `get_options_columns()`
* Supported spot columns: `get_spot_columns()`
* Millisecond timestamp: `timestamp()`

***

### **Data Methods**

<details>

<summary>Get rows</summary>

`get_rows(params)`

* type: 'futures', 'options', or 'spot'
* exchanges, products, coins, columns: lists
* begin, end: millisecond timestamps
* resolution: minutes (integer) or resolution (string)

Returns DataFrame

*If both \`coins\` and \`products\` are specified, only \`products\` will be used*

</details>

<details>

<summary>Batch rows</summary>

`batch_rows(params)`

* type: 'futures', 'options', or 'spot'
* exchanges, products, coins, columns: lists&#x20;
* begin, end: millisecond timestamps
* resolution: minutes (integer)

Returns list for use in `stream_rows`

*If both \`coins\` and \`products\` are specified, only \`products\` will be used*

</details>

<details>

<summary>Stream rows</summary>

`stream_rows(batches)`

* batches: list returned from `batch_rows`

Yields DataFrame

</details>

<details>

<summary>Get options term structure</summary>

`get_term_structure(coins)`

* coins: list

Returns DataFrame

*Latest values only*

</details>

<details>

<summary>Get market caps</summary>

`get_market_caps(coins)`

* coins: list

Returns DataFrame

*Latest values only*

</details>

<details>

<summary>Get orderbook data</summary>

`depth(params)`

* exchange, product, coin: string
* begin, end: millisecond timestamps
* resolution: minutes (integer) or resolution (string)

Yields object with `timestamp`, `midprice`, and `price:value` pairs.

*Use 'coin' only for aggregated orderbook data. Use 'product' and 'exchange' for a specific product.*

</details>