### Options Surface Chart Example

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Example demonstrating how to create an options volume surface chart using Seaborn.

```APIDOC
## Options Surface Chart Example

### Description
Create a visualization of options volume across strike prices using the library with seaborn.

### Method
(Illustrative example, not a direct API call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import os
import pandas as pd
import seaborn as sns
from convexvalue.core import CVObject

# Configure seaborn theme
sns.set_theme(style='whitegrid')

API_KEY = os.environ.get('CV_API_KEY')
SYMBOL = 'NET'

cvx = CVObject(API_KEY)

# Assuming cvx.getChain is called and response processed into df as in getChain example
# For brevity, let's assume df is already populated with strike and volm
# Example df structure:
# df = pd.DataFrame({
#     'strike': [140, 145, 150, 155, 160],
#     'volm': [500, 800, 1000, 900, 700],
#     'flag': ['C', 'C', 'C', 'P', 'P']
# })

# Fetch data and process into df (as shown in getChain example)
response = cvx.getChain(sym=SYMBOL, exp='1', fields='volm')
options_list = response['data']
df = pd.DataFrame(options_list, columns=['strike', 'volm', 'flag'])
df['strike'] = pd.to_numeric(df['strike'])
df['volm'] = pd.to_numeric(df['volm'])

# Separate calls and puts for plotting
calls = df[df['flag'] == 'C'].copy()
puts = df[df['flag'] == 'P'].copy()

# Create the plot
plt.figure(figsize=(12, 7))

sns.lineplot(data=calls, x='strike', y='volm', label='Calls')
sns.lineplot(data=puts, x='strike', y='volm', label='Puts')

plt.title(f'{SYMBOL} Options Volume Surface')
plt.xlabel('Strike Price')
plt.ylabel('Volume')
plt.legend()
plt.grid(True)
plt.show()
```

### Response
(This is a visualization example, not a direct API response.)
```

--------------------------------

### Install and Configure Convex Value Python

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Instructions for installing the Convex Value Python library using pip and setting up authentication credentials via environment variables. Supports both session-based and legacy API key authentication.

```bash
# Install the library
# pip install convexvalue

# Set environment variables for authentication
# For session-based authentication (recommended):
# export CONVEX_VALUE_EMAIL=your_email@example.com
# export CONVEX_VALUE_PASSWORD=your_password

# For legacy API key authentication:
# export CV_API_KEY=your_api_key
```

--------------------------------

### GET /getChain

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves an options chain for a specific symbol, including volume data, which can be parsed into a pandas DataFrame for analysis.

```APIDOC
## GET /getChain

### Description
Fetches the options chain for a given ticker symbol. Allows filtering by OTM status, strike count, expiration, and specific data fields.

### Method
GET

### Endpoint
/getChain

### Parameters
#### Query Parameters
- **sym** (string) - Required - The ticker symbol to query.
- **otm** (boolean) - Optional - Filter for out-of-the-money options.
- **stks** (integer) - Optional - Number of strikes to return.
- **exp** (string) - Optional - Expiration identifier.
- **fields** (string) - Optional - Specific fields to return (e.g., 'volm').

### Request Example
{
  "sym": "AAPL",
  "otm": "true",
  "stks": 10000,
  "exp": "1",
  "fields": "volm"
}

### Response
#### Success Response (200)
- **data** (array) - List of option objects containing strike, volume, and flag.

#### Response Example
{
  "data": [
    {"strike": "150", "volm": "500", "flag": "call"},
    {"strike": "145", "volm": "300", "flag": "put"}
  ]
}
```

--------------------------------

### Query Options Greeks Data in Python

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

An example of querying specific options data, such as Greeks, for a given symbol using SQL. Demonstrates filtering and limiting results, and converting the output to a pandas DataFrame.

```python
# Example: Query options greeks for a specific symbol
SQL_QUERY = '''
SELECT * FROM opt_greeks
WHERE root = 'AAPL'
LIMIT 100
'''
results = cvx.query_sql(SQL_QUERY)
df = results.df()
```

--------------------------------

### GET /getChain

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/README.md

Retrieves the options chain for a specific stock symbol with customizable parameters for filtering and field selection.

```APIDOC
## GET /getChain

### Description
Retrieves the options chain for a given stock ticker symbol based on specified OTM status, number of strikes, expiration, and data fields.

### Method
GET

### Endpoint
CVObject.getChain(sym, otm, stks, exp, fields)

### Parameters
#### Path Parameters
- **sym** (string) - Required - Symbol of the stock ticker (e.g., AAPL)
- **otm** (string) - Required - Out-of-the-money status (e.g., True)
- **stks** (integer) - Required - Number of strikes to return
- **exp** (string) - Required - Expiration dates (e.g., 1,2,3)
- **fields** (string) - Required - Fields to include (e.g., vol,delta,gamma)

### Response
#### Success Response (200)
- **data** (object) - The requested options chain data.
```

--------------------------------

### GET /getFlowTable

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/README.md

Retrieves the options flow table, allowing for detailed filtering by premium, category, and pagination.

```APIDOC
## GET /getFlowTable

### Description
Fetches the options flow table with support for pagination, premium filtering, and specific field selection.

### Method
GET

### Endpoint
CVObject.getFlowTable(lim, fields, cat, list, page, minprem, maxprem)

### Parameters
#### Query Parameters
- **lim** (integer) - Required - Limit of data records
- **fields** (string) - Required - Fields to include (e.g., value,price,volatility)
- **cat** (string) - Required - Direction category (e.g., ALL)
- **list** (string) - Required - Order by field
- **page** (integer) - Required - Pagination marker
- **minprem** (integer) - Required - Minimum premium filter
- **maxprem** (integer) - Required - Maximum premium filter

### Response
#### Success Response (200)
- **data** (array) - The options flow table data.
```

--------------------------------

### GET /tasQuery

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/README.md

Executes a database query against the TAS (Time and Sales) data with filtering and ordering capabilities.

```APIDOC
## GET /tasQuery

### Description
Queries the database for Time and Sales information based on provided filters and ordering criteria.

### Method
GET

### Endpoint
CVObject.tasQuery(lim, filters, root, dir, orderby)

### Parameters
#### Query Parameters
- **lim** (integer) - Required - Limit of data records to return
- **filters** (string) - Required - Query filters (e.g., size>100)
- **root** (string) - Required - Symbol of stock (e.g., AAPL)
- **dir** (string) - Required - Sort direction (e.g., desc)
- **orderby** (string) - Required - Field to order by (e.g., size)

### Response
#### Success Response (200)
- **result** (array) - List of database records matching the query.
```

--------------------------------

### getFlowTableParams - Get Available Parameters

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves a list of all available parameters that can be used for filtering and selecting fields in the `getFlowTable` endpoint.

```APIDOC
## getFlowTableParams - Get Available Parameters

### Description
Retrieve the list of available parameters for use in flow table fields and filters.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
None

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Get available parameters for flow table queries
params = cvx.getFlowTableParams()

print("Available fields and filters:")
print(params)
```

### Response
#### Success Response (200)
- **fields** (list) - List of available fields for `getFlowTable`.
- **filters** (list) - List of available filters for `getFlowTable`.

#### Response Example
```json
{
  "fields": ["symbol", "price", "volume", "premium", "timestamp"],
  "filters": ["cat", "list", "minprem", "maxprem"]
}
```
```

--------------------------------

### Initialize CVObject API Client

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Demonstrates how to instantiate the CVObject client using an API key retrieved from environment variables.

```python
import os
from convexvalue.core import CVObject

# Get API key from environment
API_KEY = os.environ.get('CV_API_KEY')

# Instantiate the legacy API client
cvx = CVObject(API_KEY)
```

--------------------------------

### Initialize and Use ConvexValue Client

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/README.md

Demonstrates how to import the library, instantiate the client, and retrieve a flow report for a specific symbol.

```python
from convexvalue import ConvexValue

cvx = ConvexValue()
print(cvx.getFlowRep('NET'))
```

--------------------------------

### Initialize ConvexValue Client

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/examples/Example.ipynb

Instantiates the ConvexValue client. It automatically authenticates using the CONVEX_VALUE_EMAIL and CONVEX_VALUE_PASSWORD environment variables.

```python
from convexvalue import ConvexValue
cvx = ConvexValue()
```

--------------------------------

### Configure Authentication Environment Variables

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/README.md

Sets the necessary environment variables for the Convex Value API client. This should be done before initializing the client to avoid hardcoding credentials.

```bash
export CONVEX_VALUE_EMAIL=<email>
export CONVEX_VALUE_PASSWORD=<password>
```

--------------------------------

### Execute SQL Queries with ConvexValue in Python

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Shows how to execute custom SQL queries against the Convex Value database using the `query_sql` method. It covers retrieving options data, converting results to pandas DataFrames, and generating visualizations.

```python
from convexvalue import ConvexValue

cvx = ConvexValue()

# Query SPX options summary data
SQL_QUERY = '''
SELECT *
FROM opt_summary
WHERE symbol LIKE '.SPX%'
LIMIT 50
'''

results = cvx.query_sql(SQL_QUERY)

# Access results as JSON
print(results.json())

# Convert to pandas DataFrame for analysis
df = results.df()
print(df.head())

# Output columns include: symbol, event_time, day_id, day_open_price,
# day_high_price, day_low_price, day_close_price, prev_day_volume, oi, etc.

# Generate a quick visualization
results.plot()
```

--------------------------------

### CVObject - Legacy API Client Initialization

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Initializes the CVObject class to access legacy REST API endpoints using an API key for authentication.

```APIDOC
## CVObject - Legacy API Client

### Description
The CVObject class provides access to the legacy REST API endpoints using API key authentication for options chains, flow tables, and time and sales data.

### Initialization Example
```python
import os
from convexvalue.core import CVObject

# Get API key from environment
API_KEY = os.environ.get('CV_API_KEY')

# Instantiate the legacy API client
cvx = CVObject(API_KEY)
```
```

--------------------------------

### Retrieve and Visualize Options Chain Volume

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

This snippet demonstrates how to query an options chain using the Convex Value API, convert the resulting data into a pandas DataFrame, and generate a line plot comparing volume across strike prices for puts and calls.

```python
response = cvx.getChain(sym=SYMBOL, otm='true', stks=10000, exp='1', fields='volm')
options_list = response['data']
df = pd.DataFrame(options_list, columns=['strike', 'volm', 'flag'])
df['strike'] = pd.to_numeric(df['strike'])
df['volm'] = pd.to_numeric(df['volm'])
plt = sns.lineplot(data=df, x='strike', y='volm', hue='flag')
fig = plt.get_figure()
fig.savefig(f'plot_{SYMBOL}_strike_x_volm.png')
```

--------------------------------

### Query Active Options Database

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves active options based on specific metrics like volume and delta.

```python
response = cvx.activeOptionsQuery(
    lim=100,
    filters='volm>100,delta<0.05,delta>-0.05',
    dir='desc',
    orderby='dayVolume'
)
```

--------------------------------

### POST /query_sql

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Executes a custom SQL query against the Convex Value database to retrieve options and underlying market data. The results are returned as a response object that supports conversion to JSON, pandas DataFrames, and visualizations.

```APIDOC
## POST /query_sql

### Description
Executes a custom SQL query against the Convex Value database to retrieve options and underlying market data. The results are returned as a response object that supports conversion to JSON, pandas DataFrames, and visualizations.

### Method
POST

### Endpoint
/query_sql

### Parameters
#### Request Body
- **query** (string) - Required - The SQL query string to be executed against the database.

### Request Example
{
  "query": "SELECT * FROM opt_summary WHERE symbol LIKE '.SPX%' LIMIT 50"
}

### Response
#### Success Response (200)
- **data** (object) - The raw query result set.
- **status_code** (integer) - The HTTP status code of the request.
- **text** (string) - The raw response text.

#### Response Example
{
  "status_code": 200,
  "data": [{"symbol": ".SPX231215C04500000", "day_close_price": 125.50, "oi": 500}]
}
```

--------------------------------

### activeOptionsQuery - Active Options Database

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Queries the active options database with filters for volume, delta, and other metrics.

```APIDOC
## activeOptionsQuery - Active Options Database

### Description
Query the active options database with filters for volume, delta, and other metrics.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
- **lim** (integer) - Optional - Limit the number of results.
- **filters** (string) - Optional - Filter criteria (e.g., 'volm>100,delta<0.05').
- **dir** (string) - Optional - Sort direction ('desc' or 'asc').
- **orderby** (string) - Optional - Field to order by (e.g., 'dayVolume').

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Find high-volume, low-delta options (potential lottery tickets)
response = cvx.activeOptionsQuery(
    lim=100,                                    # Limit results
    filters='volm>100,delta<0.05,delta>-0.05',  # Volume > 100, near-zero delta
    dir='desc',                                 # Sort descending
    orderby='dayVolume'                         # Order by daily volume
)

print("High Volume Low Delta Options:")
print(response)
```

### Response
#### Success Response (200)
- **(structure varies)** - A list of active options contracts matching the criteria.

#### Response Example
```json
{
  "options": [
    {
      "symbol": "XYZ",
      "strike": 50.00,
      "type": "C",
      "volume": 150,
      "delta": 0.04
    }
  ]
}
```
```

--------------------------------

### Query Options Flow Data

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves recent options activity using filters for premium, category, and pagination.

```python
response = cvx.getFlowTable(
    lim=100,
    fields='value,price,volatility',
    cat='ALL',
    list='ALL',
    page=1,
    minprem=10000,
    maxprem=0
)
```

--------------------------------

### Handle ConvexValueResponse Methods in Python

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Illustrates the various methods available on the ConvexValueResponse object for accessing query results. Includes retrieving data as dictionaries, JSON strings, pandas DataFrames, generating plots, and checking response status.

```python
from convexvalue import ConvexValue

cvx = ConvexValue()

SQL_QUERY = '''
SELECT symbol, day_close_price, oi, prev_day_volume
FROM opt_summary
WHERE symbol LIKE '.AAPL%'
LIMIT 20
'''

results = cvx.query_sql(SQL_QUERY)

# Get raw data as Python dictionary
data = results.data()
print(data)

# Get data as JSON string
json_str = results.json()
print(json_str)

# Convert to pandas DataFrame
df = results.df()
print(df.columns.tolist())
print(df.describe())

# Generate matplotlib plot directly from results
plot = results.plot()

# Check response status
print(f"Status Code: {results.status_code}")
print(f"Raw Text: {results.text}")
```

--------------------------------

### Retrieve and Analyze Options Chain

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Fetches an options chain for a specific symbol and processes the response into a pandas DataFrame for filtering calls and puts.

```python
import os
import pandas as pd
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Get options chain for Cloudflare (NET)
response = cvx.getChain(
    sym='NET',
    otm='true',
    stks=10000,
    exp='1',
    fields='volm'
)

# Extract options data
options_list = response['data']

# Create DataFrame for analysis
df = pd.DataFrame(options_list, columns=['strike', 'volm', 'flag'])
df['strike'] = pd.to_numeric(df['strike'])
df['volm'] = pd.to_numeric(df['volm'])

# Filter puts and calls
calls = df[df['flag'] == 'C']
puts = df[df['flag'] == 'P']
```

--------------------------------

### Execute SQL Query

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/examples/Example.ipynb

Executes a SQL query against the ConvexValue database. The query is defined as a string and passed to the query_sql method.

```python
SQL_QUERY = '''select * from opt_summary where symbol like '.SPX%' limit 5'''
results = cvx.query_sql(SQL_QUERY)
```

--------------------------------

### getFlowRep - Options Flow Report

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Fetches a summary report of options flow activity.

```APIDOC
## getFlowRep - Options Flow Report

### Description
Get the options flow report providing a summary of options flow activity.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
None

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Get flow report
flow_rep = cvx.getFlowRep()

print("Options Flow Report:")
print(flow_rep)
```

### Response
#### Success Response (200)
- **(structure varies)** - A report summarizing options flow activity.

#### Response Example
```json
{
  "total_trades": 15000,
  "total_premium": 25000000,
  "call_volume": 8000,
  "put_volume": 7000
}
```
```

--------------------------------

### Query Time and Sales Data

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Queries the trade-level database with specific filters and sorting criteria.

```python
response = cvx.tasQuery(
    lim=100,
    filters='size>100',
    root='AAPL',
    dir='desc',
    orderby='size'
)
```

--------------------------------

### Visualize Query Results

Source: https://github.com/aaronsdevera/convex-value-python/blob/main/examples/Example.ipynb

Converts the query results into a pandas DataFrame or generates a plot. Requires the results object returned from a query.

```python
results.df()
results.plot()
```

--------------------------------

### tasQuery - Time and Sales Query

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Queries the time and sales database for trade-level data, allowing filtering by trade size and sorting.

```APIDOC
## tasQuery - Time and Sales Query

### Description
Query the time and sales database for trade-level data with filtering and sorting options.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
- **lim** (integer) - Optional - Limit the number of results.
- **filters** (string) - Optional - Filter criteria (e.g., 'size>100').
- **root** (string) - Required - Stock symbol (e.g., 'AAPL').
- **dir** (string) - Optional - Sort direction ('desc' or 'asc').
- **orderby** (string) - Optional - Field to order by (e.g., 'size').

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Query time and sales for large trades
response = cvx.tasQuery(
    lim=100,              # Limit to 100 results
    filters='size>100',   # Filter for trades > 100 contracts
    root='AAPL',          # Stock symbol
    dir='desc',           # Sort direction: desc or asc
    orderby='size'        # Order by trade size
)

print("Large AAPL Trades:")
print(response)
```

### Response
#### Success Response (200)
- **(structure varies)** - A list of trade records with details like time, price, size, and exchange.

#### Response Example
```json
{
  "trades": [
    {
      "time": "10:05:00",
      "price": 170.50,
      "size": 150,
      "exchange": "N"
    }
  ]
}
```
```

--------------------------------

### getFlowTable - Options Flow Data

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves the options flow table with options to filter by category, list, premium, and specify returned fields, supporting pagination.

```APIDOC
## getFlowTable - Options Flow Data

### Description
Retrieve the options flow table showing recent options activity with premium filters and pagination support.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
- **lim** (integer) - Optional - Limit the number of results returned.
- **fields** (string) - Optional - Comma-separated list of fields to include (e.g., 'value,price,volatility').
- **cat** (string) - Optional - Category filter ('ALL', 'CALL', 'PUT').
- **list** (string) - Optional - List filter.
- **page** (integer) - Optional - Pagination page number.
- **minprem** (integer) - Optional - Minimum premium filter.
- **maxprem** (integer) - Optional - Maximum premium filter (0 for no limit).

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Get options flow table with filters
response = cvx.getFlowTable(
    lim=100,                    # Limit results to 100 rows
    fields='value,price,volatility',  # Fields to include
    cat='ALL',                  # Category: ALL, CALL, PUT
    list='ALL',                 # List filter
    page=1,                     # Pagination page number
    minprem=10000,              # Minimum premium filter ($10,000)
    maxprem=0                   # Maximum premium (0 = no limit)
)

print(response)
```

### Response
#### Success Response (200)
- **(structure varies based on fields requested)** - Typically a list of options flow records.

#### Response Example
```json
{
  "data": [
    {
      "symbol": "AAPL",
      "price": 170.50,
      "volume": 500,
      "premium": 15000,
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### getSeries - Price Series Data

Source: https://context7.com/aaronsdevera/convex-value-python/llms.txt

Retrieves historical time series price data for a specified stock symbol.

```APIDOC
## getSeries - Price Series Data

### Description
Retrieve simple time series price data for a stock symbol.

### Method
GET (Implicitly via CVObject method)

### Endpoint
(Not directly exposed as a URL, accessed via CVObject)

### Parameters
- **sym** (string) - Required - Stock ticker symbol (e.g., 'AAPL').

### Request Example
```python
import os
from convexvalue.core import CVObject

API_KEY = os.environ.get('CV_API_KEY')
cvx = CVObject(API_KEY)

# Get price series for Apple
series_data = cvx.getSeries(sym='AAPL')

print("AAPL Price Series:")
print(series_data)
```

### Response
#### Success Response (200)
- **(structure varies)** - Typically a list or dictionary containing historical price data (e.g., open, high, low, close, volume).

#### Response Example
```json
{
  "dates": ["2023-10-26", "2023-10-27"],
  "close": [170.00, 170.50],
  "volume": [50000000, 52000000]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.