Skip to main content

Client

The Market Data Python Client includes functionality for making API requests, handling responses, managing rate limits, and logging. The SDK supports various data types including stocks, options, funds, and market status information.

Get Started Quickly with the MarketDataClient​

  1. Review the documentation on authentication to learn how to set your API token.
  2. Create a MarketDataClient instance and use it to make requests to the Market Data API.
  3. Make a test request and review the console output. The SDK includes logging capabilities to help you debug requests.
  4. Check the rate limit in the client to keep track of your requests and how many requests you have remaining.
  5. Configure Settings to customize output format, date format, and other universal parameters.

MarketDataClient​

class MarketDataClient:
    def __init__(self, token: str = None, logger: Logger = None):
        ...

MarketDataClient is the main client class for interacting with the Market Data API. It provides access to all resources (stocks, options, funds, markets) and handles authentication, rate limiting, and request management.

Properties​

  • token (str): The authentication token for API requests. See authentication documentation for details.
  • rate_limits (UserRateLimits): Current rate limit information
  • base_url (str): The base URL for API requests
  • api_version (str): The API version to use
  • headers (dict): HTTP headers including Authorization and User-Agent
  • default_params (UserUniversalAPIParams): Default universal parameters for API requests. See Settings for details on configuring these parameters.

Resources​

  • stocks (StocksResource): Access to stocks endpoints (prices, quotes, candles, earnings, news)
  • options (OptionsResource): Access to options endpoints (chain, expirations, strikes, quotes, lookup)
  • funds (FundsResource): Access to funds endpoints (candles)
  • markets (MarketsResource): Access to markets endpoints (status)

Methods​

init​

def __init__(self, token: str = None, logger: Logger = None)

Creates and configures a new MarketDataClient instance with default settings. This method initializes the client with the provided token (or reads it from the MARKETDATA_TOKEN environment variable), sets up HTTP client configuration, and initializes rate limits by making a request to the /user/ endpoint.

Parameters​

  • token (str, optional)

    The authentication token for API requests. If not provided, the SDK will attempt to read it from the MARKETDATA_TOKEN environment variable.

  • logger (logging.Logger, optional)

    A custom logger instance from Python's logging module. If not provided, the SDK will use its default logger. You can create a custom logger using marketdata.logger.get_logger().

Returns​

  • MarketDataClient

    A new MarketDataClient instance ready to make API requests.

Notes​

  • The client automatically fetches rate limits during initialization by making a request to /user/ endpoint.
  • The client includes a User-Agent header with the format marketdata-py-{version} (e.g., marketdata-py-0.0.1).
  • All requests include an Authorization: Bearer {token} header.
  • The client uses httpx.Client for HTTP requests with automatic connection pooling.

Example​

from marketdata.client import MarketDataClient

# Token will be automatically obtained from MARKETDATA_TOKEN environment variable
client = MarketDataClient()

# Or provide the token explicitly
client = MarketDataClient(token="your_token_here")

# You can also provide a custom logger
from marketdata.logger import get_logger
custom_logger = get_logger()
client = MarketDataClient(token="your_token_here", logger=custom_logger)

Accessing Rate Limits​

The client automatically fetches and tracks rate limits from the API. Rate limits are initialized when the client is created by making a request to /user/ endpoint, and are updated after each API request based on response headers.

You can access current rate limits:

client = MarketDataClient()

# Access current rate limits
rate_limits = client.rate_limits

# Access individual fields
print(f"Limit: {rate_limits.requests_limit}")
print(f"Remaining: {rate_limits.requests_remaining}")
print(f"Consumed: {rate_limits.requests_consumed}")
print(f"Reset at: {rate_limits.requests_reset}")

# Or use the formatted string representation
print(rate_limits)  # Shows: "Rate used X/Y, remaining: Z credits, next reset: ISO timestamp"

Note: Rate limits are tracked via the following response headers:

  • x-api-ratelimit-limit: Total number of requests allowed
  • x-api-ratelimit-remaining: Number of requests remaining
  • x-api-ratelimit-consumed: Number of requests consumed
  • x-api-ratelimit-reset: Unix timestamp when the rate limit resets

The requests_reset field is automatically converted to a datetime.datetime object for easier use.

Configuration​

The SDK supports flexible configuration of universal parameters through multiple methods. You can configure settings like output format, date format, data mode, and more. See the Settings documentation for complete details on all available configuration options and how to use them.