Metadata-Version: 2.4
Name: vega-analytica
Version: 0.1.3
Summary: Python client for the Vega Analytica API
Author: Vega Analytica Pty Ltd
License: Proprietary
Project-URL: Homepage, https://vega-analytica.com
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# Vega Analytica Python Client

Python client for the Vega Analytica API.

## Installation

```bash
pip install vega-analytica
```

## Create a client

```python
from vega_analytica import RESTClient

client = RESTClient("YOUR_API_KEY")
```

## Cipher example

```python
result = client.cipher(
    ticker="AAPL",
    region="USA",
    trade_date="2025-01-02",
)
```

## Echo example

Echo uses the same scenario inputs as the Vega Analytica web app:

```python
result = client.echo(
    ticker="AAPL",
    region="USA",
    latest_price_date="2026-08-04",
    latest_price=214.35,
    future_date="2026-11-04",
    target_price=240.00,
    position="long_call",
)

summary = result["summary"]
```

By default, Echo returns only a clean summary of the highest-return contract.

Valid positions are:

- `long_call`
- `short_call`
- `long_put`
- `short_put`

Valid regions are:

- `USA`
- `AUS`
- `CAN`
- `EUR`
- `IND`
- `JPN`
- `UK`

### Additional response data

Use `include` to request additional response sections:

```python
result = client.echo(
    ticker="AAPL",
    region="USA",
    latest_price_date="2026-08-04",
    latest_price=214.35,
    future_date="2026-11-04",
    target_price=240.00,
    position="long_call",
    include=[
        "stock_price_profile",
        "highest_return_contract_profile",
        "option_grid",
    ],
)
```

Supported values are:

- `stock_price_profile`
- `highest_return_contract_profile`
- `option_grid`

The highest-return contract summary is always returned in `result["summary"]`.

### Intermediate price anchors

`price_anchors` contains intermediate anchors only. The client automatically
adds `future_date` and `target_price` as the final anchor.

```python
result = client.echo(
    ticker="AAPL",
    region="USA",
    latest_price_date="2026-08-04",
    latest_price=214.35,
    future_date="2027-02-04",
    target_price=255.00,
    position="long_call",
    price_anchors=[
        {
            "date": "2026-10-05",
            "price": 225.00,
        },
        {
            "date": "2026-12-04",
            "price": 238.00,
        },
    ],
)
```

A maximum of nine intermediate anchors may be supplied, giving ten anchors
after the final future-date anchor is added.

## Rate limiting

Inference is free to use. An account may make one inference request every
15 seconds.

```python
from vega_analytica import RateLimitError

try:
    result = client.echo(
        ticker="AAPL",
        region="USA",
        latest_price_date="2026-08-04",
        latest_price=214.35,
        future_date="2026-11-04",
        target_price=240.00,
        position="long_call",
    )
except RateLimitError as exc:
    print(exc)
    print(exc.retry_after_seconds)
```
