Swap loyalty points anywhere on XRPL
Unlocking ~$10B AUD in siloed loyalty value. Trade Macca's for Qantas, Woolworths for GYG — instantly, trustlessly, on-chain.
Australians hold $10B+ AUD in loyalty points trapped in silos. You can't swap Macca's points for Qantas miles. Points expire. Value is lost.
LoyaltySwap tokenises loyalty points as XRPL tokens, enabling market-driven AMM swaps via rippling — no brand system changes required.
# 1. Clone the repository
git clone <repo-url>
cd XRPL-Hackathon-2026
# 2. Install frontend dependencies
npm install
# 3. Set up backend
cd backend
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ..
# 4. Start backend (first run creates 7 issuer wallets on XRPL Testnet ~60s)
cd backend
source venv/bin/activate
uvicorn main:app --host 0.0.0.0 --port 8000
# Wait for: ✅ 7 AMM pools seeded (in-memory)
# Subsequent restarts are instant (wallets cached in .issuer_wallets.json)
# 5. In a new terminal, start frontend
cd XRPL-Hackathon-2026
npm run dev- Frontend: http://localhost:3000
- Backend: http://localhost:8000
- Health check: http://localhost:8000/health
docker-compose up --build- Frontend at http://localhost:3000, backend at http://localhost:8000
- First run takes ~60s (issuer wallet creation). Restarts are instant.
Uniswap-style two-panel swap interface. Select any loyalty token pair, see live AMM quotes with optimal routing (mMacca → XRP → mQantas), price impact, and execute real on-ledger XRPL transactions.
| Token | Brand | Description |
|---|---|---|
🍔 mMacca |
McDonald's AU | MyMacca's Rewards |
mQantas |
Qantas Airways | Frequent Flyer Points |
🛩️ mJetstar |
Jetstar Airways | Jetstar Rewards |
🌮 mGYG |
Guzman y Gomez | GYG Loyalty |
🍎 mApple |
Apple | Apple Rewards |
💻 mKmart |
Kmart | Kmart Rewards |
🛒 mWoolies |
Woolworths | Everyday Rewards |
Provide liquidity to earn 0.3% AMM fees. View TVL, APY, and pool share in real-time.
Send tokenised points to any XRPL address with real on-ledger Payment transactions. QR code generation for instant sharing.
Custodial ramp with 3-step flow: select brand → scan QR → mint tokens 1:1. Auto-creates trustlines for new tokens.
Follow this exact flow to see the full LoyaltySwap experience:
- Click "Connect Xaman" (top-right, pink button)
- Wait ~15s — a real XRPL Testnet wallet is created via faucet with 3 token trustlines + initial balances
- ✅ You'll see your real truncated XRPL address and XRP balance
- On the Swap tab (default), enter
100in the "You pay" field - Note the live quote: ~79 mQantas from 100 mMacca
- See the routing: mMacca → XRP → mQantas
- Click "Swap" — real XRPL transactions are submitted (~5s)
- Click the explorer link to see your transaction on https://testnet.xrpl.org
- Click "Done" — balances update from the ledger
- Click any brand card to go to the swap widget
- Click the "Liquidity" tab
- Select two tokens, enter amounts
- See pool TVL, APY, and your share estimate
- Click "Add Liquidity"
- Click the "Transfer" tab
- Enter a recipient XRPL address
- Select token + amount → click "Send"
- See your QR code for receiving
- Click the "On-Ramp" tab
- Select a brand (e.g., mMacca), enter
500 - Click "Scan & Mint" — watch the 3-step process
- Points are minted 1:1 to your wallet
XRPL-Hackathon-2026/
├── index.html # Entry point
├── vite.config.js # Vite + React + proxy config
├── package.json
├── docker-compose.yml # One-command Docker setup
├── Dockerfile # Frontend container
├── .gitignore
├── .dockerignore
├── backend/
│ ├── main.py # FastAPI app with lifespan + CORS
│ ├── routes.py # All API endpoints (auth, swap, mint, transfer, pools)
│ ├── xrpl_client.py # XRPL Testnet integration (wallets, hex currencies, AMM)
│ ├── requirements.txt # Python deps (fastapi, xrpl-py, uvicorn)
│ ├── Dockerfile # Backend container
│ └── .issuer_wallets.json # Cached issuer wallets (auto-generated, gitignored)
└── src/
├── main.jsx # React root with WalletProvider
├── App.jsx # Main layout: tabs, hero, footer
├── index.css # Full design system (600+ lines)
├── context/
│ └── WalletContext.jsx # Real XRPL wallet state (faucet, seed, balances)
├── data/
│ ├── tokens.js # 7 brand token definitions
│ └── pools.js # Local AMM pool calculations (fallback)
├── services/
│ └── api.js # API service layer (connects to FastAPI backend)
└── components/
├── Navbar.jsx # Sticky nav + tab bar + wallet button
├── SwapWidget.jsx # Uniswap-style swap interface
├── TokenSelector.jsx# Searchable token modal
├── BrandGrid.jsx # 7-card token overview grid
├── LiquidityPanel.jsx # LP interface
├── P2PTransfer.jsx # Send tokens + QR code
├── OnRamp.jsx # Deposit (scan → mint with auto-trustline)
├── SuccessOverlay.jsx # Confetti + tx hash + explorer link
└── RevenueWidget.jsx # Platform stats dashboard
User: Swap 100 mMacca → mQantas
1. Quote: Constant product AMM math (x * y = k), 0.3% fee per hop
2. Route: mMacca → XRP → mQantas (two hops)
3. Step 1: User sends 100 mMacca to mMacca issuer (real Payment tx)
4. Step 2: mQantas issuer sends ~79 mQantas to user (real Payment tx)
5. Auto-trustline: If user doesn't have mQantas trustline, it's created first
6. Result: Two real on-ledger transactions, visible on testnet.xrpl.org
7. Currency codes: >3 char names hex-encoded (mMacca → 6D4D616363610000...)
| Token | Hex | Usage |
|---|---|---|
--pink |
#FF007A |
Primary CTAs, accents |
--dark-bg |
#0D0D0D |
App background |
--dark-card |
#191919 |
Card surfaces |
--green |
#27AE60 |
Positive indicators |
--purple |
#8B5CF6 |
Liquidity theme |
--red |
#EB5757 |
Negative indicators |
Font: Inter (Google Fonts) — 400/500/600/700/800/900
Responsive: Mobile-first, max-width 1200px, bottom nav on mobile
| Layer | Technology |
|---|---|
| Frontend | React 19 + Vite 5 |
| Backend | Python FastAPI + uvicorn |
| XRPL | xrpl-py — real Testnet transactions |
| Styling | Vanilla CSS with design tokens |
| Icons | Lucide React |
| QR Codes | qrcode.react |
| Animations | react-confetti + CSS keyframes |
| AMM Engine | Custom constant product (x*y=k) |
| Network | XRPL Testnet (s.altnet.rippletest.net) |
| Deploy | Docker Compose |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Backend health + pool count |
| POST | /api/v1/auth/connect |
Connect wallet, get JWT + balances |
| POST | /api/v1/wallet/create |
Create funded testnet wallet + trustlines |
| GET | /api/v1/wallet/balances/{address} |
Real on-ledger token balances |
| GET | /api/v1/swaps/quote |
AMM swap quote |
| POST | /api/v1/swaps/execute |
Execute real swap (2 Payment txs) |
| POST | /api/v1/tokens/mint/{token} |
Mint tokens from issuer to user |
| POST | /api/v1/transfers/send |
P2P token transfer |
| GET | /api/v1/pools |
All AMM pool info |
| GET | /api/v1/tokens |
Token metadata + hex codes + issuers |