tickerdb 0.1.14

Connect your agent to pre-computed market context that improves reasoning and reduces token usage.

TickerDB - Market context for agents.

Connect your agent to pre-computed market context that improves reasoning and reduces token usage.

• Sync and async clients
• Full type hints for IDE autocompletion
• Typed exceptions for every error class
• Rate limit information on every response

Full API documentation: https://tickerdb.com/docs

Installation

pip install tickerdb

Quick Start

Synchronous

from tickerdb import TickerDB

client = TickerDB("tdb_your_api_key")

# Get a ticker summary
result = client.summary("AAPL")
print(result["data"])
print(result["data"]["as_of_date"])

# Rate limit info is included on every response
print(result["rate_limits"]["requests_remaining"])

Asynchronous

import asyncio
from tickerdb import AsyncTickerDB

async def main():
    async with AsyncTickerDB("tdb_your_api_key") as client:
        result = await client.summary("AAPL")
        print(result["data"])

asyncio.run(main())

Endpoints

Summary

Get a detailed summary for a single ticker.

result = client.summary("AAPL")
result = client.summary("AAPL", timeframe="weekly")
result = client.summary("AAPL", date="2025-01-15")

Summary payloads are intentionally forward-compatible. Current snapshots include top-level freshness like as_of_date, richer volume fields such as price_direction_on_volume, optional level metadata such as support_level.status_meta when requested, Pro sector_context fields like agreement and overbought_count, and stock-only nested fundamentals.insider_activity when available.

Summary stays band-first by default, so sibling _meta / status_meta stability objects are omitted unless you opt in:

result = client.summary("AAPL", meta=True)
result = client.summary(
    "AAPL",
    fields=["trend.direction", "trend.direction_meta"],
)

MA distance fields are available both in snapshots and events:

result = client.summary("AAPL", fields=["trend.distance_from_ma_band.ma_50"])
print(result["data"]["trend"]["distance_from_ma_band"]["ma_50"])
# "slightly_above"

Summary with Date Range

Get a summary series for one ticker across a date range by passing start and end.

result = client.summary("AAPL", start="2025-01-01", end="2025-03-31")
result = client.summary("AAPL", timeframe="weekly", start="2024-01-01", end="2025-03-31")

Summary with Events Filter

Query event occurrences for a specific band field.

result = client.summary("AAPL", field="momentum_rsi_zone", band="deep_oversold")
result = client.summary("AAPL", field="extremes_condition", band="deep_oversold")
result = client.summary("BTCUSD", field="trend_distance_ma50", band="above")
result = client.summary(
    "BTCUSD",
    field="trend_distance_ma50",
    band="above",
    context_ticker="SPY",
    context_field="trend_distance_ma50",
    context_band="below",
)

For MA distance event fields such as trend_distance_ma50, grouped band="above" and band="below" aliases are supported in addition to granular values like slightly_above.

Watchlist

Get the saved watchlist snapshot for the authenticated account.

result = client.watchlist()
print(result["data"]["as_of_date"])
result = client.watchlist(date="2025-01-15")

Add tickers to the saved watchlist:

result = client.add_to_watchlist(["AAPL", "MSFT", "TSLA"])

Remove tickers from the saved watchlist:

result = client.remove_from_watchlist(["TSLA"])

Watchlist Changes

Get field-level state changes for your saved watchlist tickers since the last pipeline run.

result = client.watchlist_changes()
result = client.watchlist_changes(timeframe="weekly")

Band Stability Metadata

Summary omits sibling _meta objects by default so the primary band label stays front-and-center. Set meta=True to include full paid-tier stability metadata across the response, or request just the few *_meta fields you need via fields.

Summary and watchlist responses also include as_of_date so you can tell which market session the snapshot represents.

result = client.summary("AAPL", meta=True)
data = result["data"]

# The band value itself
print(data["trend"]["direction"])          # "uptrend"

# Stability metadata for that band
print(data["trend"]["direction_meta"])
# {"stability": "established", "periods_in_current_state": 18, "flips_recent": 1, "flips_lookback": 20}

# Type hints available
from tickerdb import Stability, BandMeta

Stability is one of "fresh", "holding", "established", or "volatile". BandMeta contains the full metadata dict. Stability metadata is available on Plus and Pro tiers only.

Stability context also appears in Watchlist, which still includes paid-tier _meta objects by default, and in Watchlist Changes, which include stability fields inline for each changed band.

Query Builder

The SDK includes a fluent query builder for searching assets by categorical state. Chain methods in order: select, filters, sort, limit.

results = client.query() \
    .select('ticker', 'sector', 'trend_distance_ma50', 'momentum_rsi_zone') \
    .eq('trend_distance_ma50', 'slightly_above') \
    .eq('sector', 'Technology') \
    .sort('extremes_condition_percentile', 'asc') \
    .limit(10) \
    .execute()

Error Handling

The SDK raises typed exceptions for all API errors:

from tickerdb import TickerDB, TickerDBError, RateLimitError, NotFoundError

client = TickerDB("tdb_your_api_key")

try:
    result = client.summary("INVALID_TICKER")
except NotFoundError as e:
    print(f"Ticker not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited! Resets at: {e.reset}")
    print(f"Upgrade: {e.upgrade_url}")
except TickerDBError as e:
    print(f"API error [{e.status_code}]: {e.message}")

Exception Hierarchy

Exception	Status Code	Description
TickerDBError	any	Base exception for all API errors
AuthenticationError	401	Invalid or missing API key
ForbiddenError	403	Endpoint restricted to higher tier
NotFoundError	404	Asset not found
RateLimitError	429	Rate limit exceeded
DataUnavailableError	503	Data temporarily unavailable

All exceptions include status_code, error_type, message, and optionally upgrade_url and reset attributes.

Rate Limits

Every response includes a rate_limits dict parsed from the API headers:

result = client.summary("AAPL")
limits = result["rate_limits"]

print(limits["request_limit"])           # Total request limit
print(limits["requests_remaining"])      # Requests remaining
print(limits["request_reset"])           # Reset timestamp
print(limits["hourly_request_limit"])    # Hourly limit
print(limits["hourly_requests_remaining"])  # Hourly remaining

Links

• TickerDB Website
• API Documentation
• PyPI Package