Vikuna

Lightweight Python library for Alpaca paper trading, portfolio inspection, equity and options market data access, and DuckDB-backed bar caching. The package is structured so trading, account, market data, options, and storage can be used independently.

Features

• Place and manage Alpaca paper-trading orders
• Submit advanced equity orders including trailing stop, bracket, OCO, and OTO
• Read account snapshots and open positions
• Fetch historical bars and latest quotes
• Discover option contracts, read option quotes/bars, and place single-leg option orders
• Submit multi-leg option orders and inspect option chain snapshots with greeks
• Validate invalid order combinations before hitting the Alpaca API
• Cache bars locally in DuckDB for incremental sync workflows
• Work with typed dataclasses and Polars dataframes

Installation

Use the checked-in uv environment when possible:

uv sync --dev

Fallback:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Configuration

Create a local .env file from .env.example:

ALPACA_API_KEY=your_api_key_here
ALPACA_SECRET_KEY=your_secret_key_here
ALPACA_BASE_URL=https://paper-api.alpaca.markets
DB_PATH=./data/market_data.duckdb

Use paper-trading credentials for development.

Quick Start

from datetime import datetime, timedelta, timezone
from vikuna import (
    AlpacaAccountClient,
    AlpacaMarketData,
    AlpacaOptionsClient,
    MarketDatabase,
    MultiLegOrderRequest,
    OptionOrderLeg,
)

account_client = AlpacaAccountClient()
account = account_client.get_account()
print(account.portfolio_value)

market_data = AlpacaMarketData()
db = MarketDatabase()

end = datetime.now(timezone.utc)
start = end - timedelta(days=30)
bars = market_data.get_bars("AAPL", "1d", start, end)
db.save_bars(bars)

latest = db.get_latest_timestamp("AAPL", "1d")
print(latest)
db.close()

options = AlpacaOptionsClient()
contracts = options.list_contracts("AAPL", contract_type="call", limit=5)
print(contracts)

chain = options.get_chain_snapshot("AAPL", contract_type="call")
print(chain.select(["symbol", "bid_price", "ask_price", "delta", "theta"]))

db.save_option_bars(options.get_bars("AAPL240621C00190000", "1d", start, end))
db.save_option_snapshots(options.list_chain_snapshots("AAPL", contract_type="call"))

spread = MultiLegOrderRequest(
    qty=1,
    order_type="limit",
    limit_price=1.25,
    legs=[
        OptionOrderLeg("AAPL240621C00190000", "buy", "buy_to_open"),
        OptionOrderLeg("AAPL240621C00200000", "sell", "sell_to_open"),
    ],
)
# options.submit_multileg_order(spread)

API Overview

• AlpacaTradingClient: buy, sell, cancel_order, cancel_all_orders, get_order, list_orders
• AlpacaAccountClient: get_account, get_positions, get_position, close_position, close_all_positions
• AlpacaMarketData: get_bars, get_latest_bar, get_quote
• AlpacaOptionsClient: list_contracts, get_contract, get_bars, get_latest_quote, buy, sell
• AlpacaOptionsClient: also submit_multileg_order and get_chain_snapshot
• AlpacaOptionsClient: also list_chain_snapshots for typed snapshot objects
• MarketDatabase: save_bars, load_bars, get_latest_timestamp, sync
• MarketDatabase: also save_option_bars, load_option_bars, get_latest_option_timestamp, sync_option_bars
• MarketDatabase: also save_option_snapshots, load_option_snapshots, sync_option_snapshots

Shared types exported by the package:

• Bar
• Order
• Position
• Account
• OptionContract
• OptionOrderLeg
• MultiLegOrderRequest
• OptionQuote
• OptionSnapshot
• BAR_SCHEMA

Notes

• Options support is implemented against Alpaca’s current options trading and market data APIs.
• Futures are not implemented in this library yet because Alpaca does not expose a stable futures API surface here.

Development

Run the test suite:

.venv/bin/python -m pytest tests -q

Run the local smoke example:

python main.py