Alpha Vantage

---
name: alpha-vantage
description: Use this skill when users need Alpha Vantage market data or indicators (stocks, ETFs, forex, crypto, commodities, macro, company fundamentals) via the official API. Apply it for ticker lookups, time series pulls, indicator calculations, screening/fundamental analysis, API integration code, and deployment-safe workflows requiring API key handling, throttling retries, and commercial/public-use guardrails.
---

# Alpha Vantage

## Overview

This skill provides a production-ready workflow for Alpha Vantage API usage: selecting the right endpoints, building validated requests, handling throttling/error responses, and preparing safe public/commercial deployment.

## Quick Start

1. Set API key: `export ALPHAVANTAGE_API_KEY=...`
2. For endpoint/params, read `references/api_docs.md`
3. For scriptable calls with retry/backoff, use `scripts/alpha_vantage_client.py`
4. For public deployment, follow the `Deployment Guardrails` section before release

## Workflow

1. Classify request type:
- Price bars or latest price: time series functions
- Indicators (RSI, SMA, MACD, etc.): technical indicator functions
- Company info, earnings, statements: fundamentals
- FX/Crypto/Commodities/Macro: their dedicated function families
2. Resolve mandatory parameters from `references/api_docs.md`.
3. Build request with `function=...` and `apikey=...`.
4. Parse response and branch for:
- HTTP error status
- `Error Message`
- `Note` (usually rate-limit/throttle condition)
- Empty/partial payload
5. If `Note`/throttled, retry using exponential backoff with jitter.
6. Normalize output to a stable schema before downstream use.

## Implementation Guidelines

### Authentication

- Use `ALPHAVANTAGE_API_KEY` environment variable by default.
- Never hardcode keys in source, logs, prompts, or examples.
- Mask keys in debug output (show only short prefix/suffix).

### Reliability and Rate Limits

- Treat responses containing `Note` as retriable throttle events.
- Use bounded retries with exponential backoff and jitter.
- For multi-symbol jobs, queue calls and pace to plan limits.
- Cache stable responses (fundamentals, metadata) to reduce quota burn.

### Response Validation

- Validate both transport and payload success.
- Handle string-encoded numbers safely (`float(...)`/`Decimal` as needed).
- Keep parser logic resilient to minor schema/key ordering changes.

### Data Quality

- Preserve source timestamps/time zones from payload metadata.
- Do not infer adjusted/unadjusted semantics; use explicit functions.
- Record the function and params used for reproducibility/auditability.

## Deployment Guardrails

### Public/Commercial Readiness

- Review Alpha Vantage terms before public/commercial release:
  https://www.alphavantage.co/terms_of_service/
- Ensure your usage tier and traffic profile are aligned with your plan:
  https://www.alphavantage.co/premium/
- Do not redistribute restricted content if terms disallow it.

### Security and Operations

- Store API keys in secret managers (or environment variables for local dev only).
- Add circuit-breaking and queue backpressure for upstream rate spikes.
- Instrument call counts, throttle rate, retry count, and error classes.
- Add alerting for sustained `Note` responses and non-2xx response spikes.

## Resources

### references/

- `references/api_docs.md` contains endpoint selection guidance and required parameters.

### scripts/

- `scripts/alpha_vantage_client.py` provides a reusable request wrapper with:
  - env-based auth
  - timeout and retry logic
  - throttle/error detection
  - optional compact output