A fully functional Bitcoin marketplace for Runes, Ordinals, and BRC-20 tokens. Built with React + Vite, real Bitcoin wallet integration, and on-chain transaction construction.
- Explore — Browse top collections, trending runes, and notable listings
- Runes — View all runes with real-time prices, sparklines, and market data
- Ordinals — Browse inscriptions with sat rarity filtering
- BRC-20 — Token listings with mint progress tracking
- Activity Feed — Live mempool activity via WebSocket (mempool.space)
- Mint Runes — Mint existing runes or etch brand-new ones on Bitcoin
- Upload Collection — Inscribe entire collections with parent/child model
- Wallet Connection — Xverse, Unisat, Leather, OKX with real PSBT signing
- PSBT Trading — Real marketplace listings using partially-signed Bitcoin transactions
cd "Magic Runes"
npm install
npm run dev # → http://localhost:3000Copy .env.example to .env and fill in any keys you need:
cp .env.example .env| Variable | Purpose | Required? |
|---|---|---|
VITE_PINATA_JWT |
IPFS uploads via Pinata | No — local fallback works |
VITE_NFT_STORAGE_KEY |
IPFS uploads via nft.storage | No — alternative to Pinata |
No API keys are required for development. The app uses free public endpoints:
- mempool.space — fees, UTXOs, broadcasting
- Hiro Ordinals API — inscription data
- BestInSlot API — rune lookups (free tier)
src/
├── App.jsx # Root router
├── main.jsx # Entry + WalletProvider
├── context/
│ └── WalletContext.jsx # Global wallet state
├── services/
│ ├── inscription.js # Ordinal inscription PSBT construction
│ ├── runes.js # Runestone encoding + etch/mint PSBTs
│ ├── trading.js # Marketplace listing/buying PSBTs
│ ├── mempool.js # WebSocket + REST (mempool.space)
│ ├── storage.js # IPFS upload (Pinata / nft.storage)
│ └── wallet.js # Wallet connection normalization
├── utils/
│ ├── api.js # API helpers + mock data generators
│ └── wallet.js # Wallet connect/sign/balance
├── pages/
│ ├── ExplorePage.jsx # Homepage with collections + trending
│ ├── RunesPage.jsx # Runes listing table
│ ├── RuneDetail.jsx # Single rune with swap widget
│ ├── OrdinalsPage.jsx # Inscription browser
│ ├── BRC20Page.jsx # BRC-20 tokens listing
│ ├── BRC20Detail.jsx # Single BRC-20 with trade widget
│ ├── MempoolPage.jsx # Live activity feed
│ ├── MintRunesPage.jsx # Etch & mint runes
│ └── UploadCollectionPage.jsx # Collection inscription wizard
├── components/
│ ├── layout/ # Navbar, Footer
│ ├── modals/ # WalletModal, CreateCollectionModal
│ ├── collections/ # Cards, rows, detail views
│ ├── shared/ # Badge, StatBox, FilterPills, Sparkline, etc.
│ └── icons/ # SVG icon components
├── data/ # Mock data (collections, runes, brc20, ordinals)
└── styles/
└── global.css # Animations, scrollbar, dark theme
Each wallet browser extension exposes a JavaScript API on window. The app detects available wallets and connects through their native APIs, normalizing the interface to always provide { address, ordinalsAddress, publicKey }.
All Bitcoin transactions use Partially Signed Bitcoin Transactions (PSBTs):
- Inscriptions — Taproot commit/reveal pattern with OP_FALSE/OP_IF envelope
- Rune Etching — OP_RETURN with Runestone payload (LEB128 encoded tags)
- Rune Minting — OP_RETURN with mint tag referencing the etching block
- Marketplace — SIGHASH_SINGLE|ANYONECANPAY for trustless swaps
Connects to mempool.space WebSocket for real-time new transactions, supplemented by polling the Hiro API for ordinals-specific activity.
| Capability | What's Needed |
|---|---|
| Real trading | Backend order book (listings DB + API) |
| Collection indexing | Ord indexer or BestInSlot/Hiro subscription |
| IPFS uploads | Pinata JWT or nft.storage key in .env |
| Custom domain | Standard Vite build + hosting (Vercel, etc.) |
The frontend is fully functional — wallet connections, PSBT construction, and broadcasting all work on mainnet. The main production dependency is a backend for storing and serving marketplace listings.
- React 18 + Vite 6 — Fast dev experience
- bitcoinjs-lib — PSBT construction and Bitcoin scripting
- @noble/hashes + tiny-secp256k1 — Cryptographic primitives
- sats-connect — Xverse wallet SDK
- mempool.space — Free Bitcoin API (fees, UTXOs, broadcasting, WebSocket)
npm run dev # Dev server on :3000
npm run build # Production build
npm run preview # Preview production build