Historical Volatility API

A Rust REST API using Axum that computes 90-day rolling annualized volatility for Solana tokens, leveraging Birdeye price data and an in-memory cache.

---

🚀 Quick Start

1. Clone and build

   git clone <repo-url>
   cd <project-dir>
   cargo build --release

2. Configure Create a .env file in project root:

   BIRDEYE_API_KEY=your-api-key-here
   BIRDEYE_BASE_URL=https://public-api.birdeye.so/token_price/history
   APP_SERVER_PORT=3000

3. Run

   cargo run --release

   Server listens on 0.0.0.0:${APP_SERVER_PORT}.

---

🔧 Configuration

Environment Variable	Description	Required
BIRDEYE_API_KEY	API key for Birdeye price data	✅
BIRDEYE_BASE_URL	Base URL for Birdeye historical price endpoint	✅
APP_SERVER_PORT	Port for this service (e.g. 3000)	✅

---

📦 Project Structure

├── src/
│   ├── cache/
│   │   ├── mod.rs
│   │   └── volatility_cache.rs
│   ├── errors/
│   │   ├── api_error.rs
│   │   └── mod.rs
│   ├── extractors/
│   │   ├── mod.rs
│   │   └── query_extractor.rs
│   ├── routes/
│   │   ├── health_check.rs
│   │   ├── historical_volatility.rs
│   │   └── mod.rs
│   ├── utils/
│   │   ├── custom_date_serde.rs
│   │   └── mod.rs
│   ├── config.rs
│   ├── lib.rs
│   ├── main.rs
│   └── state.rs
├── tests/
│   ├── health_check/
│   │   └── main.rs
│   └── historical_volatility/
│       └── main.rs
├── .env.example
├── .gitignore
├── Cargo.toml
└── README.md

---

🔗 Endpoints

GET /historicalVolatility?tokenAddress=<address>

• Query (required):
  • tokenAddress (base-58 Solana token address)
• Success (200)

  { "historicalVolatility": 42.17 }

• Errors
  • 400 Bad Request – missing or invalid tokenAddress
  • 500 Internal Server Error – upstream failures

GET /healthCheck

• Success (200)

  { "message": "Server is running." }

---

💡 Logging & Tracing

• Built with [tracing]
• info! for startup, incoming requests
• debug! for detailed computation steps

---

🧪 Testing

• Integration tests in tests/ use wiremock to simulate Birdeye responses.
• Unit tests cover date serializer/deserializer and volatility calculations.

---

© 2025 Epicentral Labs. All rights reserved.