🔭 StellarScope

A minimal, hackathon-ready blockchain explorer for the Stellar Testnet
Built with plain HTML, CSS & JavaScript — zero frameworks, zero build step, zero dependencies.

---

📑 Table of Contents

• Overview
• Features
• Live Demo Data
• Folder Structure
• Prerequisites
• Clone & Setup
• Running Locally
• How to Use
• Architecture
• API Reference
• Deployment
• Upgrade Path (React)
• Troubleshooting
• License

---

🌟 Overview

StellarScope is a lightweight blockchain explorer that lets you search and inspect accounts and transactions on the Stellar Testnet. It talks directly to the public Horizon Testnet API — no backend, no API keys, no sign-up required.

Built for:

• 🏆 Hackathons — ship a working demo in minutes
• 📚 Learning — understand how Stellar's Horizon API works
• 🔍 Debugging — quickly inspect testnet accounts and transactions

---

✨ Features

Feature	Description
🔍 Smart Search	Auto-detects whether you entered an Account ID or Transaction Hash
💰 Account Balances	Displays all asset balances (XLM + custom tokens) in a clean grid
📜 Transaction History	Shows the last 5 transactions with hash, date, fee, ops, and status
📋 Transaction Detail	Full breakdown — hash, ledger, source account, fee, memo, and more
🔗 Cross-Navigation	Click any tx hash → detail view; click source account → account view
📋 Copy to Clipboard	One-click copy for account IDs
⚡ Parallel Fetching	Account info & transactions fetched simultaneously via Promise.all
🛡️ Error Handling	Invalid input, 404 not found, network errors — all with clear messages
🎨 Dark Glassmorphism UI	Animated background, gradient accents, micro-animations
📱 Fully Responsive	Works on desktop, tablet, and mobile

---

🧪 Live Demo Data & Sample Hashes

Use these real Stellar Testnet values to test the explorer immediately:

Sample Account IDs

Account ID	Description
GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR	Active testnet account with ~324M XLM balance
GBOREJYSJ4JDNB5BK4VD6SRC6AZ6GDTVDG4NZEXS2XWYSIEVW72LXYGM	Testnet account with recent smart contract activity
GAM4WCTCCLU2EDVJJ5H7U4OOITDY2PB65FGZAFMAOFD76LI7ZDCZ7ATR	Testnet account with DeFi vault interactions

Sample Transaction Hashes

Transaction Hash	Type	Fee
d8f2cb25b8d5cc68bbb1e1fd0d682a16962b77127516b6cf50c763938af7627d	Create Account	100 stroops
904c631661bdf3885ed266f8b74c71b80f7fd4fdcc4a45033852d54910d3b88e	Invoke Contract	10,085 stroops
e78654bc33e9446878e386c9c14b6192790353ea45b46305be10b9ff674991f2	Smart Contract (Deposit)	26,720 stroops
324c85b686783f2b2aa1136b16399496671b27cfc5b3c4e2a4dad15da1c70b5e	Smart Contract (Withdraw)	26,013 stroops
0f4b155a30ffb8e35b3313caa158ec8b37777425df79a617b7c2b21d9494002f	Create Account	100 stroops

💡 Tip: You can also click "Try Example Account" or "Try Example Tx" buttons in the app to auto-fill these values.

How to Find More Hashes

1. From the app itself: Search any account → see its transactions → click a hash
2. From Horizon API: Open https://horizon-testnet.stellar.org/transactions?order=desc&limit=5 and copy any "hash" field
3. From Stellar Laboratory: Visit laboratory.stellar.org → switch to Testnet

---

📁 Folder Structure

blockchain-explorer/
│
├── index.html          # Main HTML — search UI, results cards, table layout
├── styles.css          # Complete CSS design system — dark theme, animations, responsive
├── app.js              # Application logic — API calls, rendering, navigation, error handling
└── README.md           # This documentation file

That's it. No node_modules, no package.json, no build tools, no transpilation. Just 3 files that run in any browser.

---

📋 Prerequisites

Requirement	Version	Why
Web Browser	Any modern browser	Chrome, Firefox, Edge, Safari — all work
Internet Connection	—	Required to reach the Horizon Testnet API
Git (optional)	2.x+	Only needed if you're cloning from a repository
Node.js (optional)	16+	Only needed if you want to use npx serve for local dev server

Note: Since this is a pure HTML/CSS/JS project, you don't technically need anything except a browser. You can just double-click index.html to open it.

---

🚀 Clone & Setup (Step-by-Step)

Step 1: Clone the Repository

# Using HTTPS
git clone https://github.com/<your-username>/blockchain-explorer.git

# Using SSH
git clone git@github.com:<your-username>/blockchain-explorer.git

Step 2: Navigate Into the Project

cd blockchain-explorer

Step 3: Verify the Files

# On Windows (PowerShell)
dir

# On macOS/Linux
ls -la

You should see:

index.html
styles.css
app.js
README.md

Step 4: Open in a Code Editor (Optional)

# Open in VS Code
code .

---

💻 Running Locally

Option 1: Direct Open (Simplest)

Just double-click index.html or run:

# Windows
start index.html

# macOS
open index.html

# Linux
xdg-open index.html

⚠️ This works for exploring, but some browsers may restrict fetch calls from file:// protocol. If you see CORS errors, use Option 2 or 3.

Option 2: VS Code Live Server (Recommended for Development)

1. Install the Live Server extension in VS Code
2. Right-click index.html → "Open with Live Server"
3. Browser opens at http://127.0.0.1:5500
4. Auto-reloads on every file save ✨

Option 3: Node.js serve (One-liner)

npx -y serve . -l 3000

Open: http://localhost:3000

Option 4: Python HTTP Server

# Python 3
python -m http.server 8080

# Python 2
python -m SimpleHTTPServer 8080

Open: http://localhost:8080

Option 5: PHP Built-in Server

php -S localhost:8080

---

🎯 How to Use

Search by Account ID

1. Open StellarScope in your browser
2. Paste a Stellar account ID into the search bar (starts with G, 56 characters)

   GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR
   

3. Press Enter or click Search
4. You'll see:
   • Account Overview — Account ID (copyable), sequence number, account type badge
   • Balances — All assets held by the account (XLM and any custom tokens)
   • Recent Transactions — Last 5 transactions in a table

Search by Transaction Hash

1. Paste a 64-character hex transaction hash into the search bar

   d8f2cb25b8d5cc68bbb1e1fd0d682a16962b77127516b6cf50c763938af7627d
   

2. Press Enter or click Search
3. You'll see:
   • Transaction Detail — Hash, ledger number, timestamp, source account, fee, memo, operation count, success/fail status

Navigate Between Views

• Click a transaction hash in the Recent Transactions table → loads that transaction's detail view
• Click the source account in a transaction detail → loads that account's overview
• The search bar updates automatically, so you can always see what you're viewing

Use Quick-Fill Buttons

• "Try Example Account" → fills the search bar with a real testnet account ID
• "Try Example Tx" → fetches the latest transaction hash from the testnet and fills it in

---

🏗 Architecture

┌─────────────────────────────────────────────────────┐
│                    index.html                       │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Header   │  │  Search Bar  │  │  Error Banner│  │
│  └──────────┘  └──────────────┘  └──────────────┘  │
│  ┌──────────────────────────────────────────────┐   │
│  │              Results Container                │   │
│  │  ┌──────────────┐  ┌─────────────────────┐   │   │
│  │  │ Account Card  │  │ Transaction Detail  │   │   │
│  │  │ + Balances    │  │ (shown for tx hash) │   │   │
│  │  └──────────────┘  └─────────────────────┘   │   │
│  │  ┌──────────────────────────────────────┐    │   │
│  │  │     Recent Transactions Table         │    │   │
│  │  └──────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
         │                      │
         ▼                      ▼
┌─────────────┐        ┌──────────────┐
│  styles.css  │        │    app.js     │
│              │        │              │
│ • CSS vars   │        │ • detectType │
│ • Dark theme │        │ • fetchAPI   │
│ • Animations │        │ • render()   │
│ • Responsive │        │ • errorMgmt  │
└─────────────┘        └──────┬───────┘
                               │
                               ▼
                  ┌─────────────────────────┐
                  │  Stellar Horizon API     │
                  │  (Testnet)               │
                  │                         │
                  │  GET /accounts/{id}      │
                  │  GET /accounts/{id}/txs  │
                  │  GET /transactions/{hash}│
                  └─────────────────────────┘

Data Flow

1. User inputs account ID or tx hash → handleSearch() triggers
2. Input detection — regex determines if it's an account (G + 55 base32 chars) or tx hash (64 hex chars)
3. API call — fetch() to Horizon Testnet (https://horizon-testnet.stellar.org)
4. Parallel fetch — For accounts, balances and transactions are fetched simultaneously via Promise.all
5. DOM render — Results are injected into pre-built HTML templates
6. Navigation — Clicking hashes/accounts triggers new searches (single-page feel)

---

🌐 API Reference

All API calls are made to the Stellar Horizon Testnet — no authentication or API keys required.

Base URL: https://horizon-testnet.stellar.org

Endpoint	Method	Description	Example
/accounts/{account_id}	GET	Get account details, balances, signers, flags	Try it →
/accounts/{account_id}/transactions	GET	Get transactions for an account	Try it →
/transactions/{tx_hash}	GET	Get a single transaction by hash	Try it →
/transactions	GET	List all recent transactions	Try it →

Query Parameters

Parameter	Values	Description
order	asc, desc	Sort order (default: asc)
limit	1–200	Number of records to return (default: 10)
cursor	paging token	For pagination through results

Response Format

All responses are JSON. Key fields used by StellarScope:

Account Response:

{
  "account_id": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
  "sequence": "695784702202",
  "subentry_count": 0,
  "balances": [
    {
      "balance": "324474672.1508013",
      "asset_type": "native"
    }
  ]
}

Transaction Response:

{
  "hash": "d8f2cb25b8d5cc68bbb1e1fd0d682a16962b77127516b6cf50c763938af7627d",
  "successful": true,
  "ledger": 2199888,
  "created_at": "2026-04-24T04:35:45Z",
  "source_account": "GASER6SB6D6OIMEY4FSMS35ZN3AF6Z7TAWSVMQZFCGIEMGHCVQCZ5Y4C",
  "fee_charged": "100",
  "max_fee": "1000000",
  "operation_count": 1,
  "memo_type": "none"
}

📖 Full API Docs: developers.stellar.org/api/horizon

---

🚢 Deployment

Option 1: GitHub Pages (Free — 2 minutes)

# 1. Initialize git (if not already)
git init
git add .
git commit -m "Initial commit: StellarScope explorer"

# 2. Create a GitHub repository (via github.com or CLI)
gh repo create blockchain-explorer --public --source=. --push

# 3. Enable GitHub Pages
#    Go to: Repository → Settings → Pages
#    Source: "Deploy from a branch"
#    Branch: main → / (root)
#    Click Save

# 4. Your site is live at:
#    https://<your-username>.github.io/blockchain-explorer/

Option 2: Netlify (Free — 1 minute, No Git Required)

1. Go to app.netlify.com
2. Drag and drop the blockchain-explorer folder onto the page
3. Done! Netlify gives you a URL instantly (e.g., https://starlit-churros-abc123.netlify.app)

Option 3: Netlify CLI

# Install Netlify CLI
npm install -g netlify-cli

# Deploy (one-liner)
netlify deploy --prod --dir=.

Option 4: Vercel (Free)

npx -y vercel --prod

Option 5: Cloudflare Pages (Free)

1. Push to GitHub
2. Go to dash.cloudflare.com → Pages → Create a project
3. Connect your GitHub repo → Deploy

---

🔄 Upgrade Path — React Version

When you're ready to scale beyond the MVP:

Step 1: Initialize React + Vite

npx -y create-vite@latest stellar-explorer-react -- --template react
cd stellar-explorer-react
npm install

Step 2: Install Stellar SDK

npm install @stellar/stellar-sdk

Step 3: Recommended Project Structure

src/
├── components/
│   ├── SearchBar.jsx          # Search input with auto-detection
│   ├── AccountCard.jsx        # Account overview + balances
│   ├── BalanceGrid.jsx        # Grid of balance cards
│   ├── TransactionTable.jsx   # Table of recent transactions
│   ├── TransactionDetail.jsx  # Detailed single transaction view
│   ├── ErrorBanner.jsx        # Error display component
│   └── LoadingSpinner.jsx     # Loading state
├── hooks/
│   ├── useStellar.js          # Custom hook for Horizon API
│   └── useDebounce.js         # Debounce search input
├── services/
│   └── horizon.js             # API abstraction layer
├── utils/
│   └── format.js              # Number, date, hash formatters
├── App.jsx                    # Main app with routing
├── App.css                    # Styles (port from styles.css)
└── main.jsx                   # Entry point

Step 4: Key Upgrades to Consider

Feature	Library	Purpose
Routing	react-router-dom	/account/:id and /tx/:hash URL routes
Data Caching	@tanstack/react-query	Cache API responses, auto-refresh
Stellar SDK	@stellar/stellar-sdk	Proper XDR parsing, signing, account creation
Real-time	EventSource / SSE	Subscribe to ledger streams for live updates
Wallet	Freighter / Albedo	Connect user's Stellar wallet
Charts	recharts	Visualize balance history, network stats
Testing	vitest + @testing-library/react	Unit and integration tests

---

🔧 Troubleshooting

"Account not found" error

• Cause: The account doesn't exist on Testnet. This explorer only works with the Stellar Testnet.
• Fix: Create a testnet account at laboratory.stellar.org using the Friendbot faucet.

"Invalid input" error

• Account IDs must start with G and be exactly 56 characters (base32 encoded)
• Transaction hashes must be exactly 64 hexadecimal characters (a-f, 0-9)
• Make sure there are no spaces or extra characters

CORS errors when opening index.html directly

• Some browsers block fetch() from file:// protocol
• Fix: Use a local server (see Running Locally options)

"Network error" message

• Check your internet connection
• The Horizon Testnet API might be temporarily down — check status.stellar.org
• Try refreshing and searching again

Transactions not loading

• Some accounts may have zero transactions (newly created accounts with no activity)
• Try the example account: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR

---

🤝 Contributing

1. Fork the repository
2. Create your branch: git checkout -b feature/amazing-feature
3. Commit: git commit -m 'Add amazing feature'
4. Push: git push origin feature/amazing-feature
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ☕ for Stellar · Powered by Horizon Testnet API