icp-multi-exchange-price-oracle

ICP Multi-Exchange Price Oracle Canister

Multi-Venue Spot Market Data & Candlestick Oracle for the Internet Computer

---

1. WHAT IS THIS?

The ICP Multi-Exchange Price Oracle Canister is a production-ready Rust smart contract for the Internet Computer (ICP). It fetches, validates, normalizes, and caches real-time and historical candlestick (OHLCV) market data from three Tier-1 exchanges (Binance, Coinbase, OKX) via deterministic HTTPS outcalls, serving queries to frontend clients with zero cycle fees.

2. WHO IS IT FOR?

• Web3 DeFi & DEX Developers: Needing validated multi-timeframe OHLCV bars and multi-exchange spread data for interactive charting and on-chain trade logic.
• DAO Treasuries: Requiring automated asset valuation without recurring third-party oracle subscription fees.
• Canister Architects: Requiring a secure reference implementation for rate-limited, single-flight HTTPS outcalls with cycle reserve protection.

3. WHAT PROBLEM DOES IT SOLVE?

The official DFINITY Exchange Rate Canister (XRC) provides single spot price cross-rates but has structural limitations for interactive applications:

1. Cycles Attached on Query: XRC requires the caller to attach cycles to every query call, making direct, unauthenticated frontend web client queries impossible.
2. No Candlestick (OHLCV) Series: XRC returns a single spot price; it does not aggregate, normalize, or cache multi-timeframe OHLCV series required for charting.
3. Black-Box Aggregation: XRC hides individual exchange order-book/candle provenance.
4. Bankruptcy Risk: Naive outcall loops can rapidly exhaust a canister cycle balance during upstream network disruptions.

4. WHY PAY FOR IT INSTEAD OF BUILDING IT?

• Free Client Queries: An in-canister RAM cache serves authenticated query calls (cached_market_data) to browser frontends at zero cycle cost to the user.
• Full OHLCV Candlestick Parsing: Parses and normalizes native candlestick streams across M1, M5, M15, H1, H4, D1, W1 timeframes.
• Multi-Exchange Transparency: Queries Binance, Coinbase, and OKX concurrently, returning validated series and provenance alongside explicit failure tracking for each venue.
• 100 Billion Cycle Reserve Protection: Automatically aborts outcalls if canister reserves drop below 100B cycles (~0.1 TC), preventing canister freeze.
• Single-Flight Coalescing: Concurrent requests for the same asset/timeframe share an in-flight promise to eliminate duplicate outcall expenses.

5. WHAT IS VERIFIED?

• 10 / 10 Automated Rust Unit Tests Passed: OHLCV validation, duplicate timestamp rejection, negative/zero price rejection, case-insensitive asset normalization, boundary calculation, and exchange parser error handling.
• WASM Compilation: Compiles to optimized wasm32-unknown-unknown canister binary.
• Candid Interface: Fully verified Candid contract (candid/market_oracle.did).

6. HOW DO I RUN IT?

# 1. Run unit tests
cargo test --manifest-path Cargo.toml

# 2. Build optimized canister WASM
cargo build --manifest-path Cargo.toml --target wasm32-unknown-unknown --release

# 3. Deploy locally with dfx
dfx start --background
dfx deploy market_oracle
dfx canister call market_oracle refresh_market_data '(record { asset = "BTC"; timeframe = variant { H1 }; limit = 20 })'