ortex 1.0.5
Official Python SDK for ORTEX Financial Data API
Requires Python: >=3.9
Keywords: api, finance, financial-data, fundamentals, market-data, options, ortex, short-interest, stock, trading

# ORTEX Python SDK

Official Python SDK for the ORTEX Financial Data API. Access comprehensive financial data including short interest, stock prices, options, fundamentals, stock scores, and more.

[![PyPI version](https://img.shields.io/pypi/v/ortex.svg)](https://pypi.org/project/ortex/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Short Interest Data** - Shares on loan, utilization, cost to borrow, days to cover
- **Official Short Interest** - FINRA-reported short interest for US, Canada, Australia, Hong Kong
- **Stock Prices** - OHLCV data with historical support
- **Stock Data** - Free float, shares outstanding, stock splits
- **Stock Scores** - Quality, value, momentum, growth scores with custom weights
- **Options Data** - Option chains, expiries, greeks, implied volatility, put/call ratios
- **Fundamentals** - Income statements, balance sheets, cash flow, ratios
- **EU Short Interest** - European regulatory short positions
- **US Government Trades** - Congressional stock trading disclosures
- **Market Data** - Earnings calendar, macro events, exchanges
- **Pagination Support** - Automatic pagination with `iter_all_pages()`
- **Credit Tracking** - Monitor API credit usage with `credits_used` and `credits_left`

## Installation

```bash
pip install ortex
```

## Quick Start

### Get Your API Key

Get your API key at **[app.ortex.com/apis](https://app.ortex.com/apis)**

### Set Up Authentication

```python
import ortex

# Option 1: Set API key directly
ortex.set_api_key("your-api-key")

# Option 2: Use environment variable
# export ORTEX_API_KEY="your-api-key"
# The SDK will automatically use this

# Option 3: Pass to each function
response = ortex.get_short_interest("NYSE", "AMC", api_key="your-api-key")
```

### Basic Usage

```python
import ortex

ortex.set_api_key("your-api-key")

# Get short interest data
response = ortex.get_short_interest("NYSE", "AMC")
df = response.df  # Access data as DataFrame
print(f"Credits used: {response.credits_used}")
print(f"Credits left: {response.credits_left}")

# Get historical short interest
response = ortex.get_short_interest("NYSE", "AMC", "2024-01-01", "2024-12-31")

# Get stock prices
response = ortex.get_price("NASDAQ", "AAPL", "2024-01-01", "2024-12-31")
df = response.df
```

## Response Object

All functions return an `OrtexResponse` object that provides:

```python
response = ortex.get_short_interest("NYSE", "AMC")

# Access data as DataFrame
df = response.df

# Access raw row data
rows = response.rows

# Credit tracking
print(f"Credits used: {response.credits_used}")
print(f"Credits left: {response.credits_left}")

# Pagination info
print(f"Total results: {response.length}")
print(f"Has next page: {response.has_next_page}")

# Iterate through all pages
for page in response.iter_all_pages():
    process(page.df)

# Get all data at once (fetches all pages)
full_df = response.to_dataframe_all()
```

## Pagination

Control page size and iterate through results:

```python
# Set page size
response = ortex.get_short_interest("NYSE", "AMC", page_size=100)

# Iterate through all pages
all_data = []
for page in response.iter_all_pages():
    all_data.extend(page.rows)
    print(f"Fetched {len(page.rows)} rows, credits used: {page.credits_used}")

# Or get everything at once
full_df = response.to_dataframe_all()
```

## All Available Functions

### Short Interest

```python
# Short interest data for a stock
response = ortex.get_short_interest("NYSE", "AMC")
response = ortex.get_short_interest("NYSE", "AMC", "2024-01-01", "2024-12-31")

# Short interest for an index (S&P 500, NASDAQ 100, etc.)
response = ortex.get_index_short_interest("US-S 500")

# Share availability for shorting
response = ortex.get_short_availability("NYSE", "AMC")

# Cost to borrow (all loans or new loans)
response = ortex.get_cost_to_borrow("NYSE", "AMC")
response = ortex.get_cost_to_borrow("NYSE", "AMC", loan_type="new")

# Days to cover
response = ortex.get_days_to_cover("NYSE", "AMC")

# Official (FINRA-reported) short interest for US, CA, AU, HK
response = ortex.get_official_short_interest("AAPL", "US", "2024-01-01")
response = ortex.get_official_short_interest("AAPL", "US", "2024-01-01", "2024-06-30")
```

### Index Short Data

```python
# Index-level short interest data
response = ortex.get_index_short_interest("US-S 500")
response = ortex.get_index_short_availability("US-S 500")
response = ortex.get_index_cost_to_borrow("US-S 500")
response = ortex.get_index_days_to_cover("US-S 500")
```

### Stock Prices

```python
# OHLCV price data
response = ortex.get_price("NASDAQ", "AAPL")
response = ortex.get_price("NASDAQ", "AAPL", "2024-01-01", "2024-12-31")

# Close price (alias for get_price)
response = ortex.get_close_price("NASDAQ", "AAPL")
```

### Stock Data

```python
# Free float shares (from_date is required)
response = ortex.get_free_float("NYSE", "F", "2024-01-01")

# Shares outstanding
response = ortex.get_shares_outstanding("NYSE", "F", "2024-01-01")

# Stock splits history
response = ortex.get_stock_splits("NASDAQ", "AAPL")
response = ortex.get_stock_splits("NASDAQ", "AAPL", from_date="2020-01-01")
```

### Stock Scores

```python
# Get stock scores with default weights (quality, value, momentum, growth, total)
response = ortex.get_stock_scores("NASDAQ", "AAPL")
response = ortex.get_stock_scores("NASDAQ", "AAPL", from_date="2025-01-01")
df = response.df

# Get stock scores with custom weights
weights = {"quality": 50, "growth": 50, "momentum": 65, "dtc": 100, "fcf_assets": 100}
response = ortex.get_stock_scores_custom("NASDAQ", "AAPL", weights)
```

### Options

```python
# List available option expiry dates
response = ortex.get_options_expiries("NASDAQ", "AAPL")

# Get full option chain for a specific expiry
response = ortex.get_options_chain("NASDAQ", "AAPL", "2025-03-21")

# Get option details (greeks, implied vol, open interest, etc.)
response = ortex.get_options_details("NASDAQ", "AAPL", "implied_vol")
response = ortex.get_options_details("NASDAQ", "AAPL", "delta")
# Available parameters: oi, volume, last_price, last_size, ask_price, ask_size,
#   bid_price, bid_size, implied_vol, delta, gamma, theta, vega, rho,
#   put_call_oi_ratio, put_call_volume_ratio

# Get put/call ratio sentiment
response = ortex.get_options_sentiment("NASDAQ", "AAPL")
response = ortex.get_options_sentiment("NASDAQ", "AAPL", days_fwd=30)
```

### Fundamentals

```python
# Income statement
response = ortex.get_income_statement("NYSE", "F", "2024Q3")
print(f"Company: {response.company}")
print(f"Period: {response.period}")
df = response.df  # Financial data as DataFrame

# Balance sheet
response = ortex.get_balance_sheet("NYSE", "F", "2024Q3")

# Cash flow statement
response = ortex.get_cash_flow("NYSE", "F", "2024Q3")

# Financial ratios
response = ortex.get_financial_ratios("NYSE", "F", "2024Q3")

# Fundamentals summary
response = ortex.get_fundamentals_summary("NYSE", "F", "2024Q3")

# Valuation metrics
response = ortex.get_valuation("NYSE", "F", "2024Q3")
```

### EU Short Interest

```python
# EU short positions (individual holders)
response = ortex.get_eu_short_positions("XETR", "SAP")

# EU short positions at a specific date
response = ortex.get_eu_short_positions("XETR", "SAP", "2024-12-01")

# EU short positions history
response = ortex.get_eu_short_positions_history("XETR", "SAP", "2024-01-01", "2024-12-31")

# Total EU short interest
response = ortex.get_eu_short_total("XETR", "SAP")
```

### US Government Trades

```python
# Get all recent congressional trades
response = ortex.get_us_government_trades()

# Filter by ticker
response = ortex.get_us_government_trades(ticker="AAPL")

# Filter by party, chamber, transaction type
response = ortex.get_us_government_trades(party="democrat", chamber="senate")
response = ortex.get_us_government_trades(transaction_type="buy")

# Filter by date range and filer
response = ortex.get_us_government_trades(
    from_date="2024-01-01",
    to_date="2024-12-31",
    filer_name="John Doe",
)
```

### Market Data

```python
# Earnings calendar
response = ortex.get_earnings("2024-12-01", "2024-12-31")

# List of exchanges
response = ortex.get_exchanges()
response = ortex.get_exchanges("United States")

# Macro economic events
response = ortex.get_macro_events("US")
response = ortex.get_macro_events("US", "2024-12-01", "2024-12-15")
```

## Using the Client Directly

For more control, use the `OrtexClient` class:

```python
from ortex import OrtexClient

# Create client
client = OrtexClient(api_key="your-api-key")

# Make requests (returns raw JSON)
data = client.get("NYSE/AMC/short_interest")

# Make requests with OrtexResponse wrapper
response = client.fetch("NYSE/AMC/short_interest")
df = response.df

# POST requests (e.g., stock scores with custom weights)
response = client.fetch_post(
    "stock/NASDAQ/AAPL/stock_scores",
    json={"weights": {"quality": 50, "growth": 50}},
)

# Use as context manager
with OrtexClient(api_key="your-api-key") as client:
    response = client.fetch("stock/NASDAQ/AAPL/closing_prices")
```

## Date Handling

The SDK accepts dates in multiple formats:

```python
from datetime import date, datetime

# String format (YYYY-MM-DD)
response = ortex.get_short_interest("NYSE", "AMC", "2024-01-01", "2024-12-31")

# Python date objects
response = ortex.get_short_interest("NYSE", "AMC", date(2024, 1, 1), date(2024, 12, 31))

# Python datetime objects
response = ortex.get_short_interest("NYSE", "AMC", datetime(2024, 1, 1), datetime(2024, 12, 31))
```

## Error Handling

The SDK provides specific exception types:

```python
import ortex
from ortex import (
    APIError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    ServerError,
)

try:
    response = ortex.get_short_interest("NYSE", "INVALID")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError:
    print("Stock not found")
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except ServerError:
    print("ORTEX server error")
except APIError as e:
    print(f"API error: {e}")
```

## Rate Limiting

The SDK automatically handles rate limiting with exponential backoff:

- Automatically retries on 429 (rate limit) responses
- Uses exponential backoff (1s, 2s, 4s, 8s, up to 60s)
- Maximum 5 retry attempts by default

Configure retry behavior:

```python
from ortex import OrtexClient

client = OrtexClient(
    api_key="your-api-key",
    timeout=60,      # Request timeout in seconds
    max_retries=10,  # Maximum retry attempts
)
```

## Documentation

- **Full API Documentation**: [docs.ortex.com](https://docs.ortex.com)
- **Get API Key**: [app.ortex.com/apis](https://app.ortex.com/apis)
- **Support**: support@ortex.com

## Requirements

- Python 3.9+
- pandas >= 2.0.0
- requests >= 2.31.0
- tenacity >= 8.2.0

## License

MIT License - ORTEX Technologies LTD

## Version

1.0.5