Open-source reference for building a mobile-native Hyperliquid builder app — wallet auth, Bridge2 deposits, agent signing, builder fees, alerts, and rewards.
Mobile-first by design. Most users trade on phones. This repo shows one full-featured path (multi-asset trading on Google Play). You are encouraged to fork narrower products — gold-only, regional equities, single HIP-3 ecosystem, demo/education — using the same infra patterns.
Live: HyperTrade on Google Play (APK on hypertrade.exchange if Play is geo-blocked). BuilderPad web: builderpad.xyz.
HyperTrade is a production-style Expo / React Native app with a FastAPI backend:
- Hyperliquid — perps, spot, HIP-3 deployer markets via
@nktkas/hyperliquid - Privy — embedded self-custody wallets (email, Google, Apple)
- Bridge2 — gasless USDC deposits (EIP-2612 permit + backend relayer on Arbitrum)
- Supabase — alerts, rewards, push tokens, deposit workers
- Railway — backend hosting (Dockerfile included)
Also in this reference app (optional for forks): BuilderPad (web/ on Vercel — branded Hyperliquid web apps; Pons token launch is a chapter, not the product), AI trading agents (workers/ai-agent, Tier 2), and UR.APP neobank / banking (IBAN/card, Tier 3). None of these are required to ship a Hyperliquid mobile builder app — see ROADMAP.md.
Not included: legal advice or store approval guarantees.
Mobile (Expo + Privy) HyperTrade retail app
├──► Hyperliquid API / WS orders, account stream, builder fee
└──► Your backend (FastAPI)
├──► Supabase
├──► Arbitrum RPC + Bridge2 relayer
└──► Optional: Finnhub, Gemini, FX caches
Optional surfaces (skip in a minimal fork):
├──► web/ (Vite, Vercel) BuilderPad — builderpad.xyz console
│ + {slug}.builderpad.xyz HL trading apps
│ + optional Pons coin chapter (contracts/pons-v2)
├──► UR.APP / Mantle IBAN, fiat tokens, KYC, cards
└──► ai-agent-worker AI agent trading brain (Railway)
~45 min if you have Privy + Supabase + an Arbitrum RPC URL.
git clone https://github.com/YOUR_ORG/hyperrwa.git && cd hyperrwa
# Backend
cp backend/.env.example backend/.env # fill in secrets
cd backend && pip install -r requirements.txt
uvicorn server:app --reload --port 8000
# Frontend (separate terminal — requires Expo dev client)
cp frontend/.env.example frontend/.env
cd frontend && npm install && npx expo start --dev-clientFull checklist: docs/SETUP.md
Database bootstrap: backend/supabase_schema.sql, then optional migrations for AI / UR / app version policy — see docs/DATABASE.md.
| Doc | Contents |
|---|---|
| SETUP.md | Step-by-step infra setup |
| DATABASE.md | Supabase tables by tier + migration order |
| FORKING.md | Strip banking/AI, rebrand, builder address |
| AGENTS.md | Coding-agent map, MCPs, UR partner note |
| AI_AGENTS.md | AI agents fork guide — Shared + Dedicated (HL subs) |
| BANKING_UR.md | Neobank / UR IBAN/card fork guide (short) |
| HL_BUILDER.md | Builder fees, Bridge2, scaling & rate limits |
| COSTS.md | Expected infra / AI / banking costs by tier |
| ENVIRONMENT.md | All env vars + unused/legacy list |
| ROADMAP.md | Shipped surfaces (HL mobile / BuilderPad web / banking / AI); HIP-4 is a separate repo |
| BUILDERPAD.md | BuilderPad product — Vite web/ at builderpad.xyz (Vercel); branded HL apps at {slug}.builderpad.xyz |
| PONS_FORK.md | Optional BuilderPad coin chapter: Pons v2 factory fork (Robinhood 4663). Not the BuilderPad product |
| MOBILE_RELEASE.md | Play Store / App Store, D-U-N-S, compliance |
| SECURITY.md | Secrets and reporting |
| Surface | Status | Need it to fork an HL mobile app? |
|---|---|---|
| 1 — Core HL trading | Shipped (frontend/ Expo) |
Yes |
| 2 — AI agents | Shipped (workers/ai-agent) |
No |
| 3 — Neobank / banking (UR.APP IBAN / card) | Shipped in reference app | No |
| BuilderPad | Shipped (web/ → builderpad.xyz on Vercel) |
No — web console for branded Hyperliquid apps ({slug}.builderpad.xyz). Optional Pons token launch lives under this product (contracts/pons-v2/), it is not a second product |
| HIP-4 outcome markets | Separate repo — orbcast | No — do not add here |
AI builds on HL (Tier 1). BuilderPad is a web product on the same FastAPI / Privy / Supabase stack (not a rewrite of the Expo app). Neobank/banking is a separate partner stack (compliance + ops). Minimal mobile forks should keep Privy + Bridge2 + builder fee only. Details: ROADMAP.md · BUILDERPAD.md.
Core HL stack can stay under ~$500/mo SaaS before upgrade cliffs (plus Bridge2 relayer ETH). Full reference with Expo/Privy upgrades and light extras often still under ~$1k/mo; AI house data (e.g. CoinGlass) and neobank/banking partner terms jump that hard. Rough check: $1M volume × 0.1% builder fee ≈ $1,000. Ballparks by tier: docs/COSTS.md. Capacity / HL rate limits: docs/HL_BUILDER.md#scaling--rate-limits.
| Store | HyperTrade status |
|---|---|
| Google Play | Live — APK on hypertrade.exchange if Play is blocked |
| Apple App Store | Not live yet — Apple is strict on perps |
Going mobile means Google and Apple review, a registered business + D-U-N-S (financial-app reality), clear non-custodial Hyperliquid interface wording, and usually geo / sanctions controls (HyperTrade geo-fences the US and UK). Web-only forks can skip store org checks. Details: docs/MOBILE_RELEASE.md · costs: docs/COSTS.md.
Geo-fence is backend-configurable for forks — see ENVIRONMENT.md / MOBILE_RELEASE.md.
You do not need to replicate our full asset list or UI. Strong fork strategies:
- Commodities only (XAU, XAG, oil)
- One geography or language
- One HIP-3 deployer vertical
- Testnet-only education app
- A branded web Hyperliquid desk for a community (keep
web// BuilderPad; skip the Play Store path)
Strip features you do not need; keep HL signing + deposits + builder config.
hypertrade/
├── backend/
│ ├── server.py # FastAPI app (core + optional modules)
│ ├── tenants.py # BuilderPad tenant helpers (optional)
│ ├── ai_agents.py # AI control plane (optional)
│ ├── supabase_schema.sql # DB bootstrap
│ ├── migrations/ # Additive SQL (AI, UR, BuilderPad, …)
│ └── .env.example
├── frontend/ # HyperTrade Expo app (Tier 1)
│ ├── app/ # Expo Router screens
│ ├── src/lib/hyperliquid.ts # HL SDK integration
│ └── .env.example
├── web/ # BuilderPad — Vite + Privy (Vercel → builderpad.xyz)
├── contracts/pons-v2/ # Optional BuilderPad coin chapter (Pons v2 fork)
├── workers/ai-agent/ # AI execution worker (optional; has .env.example)
├── showcase/ # Public AI agents demo site (optional)
└── docs/
Built on other people's open work. Thank you.
| Project | What we use it for |
|---|---|
Hyperliquid — docs, hyperliquid-python-sdk |
The exchange every app here trades on: builder codes, agent signing, Bridge2. The official Python SDK is our reference for the exchange/info payloads |
@nktkas/hyperliquid by nktkas |
TypeScript Hyperliquid client used by the mobile app, the web desk and the AI worker |
| HypeTerminal by vipineth (MIT) | Open-source Hyperliquid terminal — inspiration and reference for the web trading desk in web/ |
| Pons v2 by Pons (MIT) | The bonding-curve launchpad our contracts/pons-v2/ stack is forked from (renamed BuilderPad*, economics changed — see PONS_FORK.md). Not affiliated with or endorsed by Pons |
| Uniswap v4 by Uniswap Labs | Graduated tokens trade on the official v4 PoolManager on Robinhood Chain. Vendored interfaces / libraries are MIT except Pool.sol and Position.sol (BUSL-1.1, change date 2027-06-15) — see contracts/pons-v2/LICENSE |
| Privy · Supabase · Robinhood Chain | Auth + embedded wallets · database · the L2 the creator tokens live on |
MIT — see also CONTRIBUTING.md.
If this reference helps you ship, donations are welcome:
0x29a1D36DaEE6B0E0Dd4873dd964677000B6e23EB
(Same address as the HyperTrade HL builder fee recipient.)
Reference software only. Not financial, legal, or tax advice. Users hold keys via Privy; you operate your own backend and relayer at your risk.