# Install via pip
pip install axionquant-sdk

# Or clone from GitHub
git clone https://github.com/axionquant/python-sdk.git
cd python-sdk
pip install -e .

from axion import Axion

# Initialize client
client = Axion(api_key="your_api_key_here")

# Get stock data
quote = client.stocks.quote("AAPL")
print(f"Apple price: {quote['price']}")

# Get ESG data
esg = client.esg.data("AAPL")
print(f"ESG Score: {esg['score']}")

# Get company profile
profile = client.profiles.info("AAPL")
print(f"Company: {profile['name']}")

from axion import Axion

# Recommended: set API key once
client = Axion(api_key="your_api_key_here")

# All API categories are now available
credit = client.credit.search("Apple")
esg = client.esg.data("AAPL")
stocks = client.stocks.quote("AAPL")
crypto = client.crypto.quote("BTC-USD")

# Get all US stock tickers
us_stocks = client.stocks.tickers(country="US")

# Get quote for a single stock
aapl = client.stocks.quote("AAPL")
print(f"Apple: {aapl['price']} ({aapl['change']}%)")

# Get historical prices with date range
prices = client.stocks.prices(
    "MSFT",
    from_date="2024-01-01",
    to_date="2024-03-31",
    frame="weekly"
)

# Convert to pandas DataFrame
import pandas as pd
df = pd.DataFrame(prices)
df['date'] = pd.to_datetime(df['date'])
print(df.head())

# Get all crypto tickers
all_crypto = client.crypto.tickers()

# Filter by type (e.g., "coin", "token")
stablecoins = client.crypto.tickers(type="stablecoin")

# Get Bitcoin quote
btc = client.crypto.quote("BTC-USD")
print(f"Bitcoin: {btc['price']:,.2f}")

# Get Ethereum historical prices
eth_prices = client.crypto.prices(
    "ETH-USD",
    from_date="2024-01-01",
    to_date="2024-03-31",
    frame="daily"
)

# Get company profile
profile = client.profiles.profile("AAPL")
print(f"Company: {profile['name']}")
print(f"Industry: {profile['industry']}")
print(f"Sector: {profile['sector']}")

# Get key statistics
stats = client.profiles.statistics("AAPL")
print(f"Market Cap: {stats['market_cap']:,.0f}")
print(f"P/E Ratio: {stats['pe_ratio']}")

# Get upcoming events
calendar = client.profiles.calendar("AAPL")
for event in calendar:
    print(f"{event['date']}: {event['event_type']}")

# Get revenue history (last 4 quarters)
revenue = client.financials.revenue("AAPL", periods=4)
for period in revenue:
    print(f"{period['date']}: {period['value']:,.0f}")

# Get comprehensive financial snapshot
snapshot = client.financials.snapshot("AAPL")
print(f"Revenue (TTM): {snapshot['revenue_ttm']:,.0f}")
print(f"Gross Margin: {snapshot['gross_margin']}%")
print(f"Operating Margin: {snapshot['operating_margin']}%")
print(f"Debt/Equity: {snapshot['debt_to_equity']}")

# Calculate free cash flow trend
fcf = client.financials.free_cash_flow("AAPL", periods=5)
fcf_values = [period['value'] for period in fcf]
print(f"FCF Trend: {fcf_values}")

# DCF valuation
dcf = client.financials.dcf_value("AAPL")
print(f"Fair Price: {dcf['fair_price']:.2f}, Recommendation: {dcf['recommendation']}")

# Discount rate / WACC
rate = client.financials.dcf_rate("AAPL")
print(f"WACC: {rate['wacc'] * 100:.2f}%")

# List all available form types
form_types = client.filings.list_forms()
print(form_types[:5])

# Get recent 10-K filings for Apple
filings = client.filings.recent("AAPL", form="10-K", limit=5)
for filing in filings:
    print(f"{filing['filed_date']}: {filing['form']}")

# Search for Q1 2024 filings
q1_filings = client.filings.search(
    form="10-Q",
    year="2024",
    quarter="Q1"
)

# Get specific 10-Q filing in Q1 2024
ten_q = client.filings.history(
    "AAPL",
    form_type="10-Q",
    start_date="2024-01-01",
    end_date="2024-03-31"
)

# Get institutional ownership
institutions = client.insiders.institutions("AAPL")
print("Top Institutional Holders:")
for holder in institutions[:5]:
    print(f"{holder['name']}: {holder['shares']:,} shares")

# Get insider transactions
transactions = client.insiders.transactions("AAPL")
print("
Recent Insider Transactions:")
for tx in transactions[:5]:
    print(f"{tx['date']}: {tx['insider']} - {tx['transaction_type']}: {tx['shares']:,} shares")

# Get ownership breakdown
ownership = client.insiders.ownership("AAPL")
print(f"
Insiders: {ownership['insider_percent']}%")
print(f"Institutions: {ownership['institution_percent']}%")
print(f"Retail: {ownership['retail_percent']}%")

# Get earnings history
history = client.earnings.history("AAPL")
print("Earnings History:")
for period in history:
    print(f"{period['date']}: EPS {period['eps']} vs {period['estimate']} est")

# Get earnings trend
trend = client.earnings.trend("AAPL")
print(f"
Current Quarter Estimate: {trend['current_quarter_estimate']}")
print(f"Next Quarter Estimate: {trend['next_quarter_estimate']}")
print(f"Current Year Estimate: {trend['current_year_estimate']}")

# Get specific quarterly report
q1_2024 = client.earnings.report("AAPL", year="2024", quarter="Q1")
print(f"
Q1 2024 Revenue: {q1_2024['revenue']:,.0f}")
print(f"Q1 2024 EPS: {q1_2024['eps']}")

# Search for inflation series
inflation_series = client.econ.search("inflation")
for series in inflation_series:
    print(f"{series['id']}: {series['name']}")

# Get GDP data
gdp = client.econ.dataset("GDP_USA")
print("
GDP History:")
for observation in gdp['observations'][-5:]:
    print(f"{observation['date']}: {observation['value']}")

# Get important economic events
calendar = client.econ.calendar(
    from_date="2024-04-01",
    to_date="2024-04-30",
    country="US",
    min_importance=3
)
for event in calendar:
    print(f"{event['date']}: {event['event']} - {event['importance']}/3")

# Get overall sentiment
sentiment = client.sentiment.all("TSLA")
print(f"Overall Score: {sentiment['overall_score']}")
print(f"Sentiment: {sentiment['sentiment']}")

# Get social media sentiment
social = client.sentiment.social("TSLA")
print(f"
Social Media:")
print(f"Mentions: {social['mentions']}")
print(f"Positive: {social['positive_percent']}%")
print(f"Negative: {social['negative_percent']}%")

# Get analyst sentiment
analyst = client.sentiment.analyst("TSLA")
print(f"
Analyst Sentiment:")
print(f"Buy: {analyst['buy_count']}")
print(f"Hold: {analyst['hold_count']}")
print(f"Sell: {analyst['sell_count']}")

# Get top general headlines
headlines = client.news.general()
print("Top Financial News:")
for article in headlines[:5]:
    print(f"- {article['title']} ({article['source']})")

# Get company-specific news
aapl_news = client.news.company("AAPL")
print("
Apple News:")
for article in aapl_news[:3]:
    print(f"{article['published_at']}: {article['title']}")

# Get news by category
earnings_news = client.news.category("earnings")
mergers_news = client.news.category("mergers")

# Get Apple's suppliers
suppliers = client.supply_chain.suppliers("AAPL")
print("Apple Suppliers:")
for supplier in suppliers[:5]:
    print(f"- {supplier['name']} ({supplier['ticker']})")

# Get industry peers
peers = client.supply_chain.peers("AAPL")
print("
Industry Peers:")
for peer in peers:
    print(f"- {peer['name']} ({peer['ticker']})")

# Get major customers
customers = client.supply_chain.customers("TSLA")
print("
Tesla Customers:")
for customer in customers:
    print(f"- {customer['name']}")

# Get SPY fund information
spy = client.etfs.fund("SPY")
print(f"SPY - {spy['name']}")
print(f"AUM: {spy['aum']:,.0f}")
print(f"Expense Ratio: {spy['expense_ratio']}%")
print(f"Inception Date: {spy['inception_date']}")

# Get top holdings
holdings = client.etfs.holdings("SPY")
print("
Top Holdings:")
for holding in holdings[:5]:
    print(f"{holding['name']}: {holding['weight']}%")

# Get sector exposure
exposure = client.etfs.exposure("SPY")
print("
Sector Exposure:")
for sector, weight in exposure['sectors'].items():
    print(f"{sector}: {weight}%")

# Get all major forex pairs
pairs = client.forex.tickers()
print("Major Forex Pairs:")
for pair in pairs[:5]:
    print(f"- {pair['symbol']}: {pair['name']}")

# Get EUR/USD quote
eur_usd = client.forex.quote("EUR-USD")
print(f"
EUR/USD: {eur_usd['price']}")
print(f"Change: {eur_usd['change']}%")
print(f"Day Range: {eur_usd['day_low']} - {eur_usd['day_high']}")

# Get historical USD/JPY prices
usd_jpy = client.forex.prices(
    "USD-JPY",
    from_date="2024-01-01",
    to_date="2024-03-31",
    frame="daily"
)

# Get all futures tickers
futures = client.futures.tickers()
print("Available Futures:")
for future in futures[:5]:
    print(f"- {future['symbol']}: {future['name']}")

# Get gold futures quote
gold = client.futures.quote("GC=F")
print(f"
Gold Futures: {gold['price']}")
print(f"Settlement: {gold['settlement']}")
print(f"Open Interest: {gold['open_interest']}")

# Get crude oil futures prices
oil_prices = client.futures.prices(
    "CL=F",
    from_date="2024-01-01",
    to_date="2024-03-31",
    frame="daily"
)

# Get all indices
indices = client.indices.tickers()
print("Major Indices:")
for index in indices[:5]:
    print(f"- {index['symbol']}: {index['name']}")

# Get S&P 500 quote
spx = client.indices.quote("^GSPC")
print(f"
S&P 500: {spx['price']:,.2f}")
print(f"Change: {spx['change']}%")
print(f"YTD Change: {spx['ytd_change']}%")

# Get NASDAQ historical prices
nasdaq = client.indices.prices(
    "^IXIC",
    from_date="2024-01-01",
    to_date="2024-03-31",
    frame="daily"
)

# Search for credit entities
results = client.credit.search("Apple")
for entity in results:
    print(f"{entity['name']} - {entity['entity_type']}")

# Get credit ratings for Apple
ratings = client.credit.ratings("AAPL")
print(f"
Apple Credit Ratings:")
print(f"Moody's: {ratings['moodys']}")
print(f"S&P: {ratings['sp']}")
print(f"Fitch: {ratings['fitch']}")
print(f"Outlook: {ratings['outlook']}")

# Get ESG data for Microsoft
esg = client.esg.data("MSFT")
print(f"Overall ESG Score: {esg['score']}")
print(f"Environmental Score: {esg['environmental_score']}")
print(f"Environmental Grade: {esg['environmental_grade']}")
print(f"Social Score: {esg['social_score']}")
print(f"Social Grade: {esg['social_grade']}")
print(f"Governance Score: {esg['governance_score']}")
print(f"Governance Grade: {esg['governance_grade']}")

# Access detailed metrics
if 'controversies' in esg:
    print(f"
Controversies: {len(esg['controversies'])}")
for metric in esg['key_metrics']:
    print(f"{metric['name']}: {metric['value']}")

# Get web traffic data for Amazon
traffic = client.web_traffic.traffic("AMZN")
print(f"Monthly Visits: {traffic['monthly_visits']:,}")
print(f"Monthly Unique Visitors: {traffic['monthly_unique_visitors']:,}")
print(f"Pages per Visit: {traffic['pages_per_visit']}")
print(f"Average Visit Duration: {traffic['avg_visit_duration']}s")
print(f"Bounce Rate: {traffic['bounce_rate']}%")

# Traffic trends
print("
Traffic by Source:")
for source, percentage in traffic['traffic_sources'].items():
    print(f"{source}: {percentage}%")

# Geographic distribution
print("
Top Countries:")
for country in traffic['top_countries'][:5]:
    print(f"{country['name']}: {country['percentage']}%")

import time
from axion import Axion

client = Axion(api_key="your_api_key_here")

def fetch_with_retry(func, *args, max_retries=3, base_delay=1):
    """Fetch data with exponential backoff retry logic."""
    for attempt in range(max_retries):
        try:
            return func(*args)
        except Exception as e:
            error_str = str(e)

            # Handle rate limiting (429)
            if "429" in error_str and attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt)
                print(f"Rate limited. Retrying in {delay}s...")
                time.sleep(delay)
                continue

            # Handle authentication errors
            elif "Authentication" in error_str or "401" in error_str:
                print("Invalid API key. Please check your credentials.")
                break

            # Handle not found (404)
            elif "404" in error_str:
                print(f"Resource not found: {args}")
                break

            # Handle server errors (5xx)
            elif "500" in error_str or "502" in error_str or "503" in error_str:
                if attempt < max_retries - 1:
                    delay = base_delay * (2 ** attempt)
                    print(f"Server error. Retrying in {delay}s...")
                    time.sleep(delay)
                    continue
                else:
                    print("API server unavailable. Please try again later.")

            # Re-raise unexpected errors
            else:
                raise

    return None

# Usage
data = fetch_with_retry(client.stocks.quote, "AAPL")
if data:
    print(f"Price: {data['price']}")

# Raw API returns:
# {
#   "price": "150.42",
#   "volume": "12345678",
#   "active": "true",
#   "pe_ratio": "25.6",
#   "details": {
#     "has_dividend": "false",
#     "dividend_yield": "0.5"
#   }
# }

# After normalization:
# {
#   "price": 150.42,
#   "volume": 12345678,
#   "active": True,
#   "pe_ratio": 25.6,
#   "details": {
#     "has_dividend": False,
#     "dividend_yield": 0.5
#   }
# }

# Use directly without casting:
data = client.stocks.quote("AAPL")
price = data['price']        # Already a float
volume = data['volume']      # Already an int
if data['active']:           # Already a bool
    print(f"Trading active with P/E {data['pe_ratio']}")