GitHub - emmanuelist/anchor-x: Production-ready bridge for Circle's USDCx on Stacks. Deposit USDC from Ethereum, withdraw USDCx to Stacks. Real-time transaction tracking, bi-directional transfers.

Quick Start · Features · Architecture · Demo · Docs

💫 Why AnchorX?

🎯 The Problem

Bridging assets between Ethereum and Stacks has traditionally been:

❌ Complex — Multiple steps, confusing interfaces
❌ Slow — Long wait times with no visibility
❌ Risky — Unclear transaction status
❌ Expensive — Hidden fees and poor gas optimization

✅ The AnchorX Solution

We've built the bridge experience users deserve:

✨ One-Click — Approval + bridge in single flow
⚡ 15 Minutes — Average bridge completion time
🛡️ Secure — Circle's xReserve + real-time tracking
💰 Transparent — Clear fees, gas optimization

🏆 Key Metrics

_{Transaction Success}

_{Average Completion}

_{Low Fee Structure}

_{Always Online}

📋 Table of Contents

Click to expand

💫 Why AnchorX?
🏆 Key Metrics
✨ Features
🎬 Demo
🚀 Quick Start
🏗️ Architecture
🌉 How Bridging Works
📱 Screenshots
🔐 Security
📄 Smart Contracts
🛠️ Technology Stack
📁 Project Structure
👛 Wallet Support
⌨️ Keyboard Shortcuts
🧪 Testing
🚢 Deployment
🗺️ Roadmap
🤝 Contributing
❓ FAQ
📜 License

✨ Features

🌟 Core Capabilities

⚡ Lightning Bridge

One-Click Bridging

Streamlined UX that handles USDC approval and bridge deposit in a single, seamless flow. No more confusing multi-step processes.

📊 Real-Time Tracking

Live Status Updates

Watch your transaction progress through every step — from initiation to confirmation — with block-by-block updates.

🔄 Bi-Directional

Deposit & Withdraw

Move seamlessly between Ethereum USDC and Stacks USDCx in either direction with the same intuitive interface.

💰 Dual Dashboard

Unified Portfolio View

See your complete cross-chain balance at a glance. Track USDC, USDCx, ETH, and STX all in one beautiful dashboard.

🎨 Stunning UI/UX

Premium Design

Dark mode interface with smooth animations, particle effects, and micro-interactions that make bridging a delight.

📱 Mobile First

Fully Responsive

Optimized for every screen size with touch-friendly controls and mobile wallet deep linking.

🔥 See All Features

Bridge Features

Feature	Description
🔄 Bi-Directional Bridge	Deposit USDC → USDCx and Withdraw USDCx → USDC
⚡ One-Click Flow	Approval + bridge combined into single transaction
📍 Custom Recipients	Bridge directly to any valid Stacks/Ethereum address
💵 Fee Calculator	Real-time fee estimation with gas price tracking
📊 Progress Timeline	Visual step-by-step bridge progress indicator
🔔 Notifications	Toast alerts for every transaction state change

Dashboard Features

Feature	Description
💰 Dual Balance View	USDC + USDCx displayed simultaneously
📈 Portfolio Charts	Historical balance visualization with Recharts
🔄 Live Sync	Real-time balance updates across both chains
📋 Transaction History	Complete bridge history with status tracking
🔗 Explorer Links	One-click access to Etherscan & Hiro Explorer

UX Features

Feature	Description
🎓 Guided Onboarding	Interactive tour for first-time users
💾 Preference Persistence	Remembers your last bridge direction & amount
⌨️ Keyboard Shortcuts	Power user shortcuts for common actions
♿ Accessibility	WCAG 2.1 AA compliant with screen reader support
🎨 Reduced Motion	Respects user motion preferences
🌙 Dark Mode	Beautiful dark theme (light mode coming soon)

Technical Features

Feature	Description
🛡️ Error Boundaries	Graceful error handling and recovery
📍 Address Validation	Real-time validation for all addresses
🔄 Auto-Refresh	Balances and statuses update automatically
📱 PWA Ready	Installable as a Progressive Web App
🚀 Optimized Build	Code splitting and lazy loading for fast loads

🎬 Demo

Watch AnchorX in Action

🔄 Bridge Flow

Complete deposit in one click

📊 Dashboard

Track your cross-chain portfolio

🚀 Quick Start

Get up and running in under 2 minutes

Prerequisites

✅ Node.js 18+
✅ Bun or npm
✅ Git

✅ MetaMask or WalletConnect wallet
✅ Leather or Xverse (Stacks wallet)
✅ Testnet tokens (see faucets below)

Installation

# 1️⃣ Clone the repository
git clone https://github.com/emmanuelist/anchor-x.git

# 2️⃣ Navigate to frontend
cd anchor-x/frontend

# 3️⃣ Install dependencies
bun install  # or npm install

# 4️⃣ Start development server
bun run dev  # or npm run dev

🎉 Open http://localhost:8080 and start bridging!

Environment Setup

Create a .env file:

# Required
VITE_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id

# Optional (uses defaults if not provided)
VITE_ETHEREUM_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
VITE_STACKS_API_URL=https://api.testnet.hiro.so

🚰 Get Testnet Tokens

Sepolia ETH

Alchemy Faucet

Sepolia USDC

Circle Faucet

Testnet STX

Hiro Faucet

🏗️ Architecture

System Overview

flowchart TB
    subgraph User["👤 User"]
        Browser["🌐 Browser"]
    end

    subgraph Frontend["⚓ AnchorX Frontend"]
        direction TB
        UI["🎨 React UI Layer"]
        State["📦 State Management"]
        Hooks["🪝 Custom Hooks"]
        Services["⚙️ Bridge Services"]
    end

    subgraph Wallets["👛 Wallet Providers"]
        direction LR
        ETHWallet["🦊 MetaMask / WalletConnect"]
        STXWallet["👝 Leather / Xverse"]
    end

    subgraph Ethereum["⟠ Ethereum Network"]
        USDC["💵 USDC Token"]
        xReserve["🔐 xReserve Contract"]
    end

    subgraph Circle["🔵 Circle Infrastructure"]
        Attestation["📜 Attestation Service"]
    end

    subgraph Stacks["🟣 Stacks Network"]
        USDCx["💎 USDCx Token"]
        StacksAttest["✅ Stacks Attestation"]
    end

    Browser --> UI
    UI --> State
    State --> Hooks
    Hooks --> Services
    Services --> ETHWallet
    Services --> STXWallet
    ETHWallet --> USDC
    ETHWallet --> xReserve
    STXWallet --> USDCx
    xReserve -->|"1. Lock USDC"| Attestation
    Attestation -->|"2. Verify"| StacksAttest
    StacksAttest -->|"3. Mint USDCx"| USDCx

    style Frontend fill:#6366F1,color:#fff
    style Circle fill:#00D632,color:#fff
    style Ethereum fill:#627EEA,color:#fff
    style Stacks fill:#5546FF,color:#fff

Component Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              App.tsx                                     │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  🛡️ ErrorBoundary                                                  │  │
│  │  ┌─────────────────────────────────────────────────────────────┐  │  │
│  │  │  🔗 AppKitProvider (Web3 Modal)                              │  │  │
│  │  │  ┌───────────────────────────────────────────────────────┐  │  │  │
│  │  │  │  📊 QueryClientProvider (TanStack Query)              │  │  │  │
│  │  │  │  ┌─────────────────────────────────────────────────┐  │  │  │  │
│  │  │  │  │  👛 WalletProvider (Custom Context)             │  │  │  │  │
│  │  │  │  │  ┌───────────────────────────────────────────┐  │  │  │  │  │
│  │  │  │  │  │  💬 TooltipProvider + Toasters            │  │  │  │  │  │
│  │  │  │  │  │  ┌─────────────────────────────────────┐  │  │  │  │  │  │
│  │  │  │  │  │  │  🧭 BrowserRouter                   │  │  │  │  │  │  │
│  │  │  │  │  │  │  ┌───────────────────────────────┐  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  🎓 OnboardingProvider        │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  ┌─────────────────────────┐  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │      📄 Routes          │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 🏠 Index           │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 🌉 Bridge          │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 📊 Dashboard       │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 📜 Transactions    │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 💸 Transfer        │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  ├── 📖 HowItWorks      │  │  │  │  │  │  │  │  │
│  │  │  │  │  │  │  │  │  └── ❓ FAQ             │  │  │  │  │  │  │  │  │
└──┴──┴──┴──┴──┴──┴──┴──┴───────────────────────────────┴──┴──┴──┴──┴──┴──┘

🌉 How Bridging Works

Deposit Flow: USDC → USDCx

Ethereum to Stacks

sequenceDiagram
    autonumber
    participant U as 👤 User
    participant A as ⚓ AnchorX
    participant E as ⟠ Ethereum
    participant X as 🔐 xReserve
    participant C as 🔵 Circle
    participant S as 🟣 Stacks

    U->>A: Enter amount & confirm
    A->>E: Check USDC allowance
    
    alt Needs Approval
        A->>E: Request USDC approval
        E-->>U: Sign approval tx
        E-->>A: Approval confirmed
    end
    
    A->>X: Call depositToRemote()
    X->>E: Lock USDC in contract
    E-->>A: Deposit confirmed
    
    Note over X,C: ~5-10 minute attestation window
    
    X->>C: Request attestation
    C->>C: Verify deposit
    C->>S: Submit attestation
    S->>S: Mint USDCx
    S-->>A: Mint confirmed
    A-->>U: 🎉 Bridge complete!

Withdraw Flow: USDCx → USDC

Stacks to Ethereum

sequenceDiagram
    autonumber
    participant U as 👤 User
    participant A as ⚓ AnchorX
    participant S as 🟣 Stacks
    participant C as 🔵 Circle
    participant X as 🔐 xReserve
    participant E as ⟠ Ethereum

    U->>A: Enter amount & confirm
    A->>S: Call burn function
    S->>S: Burn USDCx tokens
    S-->>A: Burn confirmed
    
    Note over S,C: ~5-10 minute attestation window
    
    S->>C: Request withdrawal attestation
    C->>C: Verify burn
    C->>X: Submit attestation
    X->>E: Release USDC
    E-->>A: Release confirmed
    A-->>U: 🎉 Withdrawal complete!

Bridge Progress Timeline

                            DEPOSIT PROGRESS
    ═══════════════════════════════════════════════════════════════
    
    ● INITIATED                    Transaction submitted
    │   └─ Tx Hash: 0x1234...abcd
    │
    ● CONFIRMING                   Waiting for confirmations
    │   └─ ████████████░░░░░░░░    12/20 blocks
    │
    ◐ ATTESTING                    Circle verification in progress
    │   └─ Estimated: ~5 minutes remaining
    │
    ○ MINTING                      Awaiting USDCx mint on Stacks
    │
    ○ COMPLETE                     Bridge successful! ✨
    
    ═══════════════════════════════════════════════════════════════

📱 Screenshots

Landing Page

Premium hero with live transaction ticker and network status

Bridge Interface

One-click bridging with transparent fees and real-time progress

Dashboard Dual-chain portfolio view	Transaction History Complete bridge history
Mobile View Fully responsive design	Wallet Connection Multi-wallet support

🔐 Security

Your Assets Are Protected

🔵 Circle xReserve

Industry-leading attestation protocol by Circle, the issuer of USDC

🔒 Non-Custodial

Your keys, your crypto. We never have access to your private keys

✅ Audited Contracts

Smart contracts audited by leading security firms

🛡️ Open Source

Fully transparent codebase — verify everything yourself

Security Best Practices

✅ All wallet connections use WalletConnect v2 / direct provider injection
✅ Transaction simulation before execution
✅ Address validation with checksum verification  
✅ Rate limiting and request throttling
✅ No sensitive data stored in local storage
✅ HTTPS only — all API calls are encrypted
✅ Content Security Policy headers

📄 Smart Contracts

Testnet Contracts (Sepolia / Stacks Testnet)

Contract	Network	Address	Explorer
🔐 xReserve	Ethereum Sepolia	`0x008888878f94C0d87defdf0B07f46B93C1934442`	↗
💵 USDC	Ethereum Sepolia	`0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238`	↗
💎 USDCx	Stacks Testnet	`ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.usdcx`	↗
🔄 USDCx-v1	Stacks Testnet	`ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.usdcx-v1`	↗

Mainnet Contracts

Contract	Network	Address	Explorer
💵 USDC	Ethereum	`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`	↗
💎 USDCx	Stacks	`SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.usdcx`	↗

Protocol Constants

const ANCHORX_PROTOCOL = {
  // Circle xReserve Configuration
  STACKS_DOMAIN_ID: 10003,          // Circle domain identifier for Stacks
  
  // Token Configuration
  USDC_DECIMALS: 6,                 // USDC uses 6 decimal places
  USDCX_DECIMALS: 6,                // USDCx maintains same precision
  
  // Bridge Limits
  MIN_BRIDGE_AMOUNT: "1.00",        // Minimum 1 USDC per transaction
  MAX_BRIDGE_AMOUNT: "1000000.00",  // Maximum 1M USDC per transaction
  
  // Timing Estimates
  DEPOSIT_TIME_MINUTES: 15,         // Average deposit completion
  WITHDRAW_TIME_MINUTES: 20,        // Average withdrawal completion
  
  // Fee Structure  
  BRIDGE_FEE_PERCENT: 0.1,          // 0.1% bridge fee
  MIN_FEE_USD: 0.01,                // Minimum fee floor
} as const;

🛠️ Technology Stack

Frontend Technologies

_{React 18}

_TypeScript

_{Vite 5}

_Tailwind

_{Framer Motion}

_{TanStack Query}

_{React Hook Form}

Web3 Technologies

_wagmi
_{Ethereum Hooks}

_viem
_{Ethereum Client}

_{Reown AppKit}
_{Wallet Modal}

_{@stacks/connect}
_{Stacks SDK}

_Zod
_Validation

📦 Full Dependency List

{
  "dependencies": {
    "@hookform/resolvers": "^3.10.0",
    "@radix-ui/react-*": "^1.x",
    "@reown/appkit": "^1.8.16",
    "@reown/appkit-adapter-wagmi": "^1.8.16",
    "@stacks/connect": "^8.2.4",
    "@stacks/network": "^7.3.1",
    "@stacks/transactions": "^7.3.1",
    "@tanstack/react-query": "^5.83.0",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "date-fns": "^3.6.0",
    "framer-motion": "^11.18.2",
    "lucide-react": "^0.462.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-hook-form": "^7.61.1",
    "react-router-dom": "^6.30.1",
    "recharts": "^2.15.4",
    "sonner": "^1.7.4",
    "tailwind-merge": "^2.6.0",
    "viem": "^2.44.4",
    "wagmi": "^2.19.5",
    "zod": "^3.25.76"
  }
}

📁 Project Structure

frontend/
├── 📂 public/                      # Static assets
│   ├── robots.txt                  # SEO configuration
│   └── site.webmanifest           # PWA manifest
│
├── 📂 src/
│   ├── 📂 assets/                  # Images, fonts, icons
│   │
│   ├── 📂 components/
│   │   ├── 📂 layout/              # App shell components
│   │   │   ├── Header.tsx          # Navigation header
│   │   │   ├── Footer.tsx          # Site footer
│   │   │   └── Layout.tsx          # Page wrapper
│   │   │
│   │   ├── 📂 ui/                  # 70+ reusable components
│   │   │   ├── GlowCard.tsx        # Glowing card effect
│   │   │   ├── BridgeTimeline.tsx  # Progress indicator
│   │   │   ├── ChainIcon.tsx       # Chain logo display
│   │   │   ├── ParticleField.tsx   # Background particles
│   │   │   ├── AnimatedCounter.tsx # Number animations
│   │   │   ├── PreviewModal.tsx    # Bridge preview
│   │   │   ├── SuccessModal.tsx    # Success celebration
│   │   │   └── ...                 # + many more
│   │   │
│   │   ├── ErrorBoundary.tsx       # Error handling
│   │   ├── NavLink.tsx             # Active navigation
│   │   └── OnboardingProvider.tsx  # Guided tour
│   │
│   ├── 📂 contexts/
│   │   └── WalletContext.tsx       # Dual-chain wallet state
│   │
│   ├── 📂 hooks/
│   │   ├── useBridge.ts            # Bridge operations
│   │   ├── useOnboarding.ts        # Tour management
│   │   ├── usePreferences.ts       # User settings
│   │   ├── usePageMeta.ts          # SEO management
│   │   └── useReducedMotion.ts     # Accessibility
│   │
│   ├── 📂 lib/
│   │   ├── 📂 appkit/              # Web3 modal config
│   │   │
│   │   ├── 📂 bridge/              # Bridge service layer
│   │   │   ├── deposit.ts          # USDC → USDCx
│   │   │   ├── withdraw.ts         # USDCx → USDC
│   │   │   ├── encoding.ts         # Address encoding
│   │   │   ├── transactionStatus.ts
│   │   │   └── index.ts            # Exports
│   │   │
│   │   ├── 📂 constants/           # Config & ABIs
│   │   ├── 📂 ethereum/            # ETH wallet service
│   │   ├── 📂 stacks/              # STX wallet service
│   │   ├── 📂 services/            # External APIs
│   │   └── 📂 utils/               # Helper functions
│   │
│   ├── 📂 pages/
│   │   ├── Index.tsx               # 🏠 Landing page
│   │   ├── Bridge.tsx              # 🌉 Bridge interface
│   │   ├── Dashboard.tsx           # 📊 Portfolio view
│   │   ├── Transactions.tsx        # 📜 History
│   │   ├── Transfer.tsx            # 💸 Direct send
│   │   ├── HowItWorks.tsx          # 📖 Education
│   │   ├── FAQ.tsx                 # ❓ Support
│   │   └── NotFound.tsx            # 404 page
│   │
│   ├── App.tsx                     # Root component
│   ├── App.css                     # Global styles
│   ├── index.css                   # Tailwind imports
│   └── main.tsx                    # Entry point
│
├── 📄 index.html                   # HTML template
├── 📄 package.json                 # Dependencies
├── 📄 tailwind.config.ts           # Tailwind config
├── 📄 tsconfig.json                # TypeScript config
├── 📄 vite.config.ts               # Vite config
└── 📄 README.md                    # You are here! 📍

👛 Wallet Support

Ethereum Wallets

MetaMask
✅ Full Support

WalletConnect
✅ 100+ Wallets

Coinbase
✅ Full Support

Rainbow
✅ Full Support

Trust Wallet
✅ Via WC

Stacks Wallets

Leather
✅ Full Support

Xverse
✅ Full Support

Other SIP-010
✅ Compatible

⌨️ Keyboard Shortcuts

Shortcut	Action
`Ctrl` + `K`	Open command palette
`Ctrl` + `B`	Go to Bridge page
`Ctrl` + `D`	Go to Dashboard
`Ctrl` + `T`	Go to Transactions
`Esc`	Close modals
`Enter`	Confirm actions

🧪 Testing

# Run unit tests
bun run test

# Run tests with coverage
bun run test:coverage

# Run e2e tests
bun run test:e2e

Manual Testing Checklist

Bridge Flow

Withdraw Flow

Check USDCx balance displays correctly
Enter withdrawal amount
Verify fee calculation
Complete burn transaction
Verify progress timeline updates
Confirm USDC received on Ethereum

🚢 Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Environment Variables (Production)

VITE_WALLETCONNECT_PROJECT_ID=your_production_project_id

🗺️ Roadmap

✅ Completed

🚧 In Progress

📋 Planned

🤝 Contributing

We 💜 contributions!

How to Contribute

🍴 Fork the repository
🌿 Create a feature branch
```
git checkout -b feat/amazing-feature
```
💻 Code your changes
✅ Test thoroughly

📝 Commit with conventional commits

git commit -m 'feat: add amazing feature'

🚀 Push to your fork
```
git push origin feat/amazing-feature
```
🔃 Open a Pull Request

Commit Convention

Type	Description
`feat:`	New features
`fix:`	Bug fixes
`docs:`	Documentation
`style:`	Code style (no logic change)
`refactor:`	Refactoring
`perf:`	Performance
`test:`	Tests
`chore:`	Maintenance

❓ FAQ

How long does bridging take?

Deposits typically complete in ~15 minutes. Withdrawals take ~20 minutes. Times may vary based on network congestion.

What are the fees?

AnchorX charges a 0.1% bridge fee (minimum $0.01). You also pay network gas fees on the source chain (ETH for deposits, STX for withdrawals).

Is it safe?

Yes! AnchorX uses Circle's xReserve protocol — the same infrastructure trusted by major institutions. We never have custody of your funds.

What wallets are supported?

Ethereum: MetaMask, WalletConnect (100+ wallets), Coinbase Wallet, Rainbow Stacks: Leather, Xverse, and other SIP-010 compatible wallets

Can I bridge to a different address?

Yes! Toggle "Custom Recipient" in the bridge interface to send USDCx to any valid Stacks address.

What if my transaction is stuck?

Bridge transactions can take up to 30 minutes during high congestion. Check the Transaction History page for real-time status. If stuck longer, reach out on Discord.

📜 License

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

MIT License

Copyright (c) 2026 AnchorX

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

🔗 Resources

📚 Documentation

Stacks Docs Circle xReserve USDCx Guide

🛠️ Tools

Hiro Explorer Etherscan Clarinet

💬 Community

Discord Twitter Forum

🚰 Faucets

Circle USDC STX Faucet Sepolia ETH

⭐ Star History

🌟 If you find AnchorX useful, please consider giving it a star!

Built on Bitcoin. Powered by Stacks. Stabilized by USDC.

Made with ❤️ by the AnchorX Team

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
frontend		frontend
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation