๐ StellarPrice Oracle - Real-time Crypto Oracle on Stellar
Demo Video
https://drive.google.com/file/d/1dhQchLIvAp9XcbpCoD8ROnsYxg-0AewQ/view?usp=sharing
A hackathon-ready price oracle that fetches real crypto prices from DexScreener API and stores them on the Stellar blockchain.
โก Quick Start (5 minutes)
# 1. Install prerequisites
# - Node.js 18+
# - Stellar CLI: https://stellar.org/developers-blog/how-to-install-stellar-cli
# 2. Setup Stellar CLI
stellar network add --global testnet \
--rpc-url https://soroban-testnet.stellar.org:443 \
--network-passphrase "Test SDF Network ; September 2015"
# 3. Create and fund account
stellar keys generate alice --global
stellar keys fund alice --network testnet
# 4. Run setup script
chmod +x complete-setup.sh
./complete-setup.sh
# 5. Deploy and start
chmod +x quick-deploy.sh
./quick-deploy.sh
# 6. Edit .env with your Stellar secret key
# 7. Start the whole app (backend + frontend)
chmod +x start.sh
./start.sh
# 8. Visit http://localhost:3000 ๐
๐ Deployment & Setup
For a full guided setup, use the included deployment script:
chmod +x deploy-setup.sh
./deploy-setup.sh
- This script checks prerequisites, builds/contracts, updates
.env, installs dependencies, and provides one-click startup/test scripts:./start-oracle.shโ Start both backend and frontend./test-oracle.shโ Test API and frontend health./start.shโ Start the whole app (recommended)
Manual quick start:
See below or use the script above for a smoother experience.
๐ฏ What You Get
- โ Real DexScreener API data (BTC, ETH, SOL, XLM, WBTC, WETH, WSOL, etc.)
- โ Soroban contract (stores prices on-chain)
- โ Beautiful React dashboard (animated price cards, live charts)
- โ Manual data submission (perfect for demos)
- โ One-click deployment
๐๏ธ Architecture
DexScreener API โ Oracle Service โ Soroban Contract โ React Frontend
โ โ โ โ
BTC: $67K โ Format data โ Store on-chain โ Live charts
๐ Project Structure
stellar-price-oracle/
โโโ ๐ README.md
โโโ ๐ quick-deploy.sh # One-click deployment
โโโ โ๏ธ .env.example
โ
โโโ ๐ฆ contract/ # Simple Soroban Contract
โ โโโ Cargo.toml
โ โโโ src/
โ โโโ lib.rs # Minimal price oracle contract
โ
โโโ ๐ oracle-service/ # Node.js Price Fetcher
โ โโโ package.json
โ โโโ index.js # Main oracle service
โ โโโ ... # Price fetcher, Stellar client
โ
โโโ ๐จ frontend/ # React Dashboard
โ โโโ package.json
โ โโโ vite.config.ts
โ โโโ tailwind.config.js
โ โโโ src/
โ โ โโโ App.tsx # Main app
โ โ โโโ components/
โ โ โ โโโ PriceCard.tsx # Animated price cards
โ โ โ โโโ LiveChart.tsx # Real-time charts
โ โ โ โโโ NetworkStatus.tsx # Oracle health
โ โ โ โโโ SubmitData.tsx # Manual data submission
โ โ โโโ hooks/
โ โ โ โโโ useOracle.ts # Oracle data hook
โ โ โ โโโ usePrices.ts # Price data hook
โ โ โโโ services/
โ โ โ โโโ stellar.ts # Stellar integration
โ โ โ โโโ api.ts # Backend API
โ โ โโโ types/
โ โ โโโ oracle.ts # TypeScript types
โ โโโ public/
โ
โโโ ๐ docs/
โ โโโ DEMO.md # Demo script
โ โโโ DEPLOY.md # Quick deployment guide
๐ Smart Contract to App Integration Flow
1. RUST CONTRACT (contract/src/lib.rs)
โ compiles to WASM
2. WASM FILE (target/wasm32-unknown-unknown/release/price_oracle.wasm)
โ deploys to Stellar
3. CONTRACT ID (e.g., CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)
โ stored in .env
4. ORACLE SERVICE (oracle-service/index.js)
โ reads contract ID, submits prices
5. FRONTEND (frontend/src)
โ calls oracle API, displays data
๐ฆ Build & Deploy Flow
- Build Rust contract:
cd contract && cargo build --target wasm32-unknown-unknown --release - Deploy contract:
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/price_oracle.wasm --source alice --network testnet - Update
.envwith CONTRACT_ID
(or use the deployment script to automate) - Oracle service reads CONTRACT_ID and submits prices
- Frontend displays on-chain prices via the oracle API
See ../deploy-setup.sh for a full automated script.
๐ช Perfect for Hackathons
- "Live BTC price from DexScreener API" (show real data)
- "Stored on Stellar testnet" (show contract)
- "Updates every 30 seconds" (watch animation)
- "I can submit custom data" (live interaction)
- "Built in 6 hours!" (win judges)
Built with โค๏ธ for the Stellar ecosystem
๐ Simple Commands & Quick Reference
See SIMPLE_COMMANDS.md for a full list of one-liners, troubleshooting, and hackathon demo tips.
See SIMPLE_COMMANDS.md for a full list of one-liners, troubleshooting, and hackathon demo tips.
Description
Languages
Rust
56.3%
D
30.7%
TypeScript
6.8%
Shell
3.9%
JavaScript
1.8%
Other
0.4%