tickerscope

Unofficial async Python client for the MarketSurge stock research API. Wraps the GraphQL endpoints with typed dataclass models and cookie-based auth.

Features

• Sync and async clients (TickerScopeClient / AsyncTickerScopeClient)
• Frozen dataclass models with JSON serialization
• Automatic JWT auth from browser cookies (Firefox/Chrome) via rookiepy
• Token expiry detection and structured error hierarchy

Installation

pip install tickerscope

Authentication

tickerscope authenticates by extracting cookies from your browser. Log into MarketSurge in Firefox or Chrome first, then:

from tickerscope import TickerScopeClient

# Reads cookies from Firefox by default
client = TickerScopeClient()

# Or specify Chrome
client = TickerScopeClient(browser="chrome")

You can also pass a JWT directly or set the TICKERSCOPE_JWT environment variable:

client = TickerScopeClient(jwt="your-jwt-token")

Usage

Sync client

from tickerscope import TickerScopeClient

with TickerScopeClient() as client:
    stock = client.get_stock("AAPL")
    print(stock.ratings.composite)
    print(stock.pricing.price)

    chart = client.get_chart_data(
        "AAPL",
        start_date="2025-01-01",
        end_date="2025-03-01",
    )
    for point in chart.time_series.data_points[:5]:
        print(point.close, point.volume)

Async client

import asyncio
from tickerscope import AsyncTickerScopeClient

async def main():
    async with AsyncTickerScopeClient() as client:
        stock = await client.get_stock("NVDA")
        print(stock.company.name, stock.ratings.composite)

        fundamentals = await client.get_fundamentals("NVDA")
        for period in fundamentals.reported_earnings:
            print(period.period_label, period.value)

asyncio.run(main())

Async client (fully async construction)

Use the create() factory for fully async initialization, including the auth HTTP request:

async def main():
    client = await AsyncTickerScopeClient.create()
    try:
        stock = await client.get_stock("TSLA")
        print(stock.ratings)
    finally:
        await client.aclose()

Available methods

Error handling

All exceptions inherit from TickerScopeError and include a to_dict() method for structured error reporting:

from tickerscope import (
    TickerScopeError,
    AuthenticationError,
    CookieExtractionError,
    TokenExpiredError,
    APIError,
    SymbolNotFoundError,
)

try:
    stock = client.get_stock("INVALID")
except SymbolNotFoundError as exc:
    print(exc.symbol)
    print(exc.to_dict())
except TokenExpiredError:
    # Re-authenticate and retry
    ...

Development

Requires uv for dependency management:

uv sync --all-extras --dev

make lint        # ruff check
make typecheck   # ty check
make radon       # cyclomatic complexity gate (A/B only)
make test        # pytest with coverage
make ci          # all of the above

License

MIT