StockAPI Team

# Accuracy = matching the exchange's official data
exchange_price = 43251.50  # Direct from Binance API
parser_price = 43251.50    # From your data source

accuracy = 100% if exchange_price == parser_price else 0%

# ❌ BAD: Scraping HTML (30-60s delay)
import requests
from bs4 import BeautifulSoup

html = requests.get("https://exchange.com/markets/BTC-USD").text
soup = BeautifulSoup(html, 'html.parser')
price = float(soup.find("div", class_="price").text)

# Issues:
# - Price from 30-60 seconds ago
# - HTML may be cached by CDN
# - No timestamp information
# - Can't verify freshness

# ❌ BAD: Fragile HTML parsing
price_text = soup.find("span", class_="price-value").text
# "$ 43,251.50 USD"

# Naive parsing
price = float(price_text.replace("$", "").replace(",", ""))
# Works... until exchange changes format to "43.251,50" (EU format)
# Result: Crash or wrong data

# ✅ GOOD: Direct API access with validation
from stockapi import BinanceParser

parser = BinanceParser()
ticker = parser.get_ticker("BTCUSDT")

print(f"Price: ${ticker['price']}")
print(f"Timestamp: {ticker['timestamp']}")  # Server timestamp
print(f"Data age: {ticker['age_ms']}ms")    # Calculated freshness

# Guarantees:
# - Direct from exchange API
# - Validated against schema
# - Timestamp included
# - Sub-second freshness
# - 99.99% accuracy rate

# Compare provider data against exchange API
import time
from stockapi import BinanceParser

parser = BinanceParser()
correct = 0
total = 0

for _ in range(1000):
    # Get from both sources simultaneously
    parser_data = parser.get_ticker("BTCUSDT")
    exchange_data = requests.get(
        "https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT"
    ).json()

    if parser_data['price'] == float(exchange_data['price']):
        correct += 1
    total += 1

    time.sleep(1)

accuracy = (correct / total) * 100
print(f"Accuracy: {accuracy}%")

# StockAPI Results:
# - Binance: 99.99% (5 mismatches in 50,000 samples)
# - Coinbase: 99.98%
# - NYSE: 99.95%
#
# Typical DIY Scraping:
# - 85-95% accuracy (frequent parsing errors)

# Latency = time from event to data availability
event_time = 1699564723.145  # Exchange timestamp
receive_time = 1699564723.198  # Local timestamp

latency_ms = (receive_time - event_time) * 1000
# Target: <100ms for real-time trading

# Arbitrage opportunity window
binance_price = 43250.00  # Updated at T+0ms
coinbase_price = 43270.00 # Updated at T+50ms (50ms latency)

spread = 43270 - 43250 = $20 profit opportunity

# But...
# High-frequency traders with 10ms latency already took it
# You arrive at T+50ms: opportunity gone
# Result: Missed trade

# ✅ Real-world latency measurement
from stockapi import BinanceParser
import time

parser = BinanceParser()
latencies = []

for update in parser.stream_ticker("BTCUSDT"):
    exchange_time = update['timestamp']
    local_time = time.time() * 1000

    latency = local_time - exchange_time
    latencies.append(latency)

    if len(latencies) == 1000:
        break

# Calculate percentiles
p50 = sorted(latencies)[500]   # Median
p95 = sorted(latencies)[950]   # 95th percentile
p99 = sorted(latencies)[990]   # 99th percentile

print(f"Median latency: {p50:.2f}ms")
print(f"P95 latency: {p95:.2f}ms")
print(f"P99 latency: {p99:.2f}ms")

# StockAPI Results (WebSocket):
# - P50: 35ms
# - P95: 85ms
# - P99: 150ms
#
# DIY Scraping (REST polling):
# - P50: 650ms
# - P95: 2400ms
# - P99: 5000ms+

# Uptime = percentage of time data is available
uptime_percentage = (operational_time / total_time) * 100

# ❌ BAD: Crashes on first error
import requests

while True:
    response = requests.get("https://api.binance.com/ticker")
    data = response.json()
    # Process data...

# What happens when:
# - Network hiccup: CRASH
# - API rate limit: CRASH
# - Server timeout: CRASH
# - Invalid JSON: CRASH
#
# Requires manual restart
# 95% uptime at best

# ❌ BAD: Fails silently, returns stale data
cached_price = 43250.00

try:
    response = requests.get("https://api.binance.com/ticker", timeout=1)
    price = response.json()['price']
except:
    price = cached_price  # Return old data!

# Problems:
# - Trading on stale data
# - No error notification
# - Silent degradation
# - False confidence

# ✅ GOOD: Automatic recovery with monitoring
from stockapi import BinanceParser

parser = BinanceParser(
    retry_attempts=5,
    retry_delay=1.0,
    circuit_breaker=True,  # Stop on repeated failures
    health_check_interval=60,
)

# Real-time health monitoring
if parser.is_healthy():
    ticker = parser.get_ticker("BTCUSDT")
else:
    # Parser detected issues and switched to backup
    send_alert("Primary parser unhealthy, using backup")

# Handles automatically:
# - Network failures
# - API rate limits
# - Server timeouts
# - Invalid responses
# - 99.9% uptime guaranteed

# 30-day uptime tracking
import time
from stockapi import BinanceParser

parser = BinanceParser()
successful_calls = 0
failed_calls = 0

# Check every minute for 30 days
for _ in range(43200):  # 30 days * 24 hours * 60 minutes
    try:
        ticker = parser.get_ticker("BTCUSDT", timeout=5)
        if ticker and ticker['price'] > 0:
            successful_calls += 1
        else:
            failed_calls += 1
    except:
        failed_calls += 1

    time.sleep(60)

uptime = (successful_calls / (successful_calls + failed_calls)) * 100
print(f"30-day uptime: {uptime}%")

# StockAPI Results:
# - 99.92% uptime (35 minutes downtime/month)
#
# DIY Scraping Results:
# - 85-95% uptime (36-108 hours downtime/month)

# Completeness = percentage of expected data fields present
expected_fields = [
    'symbol', 'price', 'volume', 'high', 'low',
    'open', 'close', 'timestamp', 'change_24h'
]

received_fields = list(data.keys())
completeness = (
    len(set(expected_fields) & set(received_fields)) /
    len(expected_fields)
) * 100

# ❌ BAD: Scraping misses fields
html_data = {
    'price': 43250.00,
    'symbol': 'BTCUSDT',
    # Missing: volume, timestamp, high/low, change
}

# Can't calculate:
# - Price momentum (no change %)
# - Volume trend (no volume)
# - Data freshness (no timestamp)
# - Daily range (no high/low)

# ✅ GOOD: Complete data set
from stockapi import BinanceParser

parser = BinanceParser()
ticker = parser.get_ticker("BTCUSDT")

print(ticker)
# {
#   'symbol': 'BTCUSDT',
#   'price': 43250.00,
#   'volume_24h': 28450.5,
#   'high_24h': 44100.00,
#   'low_24h': 42800.00,
#   'open_24h': 43000.00,
#   'close_24h': 43250.00,
#   'change_24h': 0.58,
#   'change_percent_24h': '0.58%',
#   'timestamp': 1699564723145,
#   'bid': 43249.50,
#   'ask': 43250.50,
#   'spread': 1.00,
# }

# 100% completeness
# All fields guaranteed
# Validated schema

# When your scraper was down, can you recover the data?

# ❌ DIY Scraping: Data is lost forever
downtime_start = "2024-03-15 14:30:00"
downtime_end = "2024-03-15 14:42:00"
# 12 minutes of missing data
# Can't recover: exchange APIs don't provide historical tick data
# Result: Gaps in your database

# ✅ StockAPI: Automatic backfill
parser = BinanceParser()
historical_data = parser.get_ticker_history(
    symbol="BTCUSDT",
    start_time="2024-03-15 14:30:00",
    end_time="2024-03-15 14:42:00",
    interval="1m"
)
# Complete data recovered
# No gaps in historical analysis

# ❌ BAD: REST API polling (500ms+ latency)
import time
import requests

while True:
    response = requests.get("https://api.binance.com/api/v3/ticker/price?symbol=BTCUSDT")
    price = response.json()['price']
    print(f"BTC: ${price}")
    time.sleep(0.1)  # Poll every 100ms

# Problems:
# - 500ms+ total latency (network + processing)
# - Wasted bandwidth (99% unchanged data)
# - Rate limited after 1200 requests/minute
# - Missed price updates between polls
# - No guaranteed delivery

# ❌ COMPLEX: Manual WebSocket handling
import asyncio
import websockets
import json

async def binance_ticker():
    url = "wss://stream.binance.com:9443/ws/btcusdt@ticker"

    while True:  # Reconnection loop
        try:
            async with websockets.connect(url) as ws:
                while True:
                    message = await ws.recv()
                    data = json.loads(message)
                    print(f"Price: {data['c']}")

        except websockets.exceptions.ConnectionClosed:
            print("Connection closed, reconnecting...")
            await asyncio.sleep(1)
        except Exception as e:
            print(f"Error: {e}")
            await asyncio.sleep(5)

asyncio.run(binance_ticker())

# Problems:
# - Manual reconnection logic
# - No ping/pong handling
# - Missing error recovery
# - No message buffering
# - 50+ lines for production-ready code

# ✅ GOOD: Automatic WebSocket management
from stockapi import BinanceParser

parser = BinanceParser()

# Real-time ticker stream
for update in parser.stream_ticker("BTCUSDT"):
    print(f"Price: {update['price']}")
    print(f"Volume: {update['volume']}")
    print(f"Change: {update['change_24h']}%")

# Automatically handles:
# - WebSocket connection
# - Ping/pong keepalive
# - Automatic reconnection
# - Error recovery
# - Message parsing
# - 99.9% uptime guarantee

# ❌ BAD: Multiple WebSocket connections
import asyncio
import websockets

async def subscribe_symbol(symbol):
    url = f"wss://stream.binance.com:9443/ws/{symbol.lower()}@ticker"
    async with websockets.connect(url) as ws:
        async for message in ws:
            # Process message
            pass

# Subscribe to 100 symbols
symbols = ["BTCUSDT", "ETHUSDT", ...]  # 100 symbols
tasks = [subscribe_symbol(s) for s in symbols]
await asyncio.gather(*tasks)

# Problems:
# - 100 WebSocket connections (resource intensive)
# - Connection limit issues
# - Difficult to manage
# - High memory usage
# - Complex error handling

# ✅ GOOD: Single multiplexed stream
from stockapi import BinanceParser

parser = BinanceParser()

# Single WebSocket, multiple symbols
symbols = ["BTCUSDT", "ETHUSDT", "BNBUSDT", ...]  # 100+ symbols

for update in parser.stream_tickers(symbols):
    symbol = update['symbol']
    price = update['price']
    print(f"{symbol}: ${price}")

# Single WebSocket connection handles all symbols
# Automatic message routing
# Memory efficient
# Easy error recovery

# ❌ BAD: Repeated full snapshots
import requests

while True:
    # Fetch full order book (1000 levels)
    response = requests.get(
        "https://api.binance.com/api/v3/depth",
        params={"symbol": "BTCUSDT", "limit": 1000}
    )
    orderbook = response.json()

    # Process full orderbook every time
    analyze_orderbook(orderbook)
    time.sleep(0.1)

# Problems:
# - Massive bandwidth waste (full book every 100ms)
# - High latency (500ms+)
# - Rate limited
# - Inefficient processing

# ✅ GOOD: Incremental order book updates
from stockapi import BinanceParser

parser = BinanceParser()

# Real-time order book with incremental updates
orderbook = parser.stream_orderbook("BTCUSDT", depth=100)

for update in orderbook:
    if update['type'] == 'snapshot':
        # Initial full snapshot
        bids = update['bids']  # [[price, quantity], ...]
        asks = update['asks']
    else:
        # Incremental update (only changes)
        for bid in update['bids']:
            price, quantity = bid
            if quantity == 0:
                # Remove level
                remove_bid_level(price)
            else:
                # Update level
                update_bid_level(price, quantity)

# Minimal bandwidth (only changes)
# Sub-100ms updates
# Automatic snapshot recovery
# Guaranteed consistency

# ❌ BAD: Manual multi-exchange WebSockets
import asyncio

async def binance_stream():
    # Binance-specific WebSocket logic
    pass

async def coinbase_stream():
    # Coinbase-specific WebSocket logic
    pass

async def kraken_stream():
    # Kraken-specific WebSocket logic
    pass

# Each exchange has different:
# - WebSocket URL format
# - Authentication method
# - Message format
# - Reconnection logic
# - Rate limits

# Result: 500+ lines of integration code per exchange

# ✅ GOOD: Unified multi-exchange streaming
from stockapi import BinanceParser, CoinbaseParser, KrakenParser

# Same interface across all exchanges
parsers = {
    'binance': BinanceParser(),
    'coinbase': CoinbaseParser(),
    'kraken': KrakenParser(),
}

async def aggregate_streams(symbol):
    streams = [
        parser.stream_ticker(symbol)
        for parser in parsers.values()
    ]

    async for exchange, update in combine_streams(streams):
        print(f"{exchange}: ${update['price']}")

# Unified interface
# Same data format
# Automatic normalization
# Built-in arbitrage detection

# ✅ Production-ready stream with resilience
from stockapi import BinanceParser

parser = BinanceParser(
    reconnect_attempts=float('inf'),  # Never give up
    reconnect_delay=1.0,               # 1s between attempts
    ping_interval=20,                  # Keepalive every 20s
    ping_timeout=10,                   # 10s ping timeout
)

# Handles all failure scenarios:
# - Network interruptions
# - Exchange disconnections
# - API rate limits
# - Message corruption
# - Timeout errors

for update in parser.stream_ticker("BTCUSDT"):
    # Will automatically recover from any error
    process_update(update)

# ✅ Handle burst traffic without data loss
from stockapi import BinanceParser

parser = BinanceParser(
    buffer_size=10000,     # Buffer up to 10k messages
    buffer_strategy='drop_oldest',  # Drop old on overflow
)

# During high volatility:
# - Messages buffered during processing
# - No data loss up to buffer limit
# - Configurable overflow strategy
# - Memory-safe operation

# ✅ Track end-to-end latency
from stockapi import BinanceParser
import time

parser = BinanceParser()

for update in parser.stream_ticker("BTCUSDT"):
    # Exchange timestamp
    exchange_time = update['timestamp']

    # Local receipt time
    local_time = time.time() * 1000

    # Calculate latency
    latency = local_time - exchange_time

    print(f"Latency: {latency:.2f}ms")

    # Typical results:
    # - Binance: 20-50ms
    # - Coinbase: 30-60ms
    # - NYSE: 50-100ms
    # StockAPI adds <10ms overhead

# ✅ Production-ready trading bot in 30 lines
from stockapi import BinanceParser, CoinbaseParser

class ArbitrageBot:
    def __init__(self):
        self.binance = BinanceParser()
        self.coinbase = CoinbaseParser()

    def run(self, symbol):
        # Stream from both exchanges simultaneously
        binance_stream = self.binance.stream_ticker(symbol)
        coinbase_stream = self.coinbase.stream_ticker(symbol)

        binance_price = None
        coinbase_price = None

        while True:
            # Get latest from both (non-blocking)
            binance_price = next(binance_stream, binance_price)
            coinbase_price = next(coinbase_stream, coinbase_price)

            if binance_price and coinbase_price:
                spread = abs(
                    binance_price['price'] - coinbase_price['price']
                )

                if spread > 10:  # $10 arbitrage opportunity
                    self.execute_arbitrage(
                        binance_price,
                        coinbase_price
                    )

bot = ArbitrageBot()
bot.run("BTCUSDT")

# Real-time arbitrage detection
# Sub-100ms latency
# 99.9% uptime
# Production-ready

# ✅ GOOD: Randomized realistic fingerprints
from stockapi import BinanceParser

parser = BinanceParser(
    fingerprint_rotation=True,  # Rotates every request
    realistic_browser=True,      # Mimics real Chrome/Firefox
    canvas_randomization=True    # Unique canvas fingerprints
)

data = parser.get_ticker("BTCUSDT")
# Success rate: 99.9%

# ❌ BAD: Single datacenter proxy
import requests
proxies = {"http": "http://datacenter-proxy:8080"}
response = requests.get("https://binance.com", proxies=proxies)
# Result: Blocked in 3 requests

# ✅ GOOD: Residential proxy rotation
from stockapi import BinanceParser

parser = BinanceParser(
    proxy_type="residential",     # Real ISP IPs
    proxy_rotation="per_request", # Never reuse
    geo_targeting="US",           # Location matching
)

# Automatically handles proxy rotation
tickers = parser.get_all_tickers()
# Success rate: 99.9%

# ❌ BAD: Robotic request pattern
for i in range(1000):
    data = requests.get("https://api.binance.com/ticker")
    time.sleep(1)  # Constant 1s delay = bot

# ✅ GOOD: Natural request timing
import random
from stockapi import BinanceParser

parser = BinanceParser(
    delay_range=(0.5, 3.0),      # Random delays
    burst_protection=True,        # Prevents patterns
    request_jitter=True,          # Adds natural variance
)

# Automatically applies human-like timing
for symbol in symbols:
    ticker = parser.get_ticker(symbol)
    # Random delay: 0.5-3.0 seconds with jitter

# ❌ BAD: Missing or incorrect headers
headers = {
    "User-Agent": "Python-Requests/2.28.0"  # Instant block
}

# ✅ GOOD: Complete realistic header set
from stockapi import BinanceParser

parser = BinanceParser()
# Auto-generates realistic headers:
# {
#   "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
#   "Accept": "text/html,application/xhtml+xml...",
#   "Accept-Language": "en-US,en;q=0.9",
#   "Accept-Encoding": "gzip, deflate, br",
#   "DNT": "1",
#   "Connection": "keep-alive",
#   "Upgrade-Insecure-Requests": "1",
#   "Sec-Fetch-Dest": "document",
#   "Sec-Fetch-Mode": "navigate",
#   "Sec-Fetch-Site": "none",
#   "Cache-Control": "max-age=0"
# }

# ❌ BAD: Static HTML scraping
import requests
from bs4 import BeautifulSoup

html = requests.get("https://exchange.com/chart").text
soup = BeautifulSoup(html, 'html.parser')
data = soup.find("div", class_="price")
# Result: Empty (JavaScript required)

# ✅ GOOD: Full browser rendering
from stockapi import CoinbaseParser

parser = CoinbaseParser(
    javascript_enabled=True,    # Executes JS
    wait_for_content=True,      # Waits for AJAX
    stealth_mode=True           # Hides automation
)

price = parser.get_spot_price("BTC-USD")
# Renders JavaScript, handles AJAX, avoids detection

# ❌ BAD: New session every request
for ticker in tickers:
    response = requests.get(f"https://api.binance.com/ticker/{ticker}")
    # New connection, new fingerprint = suspicious

# ✅ GOOD: Maintain session state
from stockapi import BinanceParser

parser = BinanceParser(
    session_persistence=True,   # Reuse cookies
    connection_pooling=True,    # Reuse connections
)

# Same session for all requests
tickers = [parser.get_ticker(s) for s in symbols]

# ❌ DIY: 500+ lines of anti-detection code
# + Proxy management
# + Fingerprint rotation
# + Session handling
# + Error recovery
# + Monitoring

# ✅ StockAPI: 3 lines
from stockapi import BinanceParser

parser = BinanceParser()  # Anti-detection built-in
data = parser.get_ticker("BTCUSDT")