Skip to content

Models API Reference

OHLCVBar

stockfeed.models.ohlcv.OHLCVBar

Bases: BaseModel

Source code in src/stockfeed/models/ohlcv.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class OHLCVBar(BaseModel):
    ticker: str
    timestamp: datetime  # Always UTC
    interval: Interval
    open: Decimal
    high: Decimal
    low: Decimal
    close_raw: Decimal  # Unadjusted close
    close_adj: Decimal | None  # Split/dividend adjusted — None if not provided
    volume: int
    vwap: Decimal | None  # If available
    trade_count: int | None  # If available
    provider: str

    @field_validator("ticker")
    @classmethod
    def ticker_must_not_be_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("ticker must not be empty")
        return v.upper()

Quote

stockfeed.models.quote.Quote

Bases: BaseModel

Source code in src/stockfeed/models/quote.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class Quote(BaseModel):
    ticker: str
    timestamp: datetime
    bid: Decimal | None
    ask: Decimal | None
    bid_size: int | None
    ask_size: int | None
    last: Decimal
    last_size: int | None
    volume: int | None
    open: Decimal | None
    high: Decimal | None
    low: Decimal | None
    close: Decimal | None
    change: Decimal | None
    change_pct: Decimal | None
    provider: str

    @field_validator("ticker")
    @classmethod
    def ticker_must_not_be_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("ticker must not be empty")
        return v.upper()

TickerInfo

stockfeed.models.ticker.TickerInfo

Bases: BaseModel

Source code in src/stockfeed/models/ticker.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class TickerInfo(BaseModel):
    ticker: str
    name: str
    exchange: str
    currency: str
    country: str | None
    sector: str | None
    industry: str | None
    market_cap: int | None
    provider: str

    @field_validator("ticker")
    @classmethod
    def ticker_must_not_be_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("ticker must not be empty")
        return v.upper()

HealthStatus

stockfeed.models.health.HealthStatus

Bases: BaseModel

Source code in src/stockfeed/models/health.py 
 6
 7
 8
 9
10
11
12
class HealthStatus(BaseModel):
    provider: str
    healthy: bool
    latency_ms: float | None
    error: str | None
    checked_at: datetime
    rate_limit_remaining: int | None

Interval

stockfeed.models.interval.Interval

Bases: str, Enum

Source code in src/stockfeed/models/interval.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
class Interval(str, Enum):
    ONE_MINUTE = "1m"
    FIVE_MINUTES = "5m"
    FIFTEEN_MINUTES = "15m"
    THIRTY_MINUTES = "30m"
    ONE_HOUR = "1h"
    FOUR_HOURS = "4h"
    ONE_DAY = "1d"
    ONE_WEEK = "1w"
    ONE_MONTH = "1mo"

StockFeedResponse

stockfeed.models.response.StockFeedResponse

Bases: BaseModel, Generic[T]

Source code in src/stockfeed/models/response.py 
11
12
13
14
15
16
17
18
class StockFeedResponse(BaseModel, Generic[T]):
    data: T
    provider_used: str
    cache_hit: bool
    latency_ms: float
    timestamp: datetime  # When response was assembled
    interval: Interval | None
    ticker: str | None

Options models

GreeksSource

stockfeed.models.options.GreeksSource

Bases: str, Enum

Source code in src/stockfeed/models/options.py 
 8
 9
10
class GreeksSource(str, Enum):
    API = "api"
    CALCULATED = "calculated"

Greeks

stockfeed.models.options.Greeks

Bases: BaseModel

Source code in src/stockfeed/models/options.py 
13
14
15
16
17
18
19
class Greeks(BaseModel):
    delta: Decimal | None
    gamma: Decimal | None
    theta: Decimal | None
    vega: Decimal | None
    rho: Decimal | None
    source: GreeksSource

OptionType

stockfeed.models.options.OptionType

Bases: str, Enum

Source code in src/stockfeed/models/options.py 
22
23
24
class OptionType(str, Enum):
    CALL = "call"
    PUT = "put"

OptionContract

stockfeed.models.options.OptionContract

Bases: BaseModel

Source code in src/stockfeed/models/options.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class OptionContract(BaseModel):
    # OCC symbol (e.g. AAPL240119C00150000) — differs from ticker; encodes expiry, type, strike
    symbol: str
    underlying: str
    expiration: date
    strike: Decimal
    option_type: OptionType
    bid: Decimal | None
    ask: Decimal | None
    last: Decimal | None
    volume: int | None
    open_interest: int | None
    implied_volatility: Decimal | None
    greeks: Greeks | None
    provider: str

    @field_validator("symbol")
    @classmethod
    def symbol_must_not_be_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("symbol must not be empty")
        return v.upper()

    @field_validator("underlying")
    @classmethod
    def underlying_uppercase(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("underlying must not be empty")
        return v.strip().upper()

OptionChain

stockfeed.models.options.OptionChain

Bases: BaseModel

Source code in src/stockfeed/models/options.py 
58
59
60
61
62
class OptionChain(BaseModel):
    underlying: str
    expiration: date
    contracts: list[OptionContract]
    provider: str

OptionQuote

stockfeed.models.options.OptionQuote

Bases: BaseModel

Source code in src/stockfeed/models/options.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class OptionQuote(BaseModel):
    symbol: str
    underlying: str
    timestamp: datetime
    bid: Decimal | None
    ask: Decimal | None
    last: Decimal | None
    volume: int | None
    open_interest: int | None
    implied_volatility: Decimal | None
    greeks: Greeks | None
    provider: str

    @field_validator("symbol")
    @classmethod
    def symbol_must_not_be_empty(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("symbol must not be empty")
        return v.upper()