A high-performance, async Rust client library and data pipeline for financial market data. Built with a modular workspace architecture, it integrates with AlphaVantage, CoinGecko, CoinMarketCap, and other data sources, featuring TimescaleDB storage, advanced caching, and comprehensive cryptocurrency coverage.
Status: Under active development.
- Multi-source data integration — AlphaVantage, CoinGecko, CoinMarketCap, CoinPaprika, CoinCap, SosoValue, GitHub
- Async architecture — Built on Tokio with full concurrency support
- Two front-ends — A Clap-based CLI (
av) for ETL and queries, and an Actix-web UI (av-web) for browsing the data - Response caching — Minimizes API calls and costs
- TimescaleDB — Optimized time-series storage with hypertables
- Comprehensive crypto — 10,000+ coins with metadata, social metrics, and market data from multiple providers
- ETL process tracking — Monitoring with automatic retry mechanisms
- Rate limiting — Intelligent limiting based on API tier (75/min free, 600/min premium)
| Category | Details |
|---|---|
| Equities | Stocks, ETFs, mutual funds, bonds with company fundamentals |
| Cryptocurrency | Metadata, prices (intraday + daily), market pairs, social metrics, news |
| News & Sentiment | NLP-powered sentiment analysis with topic categorization |
| Market Analytics | Top gainers/losers tracking |
alphavantage/
├── crates/
│ ├── av-core/ # Core types, traits, and configuration
│ ├── av-client/ # AlphaVantage API HTTP client
│ ├── av-models/ # Data models for API responses
│ ├── av-database/
│ │ └── postgres/ # PostgreSQL/TimescaleDB via Diesel ORM
│ ├── av-loaders/ # ETL data loaders (equities, news, prices)
│ ├── crypto-loaders/ # Cryptocurrency-specific loaders and providers
│ ├── av-api/ # Unified, feature-gated facade over the libraries
│ ├── av-cli/ # Command-line interface (binary: av)
│ └── av-web/ # Actix-web UI (binary: av-web)
├── migrations/ # Database migrations
├── timescale_setup/ # TimescaleDB Docker setup
└── data/ # CSV data files for symbol imports
Core types, traits, error handling, and configuration shared across the workspace. Includes type-safe representations for intervals, exchanges, sectors, security types, currencies, and crypto symbols with FromStr implementations.
Pure async HTTP client for AlphaVantage API endpoints — time series, fundamentals, news sentiment, forex, and cryptocurrency. No database dependencies.
Serde-based data models for all API response types.
PostgreSQL/TimescaleDB integration via Diesel 2.3 ORM with diesel-async and BB8 connection pooling. Provides repository traits for all entity types with a unified cache layer.
ETL data loaders for equities, intraday/daily prices, company overviews, news with sentiment analysis, and top market movers. Includes batch processing, CSV import, and process state tracking.
Cryptocurrency-specific data loaders with multi-provider support:
- Providers: CoinGecko, CoinMarketCap, CoinPaprika, CoinCap, SosoValue
- Loaders: Symbol discovery, metadata, details, social metrics
- Mapping: Cross-provider symbol mapping and discovery service
Unified facade over the library crates with Cargo feature flags so downstream code can take only the slice it needs:
| Feature | Pulls in | Use when… |
|---|---|---|
models |
av-models |
Deserialising cached JSON, no I/O |
client |
+ av-client (default) |
Calling Alpha Vantage HTTP endpoints |
database |
+ av-database-postgres + diesel |
Repository / query access |
loaders |
+ av-loaders (implies client+database) |
Running ETL |
full |
Everything | Used by the binaries |
Command-line interface (av binary) built with Clap. See CLI commands below.
Actix-web UI served on 0.0.0.0:8080 (override with AV_WEB_PORT). Uses Tera templates from crates/av-web/templates/ and static assets from crates/av-web/static/. The Alpha Vantage client is optional at startup — if ALPHA_VANTAGE_API_KEY is missing the server still serves read-only pages (/search, /news, /movers, /sources, /chart) and only /load is disabled.
Routes:
| Path | Method | Purpose |
|---|---|---|
/ |
GET | Search form |
/search |
GET | Symbol search results |
/news |
GET | Sentiment-tagged news for a symbol |
/movers |
GET | Top gainers / losers |
/sources |
GET | News-source aggregation |
/chart |
GET | Time-series chart for a security ID |
/load |
GET/POST | ETL trigger (disabled without API key) |
av load securities # Load equity symbols from CSV
av load overviews # Load company overview data
av load intraday # Load intraday price data
av load daily # Load daily price data
av load news # Load news with sentiment
av load top-movers # Load market movers
av load crypto # Load crypto data
av load crypto-overview # Load crypto overviews
av load crypto-markets # Load exchange/market pair data
av load crypto-mapping # Load symbol mappings
av load crypto-metadata # Load crypto metadata
av load crypto-news # Load crypto news
av load crypto-intraday # Load crypto intraday prices
av load crypto-details # Load crypto details
av load crypto-prices # Load crypto prices
av sync market # Sync equity market data
av sync crypto # Sync cryptocurrency data
av query symbol # Query a specific symbol
av query list-symbols # List all symbols
av update stats # View database statistics
PostgreSQL with TimescaleDB extensions. Key table groups:
Core: symbols, overviews, overviewexts, equity_details, intradayprices, summaryprices, topstats
Cryptocurrency: crypto_api_map, crypto_metadata, crypto_overview_basic, crypto_overview_metrics, crypto_technical, crypto_social, crypto_markets
News & Sentiment: newsoverviews, feeds, articles, article_media, article_quotes, article_symbols, article_tags, article_translations, sources, authors, authormaps, tickersentiments, topicmaps, topicrefs
System: api_response_cache, procstates, proctypes, states
- Rust 1.92+ (edition 2021)
- Docker & Docker Compose
- PostgreSQL client tools
- AlphaVantage API key (get one here)
-
Clone the repository:
git clone https://github.com/dbrowne/alphavantage.git cd alphavantage -
Start TimescaleDB:
cd timescale_setup make up -
Configure environment (do this before running
diesel setup— it readsDATABASE_URLfrom.env):cp DOT_env_EXAMPLE .env # Edit .env with your API keys and database URL -
Run database migrations:
cd crates/av-database/postgres diesel setup diesel migration runThe Diesel CLI is required:
cargo install diesel_cli --no-default-features --features postgres. -
Verify the database connection:
PGPASSWORD=dev_pw psql -U ts_user -h localhost -p 6433 -d sec_master -c '\dt' -
Build:
cargo build --release
./target/release/av --help
# or, during development:
cargo run -p av-cli -- --helpcargo run -p av-web
# Server listens on http://0.0.0.0:8080 by default.
AV_WEB_PORT=9090 cargo run -p av-web # override the portThe web UI loads its Tera templates relative to the av-web crate (via CARGO_MANIFEST_DIR), so when you deploy the release binary keep templates/ and static/ next to it — or run from the source tree.
Mirrors the GitHub Actions workflow:
cargo build --verbose
cargo test --verbose
cargo fmt -- --check # CI fails on unformatted codePer-crate tests:
cargo test -p av-core
cargo test -p av-web -- --nocaptureNote: Loose integration files under the workspace-root
tests/directory are not picked up bycargo test(no parentCargo.toml). They need to live under a crate'stests/subdirectory to run.
See CLAUDE.md for a deeper architectural tour aimed at AI assistants and new contributors.
| Crate | Version | Purpose |
|---|---|---|
| tokio | 1.46 | Async runtime |
| actix-web | 4.x | Web framework (av-web) |
| tera | latest | HTML templating (av-web) |
| diesel | 2.3 | ORM (PostgreSQL) |
| diesel-async | 0.8 | Async Diesel with BB8 pooling |
| reqwest | 0.12 | HTTP client |
| clap | 4.4 | CLI framework |
| serde | 1.0 | Serialization |
| chrono | 0.4 | Date/time handling |
| bigdecimal | 0.4 | Financial precision |
| tracing | 0.1 | Structured logging |
| thiserror | 2.0 | Error types |
MIT
