# Table of Contents - [BASED | BasedApp Docs](#based-basedapp-docs) - [Web Terminal | BasedApp Docs](#web-terminal-basedapp-docs) - [Telegram Bot | BasedApp Docs](#telegram-bot-basedapp-docs) - [Mobile App | BasedApp Docs](#mobile-app-basedapp-docs) - [Affiliate Program | BasedApp Docs](#affiliate-program-basedapp-docs) - [Margining | BasedApp Docs](#margining-basedapp-docs) - [Take Profit / Stop Loss | BasedApp Docs](#take-profit-stop-loss-basedapp-docs) - [Top up & Spend | BasedApp Docs](#top-up-spend-basedapp-docs) - [Funding Rate | BasedApp Docs](#funding-rate-basedapp-docs) - [Desktop | BasedApp Docs](#desktop-basedapp-docs) - [Based Cloud | BasedApp Docs](#based-cloud-basedapp-docs) - [Trailing Stop Loss | BasedApp Docs](#trailing-stop-loss-basedapp-docs) - [Funding Trading Account | BasedApp Docs](#funding-trading-account-basedapp-docs) - [Liquidation | BasedApp Docs](#liquidation-basedapp-docs) - [Entry Price / PnL | BasedApp Docs](#entry-price-pnl-basedapp-docs) - [Card Types | BasedApp Docs](#card-types-basedapp-docs) - [Based XP / Gold | BasedApp Docs](#based-xp-gold-basedapp-docs) - [Depositing from Binance | BasedApp Docs](#depositing-from-binance-basedapp-docs) - [Types of Order | BasedApp Docs](#types-of-order-basedapp-docs) - [FairShare | BasedApp Docs](#fairshare-basedapp-docs) - [TWAP | BasedApp Docs](#twap-basedapp-docs) - [Participate | BasedApp Docs](#participate-basedapp-docs) - [Fees | BasedApp Docs](#fees-basedapp-docs) - [Switching over from Legacy to HyperApp | BasedApp Docs](#switching-over-from-legacy-to-hyperapp-basedapp-docs) - [Builder-on-Builder Program | BasedApp Docs](#builder-on-builder-program-basedapp-docs) - [Adding Agent Wallet | BasedApp Docs](#adding-agent-wallet-basedapp-docs) - [Monetization | BasedApp Docs](#monetization-basedapp-docs) - [Sample Apps | BasedApp Docs](#sample-apps-basedapp-docs) - [API Traders | BasedApp Docs](#api-traders-basedapp-docs) - [Builder API access | BasedApp Docs](#builder-api-access-basedapp-docs) - [Based MiniApp | BasedApp Docs](#based-miniapp-basedapp-docs) - [Quick Start Guide | BasedApp Docs](#quick-start-guide-basedapp-docs) - [MiniApp Architecture | BasedApp Docs](#miniapp-architecture-basedapp-docs) - [MiniApp API | BasedApp Docs](#miniapp-api-basedapp-docs) - [Card Types | BasedApp Docs](#card-types-basedapp-docs) - [React Sample MiniApp | BasedApp Docs](#react-sample-miniapp-basedapp-docs) - [HTML Sample MiniApp | BasedApp Docs](#html-sample-miniapp-basedapp-docs) - [Take Profit / Stop Loss | BasedApp Docs](#take-profit-stop-loss-basedapp-docs) - [Participate | BasedApp Docs](#participate-basedapp-docs) - [Card Types | BasedApp Docs](#card-types-basedapp-docs) - [Switching over from Legacy to HyperApp | BasedApp Docs](#switching-over-from-legacy-to-hyperapp-basedapp-docs) - [Based MiniApp | BasedApp Docs](#based-miniapp-basedapp-docs) --- # BASED | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) We are building the One Omnichannel Trading Platform for Hyperliquid Click the links below to learn more about our different product offerings: [Web Terminal](https://basedapp.gitbook.io/docs/~/revisions/lVRJ5uqiazETgyrlaN7r/based/web-terminal) | [Mobile App](https://basedapp.gitbook.io/docs/~/revisions/2nySWkdGjU8g4ULyNaur/based/mobile-app) | [Telegram Bot](https://basedapp.gitbook.io/docs/~/revisions/2nySWkdGjU8g4ULyNaur/based/telegram-bot) | [Desktop](https://app.gitbook.com/o/eXUW6d6Po5jqJrh52r7R/s/D195DGgjp8wD1XdWWTcZ/~/changes/82/based/desktop) | [Card](https://basedapp.gitbook.io/docs/~/revisions/2nySWkdGjU8g4ULyNaur/card) * * * Visit our socials here: [Discord](https://discord.gg/basedapp) | [Twitter](https://based.one/twitter) | [Telegram](https://based.one/telegram) [NextWeb Terminal](https://basedapp.gitbook.io/docs/based/web-terminal) Last updated 1 month ago --- # Web Terminal | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) The Based Web Terminal brings a sleek, high-performance trading experience directly to your browser: [https://app.based.one/](https://app.based.one/) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FJR6rnR9wQOqzEnBJhWxP%252FScreenshot%25202025-08-21%2520at%25202.33.58%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3Db4c266e5-6e77-4773-94af-232726cedd82&width=768&dpr=4&quality=100&sign=66e0070b&sv=2) This isn’t just a frontend for [Hyperliquid](https://app.hyperliquid.xyz/trade) . It’s a fully integrated power terminal that supports everything you can do on Hyperliquid’s native UI — and more. Designed for both everyday users and advanced traders, the Web Terminal is built to make on-chain trading more intuitive, faster, and highly customizable. In addition to the core features already available, we’re rolling out a suite of advanced tools to supercharge your trading: * Advanced Order Algorithms (e.g., Chase Orders) Dynamically adjust your limit orders to follow price action — great for staying in range during fast-moving markets. * Position Alerts via Notifications Get real-time push alerts on critical position events: fills, liquidations, price thresholds, and margin calls. * Portfolio & Exposure Tracking Instantly visualize your portfolio exposure by asset class, sector, or strategy — whether you’re net-long, delta-neutral, or hedged. * Time-Based Limit Orders Schedule limit orders that auto-cancel or execute only within specific timeframes — ideal for event-driven trading or session-based strategies. * Automation Setup Configure and run rule-based bots to execute predefined strategies like recurring buys, stop-loss execution, DCA entries, or rebalancing. * * * We’re just getting started. The Based Web Terminal is built to be your all-in-one command center for the Hyperliquid ecosystem — fast, flexible, and focused on trader empowerment. **BASED Web Terminal – Built on Hyperliquid Infrastructure** The BASED Web Terminal delivers a seamless, high-performance trading experience by leveraging Hyperliquid’s robust and battle-tested backend infrastructure. Whether you’re a long-term holder or an active trader, BASED gives you access to both perpetual and spot markets — all within a unified interface. * * * #### [](https://basedapp.gitbook.io/docs/based/web-terminal#trade-100-assets-backed-by-hyperliquid-liquidity) Trade 100+ Assets, Backed by Hyperliquid Liquidity BASED uses Hyperliquid’s real-time orderbooks to support trading across a wide and growing range of tokens. Currently, Hyperliquid supports over 100 assets, including major tokens like BTC, ETH, SOL, and trending altcoins — with more being added regularly based on community demand. Importantly, Hyperliquid is on track to implement a decentralized and permissionless asset listing mechanism, which will empower users and developers to list new assets without centralized gatekeeping — promoting broader innovation and inclusion in the on-chain economy. * * * #### [](https://basedapp.gitbook.io/docs/based/web-terminal#leverage-and-margin-mechanics) Leverage and Margin Mechanics Our trading engine follows the same leverage and risk management framework as Hyperliquid: * Maximum Leverage: Varies by asset, ranging from 3x to 40x, depending on asset volatility and liquidity. * Initial & Maintenance Margin: Maintenance margin is 50% of the initial margin at maximum leverage. * For example, if an asset has a maximum leverage of 20x, the maintenance margin required is 2.5% of notional value (vs. 5% initial margin). This approach balances capital efficiency with risk management, allowing traders to maximize exposure while minimizing liquidation risk under normal volatility conditions. * * * #### [](https://basedapp.gitbook.io/docs/based/web-terminal#backend-consistency-with-hyperliquid) Backend Consistency with Hyperliquid Because BASED is fully integrated with Hyperliquid’s backend systems, we inherit and adhere to the same trading mechanics, pricing logic, liquidation engine, and fee structure as defined in Hyperliquid’s official documentation. For full details, including trading rules, margin calculations, and position management: Refer to the [Hyperliquid Trading Docs](https://hyperliquid.gitbook.io/hyperliquid-docs/trading) * * * Whether you’re deploying sophisticated strategies with leverage or simply executing spot buys, the BASED Web Terminal provides the full power of Hyperliquid — wrapped in a sleek, mobile-friendly interface designed for the next generation of on-chain traders. [PreviousBASED](https://basedapp.gitbook.io/docs) [NextMobile App](https://basedapp.gitbook.io/docs/based/mobile-app) Last updated 2 months ago --- # Telegram Bot | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F3TPccfUmZFcig2jI5S1x%252FScreenshot%25202025-08-21%2520at%25202.39.00%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D880d1364-21fa-4d89-9874-b8ed3059be02&width=768&dpr=4&quality=100&sign=45e8aed0&sv=2) Meet Based Bot - one of the fastest, most advanced trading bots on Hyperliquid. 🔸 Real-time balance & positions 🔸 Execute longs/shorts 🔸 Close single or all trades 🔸 View ratio & interval charts 🔸 Add to group & create leaderboard And more.. Click here to get access to the telegram bot > [https://t.me/based\_one\_bot](https://t.me/based_one_bot) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FHsZHR14QLHn2be77E7Oq%252FScreenshot%25202025-08-21%2520at%25202.39.16%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3Df28c902d-8138-484f-b49a-3e4d9d22d8cc&width=768&dpr=4&quality=100&sign=2593b540&sv=2) 🤖 Based Trading Bot Commands 📊 Trading: /positions - View your open positions /balance - Check account balance 📈 Opening Positions: /long SYMBOL AMOUNT - Open long position (buy) /short SYMBOL AMOUNT - Open short position (sell) /close SYMBOL AMOUNT - Close existing position 📋 Format Options: • Token amounts: /long ETH 0.5, /short BTC 0.01 • Dollar amounts: /long ETH $100, /short BTC $500 • Close all: /close ETH all 🎯 Interactive Mode (Private Chat Only): • /long - Step-by-step long position • /short - Step-by-step short position • /close - Step-by-step position closing 📈 Charts: /chart SYMBOL INTERVAL - Generate price charts 📊 Chart Types: • Price charts: /chart BTC, /chart ETH 4h • Ratio charts: /chart BTC/ETH, /chart ETH/SOL 1d • Available intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d 🔥 Popular Ratios: • /chart BTC/ETH - Digital gold vs smart contracts • /chart ETH/SOL - Layer 1 competition • /chart SOL/AVAX - High-performance chains 👤 Account: /profile - View your profile /notifications - Toggle notifications /unlink - Unlink your wallet 👥 Group Commands: Add me to a group to access: • /join - Subscribe to group features • /members - View group members • /leaderboard - Group rankings ℹ️ Information: /help - Show this help message 💡 Tips: • Use inline buttons for quick actions • Join groups to compete with friends • Enable notifications for real-time updates [PreviousMobile App](https://basedapp.gitbook.io/docs/based/mobile-app) [NextDesktop](https://basedapp.gitbook.io/docs/based/desktop) Last updated 2 months ago --- # Mobile App | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) #### [](https://basedapp.gitbook.io/docs/based/mobile-app#all-in-one-mobile-app) All-in-One Mobile App Hold. Trade. Spend. Seamlessly. [Download on IOS](https://apps.apple.com/us/app/basedapp-crypto-wallet/id6747331142) [Download on Android](https://play.google.com/store/apps/details?id=com.basedapp.basedsuperapp&pli=1) Crypto is a vast and complex ecosystem — from memecoins to NFTs, DeFi protocols to real-world utility tokens. But when you strip it all down, most users just want to do three things: 1. Secure their crypto 2. Trade tokens efficiently 3. Use crypto in everyday life That’s what the Based App is built for — a unified, mobile-first platform that brings the core pillars of crypto into one simple, streamlined app. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FWjcHzsrHy1Cn4f2XQfW2%252Fphoto_2025-07-16_16-44-57.jpg%3Falt%3Dmedia%26token%3D99f69d1b-aa52-45a8-8be8-3c7838202c05&width=300&dpr=4&quality=100&sign=89316c7c&sv=2)![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FuvvfEgaWbstuSkZaydeo%252Fimage.png%3Falt%3Dmedia%26token%3Df581d6de-b640-43f8-b0d2-25d43184f2b2&width=300&dpr=4&quality=100&sign=4d511b15&sv=2) * * * #### [](https://basedapp.gitbook.io/docs/based/mobile-app#what-you-can-do-with-based-app-on-mobile) What You Can Do With Based App on Mobile Currently live on Android and iOS, the Based HyperApp offers a CEX-grade experience, but with full self-custody — bridging the best of both worlds. Here’s what you can do with it: * Spot Trading Buy and sell assets like BTC, ETH, and SOL while maintaining full control of your keys. * Perpetual Trading High-performance mobile interface for trading perps — complete with push notifications, real-time fills, and smooth order execution. * Real-World Spending Use your crypto with our integrated Visa Debit Card, available directly within the app. No off-ramping delays — just tap and go. * Portfolio Visibility A comprehensive portfolio dashboard that consolidates balances across Spot, Perps, Staking, EVM assets, and cash. Powered by Hyperliquid. #### [](https://basedapp.gitbook.io/docs/based/mobile-app#getting-started-is-easy) Getting Started Is Easy Whether you’re new to crypto or already have a wallet, BASED makes onboarding effortless: * New to Crypto? Sign up with your email or Google account and create a self-custodial wallet in seconds. * Already Have a Wallet? Use Connect Mobile to link your existing wallet. BASED will help you place trades, but never takes custody of your funds. We don’t store your keys. You’re always in control. [PreviousWeb Terminal](https://basedapp.gitbook.io/docs/based/web-terminal) [NextTelegram Bot](https://basedapp.gitbook.io/docs/based/telegram-bot) Last updated 1 month ago --- # Affiliate Program | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252Fx9x8xanaJrtOZCKjRiNJ%252FScreenshot%25202025-07-16%2520at%25204.27.13%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D60ae1dad-bf87-48dd-8c1e-88e3948cda77&width=768&dpr=4&quality=100&sign=1753ec90&sv=2) #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#based-referral-program) BASED Referral Program Earn up to 76% of trading fees across three tiers. Monetize your network by referring traders to BASED through our powerful multi-tier affiliate program. Whether you’re a content creator, trader, or community builder, you can earn recurring commissions as your network grows. * * * #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#commission-structure) Commission Structure Our referral program features a 3-tier commission model, rewarding you not just for your direct referrals, but also for helping us grow through second and third-degree connections. * Tier 1: Direct Referrals – 60% Commission You earn 60% of the trading fees generated by users who sign up directly through your unique link. * Tier 2: Indirect Referrals – 12% Commission You also earn 12% of the trading fees from users referred by your direct referrals. * Tier 3: Extended Network – 4% Commission An additional 4% of trading fees from users brought in by your Tier 2 referrals. Total Potential Earnings: Up to 76% of fees across your network ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FvQiFYqCGLnLr3KQwD95n%252FScreenshot%25202025-07-16%2520at%25204.28.27%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D52467aef-9091-4109-b3eb-76a3cb5ca331&width=768&dpr=4&quality=100&sign=e54be073&sv=2) #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#advanced-referral-dashboard) Advanced Referral Dashboard Track and optimize your referral performance with our intuitive dashboard designed for both power users and newcomers. You’ll gain access to key metrics including: * Referral Growth Rate – Measure how quickly your network is expanding over time * Overall Growth – Visualize your referral tree across all tiers * Estimated Commission Earnings – Project your income based on historical activity and current trends * * * #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#performance-insights) Performance Insights The dashboard also provides in-depth analytics to help you refine your strategy: * Conversion Rate – See how many users actually sign up and trade after clicking your link * Average Commission Per User – Track how much each referred user earns you * Total Referred Volume – View the cumulative trading volume generated through your referrals * Estimated Future Commissions – Forecast future payouts based on usage patterns * * * #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#how-it-works) How It Works Getting started is simple: 1. Get Your Link (there's a min XP requirement before you can get a referral link) Access your unique referral link from the BASED dashboard. 2. Start Sharing Promote your link across social media, Discord, Telegram, blogs, or your personal website. 3. Earn as They Trade Once users register through your link, they’re permanently tied to your account — and you’ll earn commissions every time they trade. * * * Whether you’re a solo trader or leading a large community, BASED referral program offers a transparent, high-yield way to monetize your influence and help drive adoption in the Hyperliquid ecosystem. Let us help you grow — and get rewarded along the way. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FvNWZLcKiYH0ha6udmZka%252Fimage.png%3Falt%3Dmedia%26token%3D9031b9b6-e08c-477f-9367-86880c04cc19&width=768&dpr=4&quality=100&sign=a4661151&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2Flh7-rt.googleusercontent.com%2Fdocsz%2FAD_4nXc8bqh6di7xyNjsJ-q9Pn_HRC0liJIPRCI0Qc31i5BSCVlZQGNbbexRSSWTUpnlXcyrPyxSp6Z2lhgNZyhjCkyFAAkiIVgGHw3-H9L2hgdGnIpxbpEWrojOQJDZgTAcIPEz0-0%3Fkey%3DjdmK2fwHa-ZwgY347NWoqg&width=768&dpr=4&quality=100&sign=c3771fb5&sv=2) #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#based-affiliate-program-v2) BASED Affiliate Program V2 The first 3-tier affiliate system in crypto, designed to reward not just direct referrals but your entire extended network — for life. **How It Works:** * Tier 1 (Direct Referrals): Earn 60% of BASED fees * Tier 2 (Referrals of Your Referrals): Earn 12% * Tier 3 (Third-Degree Referrals): Earn 4% > Even if you don’t know a whale — your friend might. * * * #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#why-based-affiliate-greater-than-traditional-exchanges) Why BASED Affiliate > Traditional Exchanges: * Earn from extended networks, not just direct signups * Users farm Both BASED XP + Hyperliquid Points — 2-in-1 capital efficiency * More revenue goes back to the network vs. CEXs * Community-aligned model — not extractive * * * #### [](https://basedapp.gitbook.io/docs/based/affiliate-program#based-trade-spend-earn-all-in-one) BASED = Trade, Spend, Earn — All in One * Trade on Hyperliquid * Spend with a Visa debit card * Earn through a lifetime revenue-sharing affiliate model No ads. No bridges. No friction. Just real crypto utility — finally. Distribution is our moat. Align with us and share in the upside. _What is the difference between_ BASED _Affiliate, Ambassador and Partner?_ **Affiliate**: Anybody can sign up to be an affiliate and start sharing about BASED. **Ambassador**: Active BASED champions can contact us via Twitter or Discord to get selected as ambassadors. **Partner**: The ultimate program with the ultimate benefits. Work done as an affiliate/ambassador will be counted in the BASED Partner Application. [PreviousDesktop](https://basedapp.gitbook.io/docs/based/desktop) [NextFees](https://basedapp.gitbook.io/docs/based/fees) Last updated 1 month ago --- # Margining | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FnCIrTZgMHVYqiJYSEwH0%252Fimage.png%3Falt%3Dmedia%26token%3D5e582eb5-d0ce-42ed-a6fc-8c1f37349dd3&width=768&dpr=4&quality=100&sign=cf6a922f&sv=2) #### [](https://basedapp.gitbook.io/docs/trading/margining#margining-overview) Margining Overview Margin calculations follow standard practices used by major centralized derivatives exchanges. * * * #### [](https://basedapp.gitbook.io/docs/trading/margining#margin-modes) Margin Modes When opening a position, users must choose a margin mode: * Cross Margin (default) Collateral is shared across all cross-margin positions, maximizing capital efficiency. Losses or gains from one position can affect others under the same mode. * Isolated Margin Collateral is confined to a single asset. If the position is liquidated, it does not impact other positions — whether cross or isolated. Likewise, losses from elsewhere won’t affect this position. * * * #### [](https://basedapp.gitbook.io/docs/trading/margining#initial-margin-and-leverage) Initial Margin & Leverage * Users can set leverage anywhere from 1x up to the asset’s maximum. * The margin required to open a position is: Position Size × Mark Price ÷ Leverage * In cross margin, the initial margin is locked and cannot be withdrawn. * In isolated margin, users can adjust margin (add/remove) even after the position is opened. For cross positions, unrealized PnL can be reused as margin for new positions. For isolated positions, unrealized PnL adds to that position’s margin. Once a position is open, leverage is not automatically re-evaluated. Users must monitor their risk and can adjust by: * Closing part or all of the position * Adding margin (if isolated) * Depositing USDC (if cross) * * * #### [](https://basedapp.gitbook.io/docs/trading/margining#maintenance-margin-and-liquidation) Maintenance Margin & Liquidation * Cross positions are liquidated if your total account value (including unrealized PnL) falls below the maintenance margin, which is 50% of the initial margin at max leverage. * Isolated positions follow the same logic, but the calculation is limited to the margin and notional value of the individual position only. [PreviousTrailing Stop Loss](https://basedapp.gitbook.io/docs/trading/trailing-stop-loss) [NextFunding Rate](https://basedapp.gitbook.io/docs/trading/funding-rate) Last updated 3 months ago --- # Take Profit / Stop Loss | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) #### [](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss#take-profit-and-stop-loss-tp-sl-orders) Take Profit and Stop Loss (TP/SL) Orders TP/SL orders are used to automatically close a position once it reaches a certain profit or loss level. These are triggered using the mark price. You can place and adjust TP/SL orders directly on the TradingView chart. If you drag an order to a level where it would instantly execute, an error will appear — this is to prevent accidental trades. If you do want it to execute immediately, you can close it manually via the position table or order form. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FJicYqDY1OpRg6nzl4JTq%252FScreenshot%25202025-07-16%2520at%25207.00.52%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D0050795f-20ea-4e07-bde7-c5c8cf018148&width=768&dpr=4&quality=100&sign=19bdfe0a&sv=2) * * * #### [](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss#market-vs-limit-tp-sl-orders) Market vs Limit TP/SL Orders You can choose between market or limit TP/SL orders: * Market TP/SL orders have a default slippage tolerance of 10%. * Limit TP/SL orders allow you to control slippage by setting a custom price. For example, let’s say you have a long position and set a stop loss with: * Trigger price: $10 * Limit price: $10 If the price drops quickly from $11 to $9, the SL may not fill — it will rest at $10. But if you set the limit price lower (e.g. $8), it’s more likely to get filled, though potentially at a worse price. * * * #### [](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss#tp-sl-tied-to-a-position) TP/SL Tied to a Position When you place TP/SL orders from the position form, they default to cover the entire position size. You can also set a fixed size manually — this will not adjust even if your position changes. These are recommended for beginners due to their simplicity and ease of use. * * * #### [](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss#tp-sl-linked-to-a-parent-order-oco) TP/SL Linked to a Parent Order (OCO) TP/SL orders can also be attached to a parent order (this setup is also called one-cancels-other or OCO). These behave a bit differently: * If the parent order fills fully, the TP/SL orders are immediately created. * If the parent order is only partially filled, TP/SL orders remain inactive. * If you cancel a partially filled parent order, the TP/SL orders are also cancelled. * If the parent order is partially filled and then auto-cancelled due to insufficient margin, the TP/SL orders will still be placed — assuming a full fill. Summary: TP/SL orders tied to a parent order will only go live if the parent fully fills, or if it’s partially filled and then cancelled due to margin limits. If the order is manually cancelled mid-fill, the linked TP/SL will not go through. [PreviousTop up & Spend](https://basedapp.gitbook.io/docs/card/top-up-and-spend) [NextTrailing Stop Loss](https://basedapp.gitbook.io/docs/trading/trailing-stop-loss) Last updated 3 months ago --- # Top up & Spend | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F74IvNmvLODiOoLtUcsop%252Fimage.png%3Falt%3Dmedia%26token%3D54b62143-01a7-48af-a900-8386749f56a7&width=300&dpr=4&quality=100&sign=16f06c61&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FDXM4w7EYSh1pbpWuhq1W%252Fimage.png%3Falt%3Dmedia%26token%3D11155e38-c161-4adf-932f-f9f819e27295&width=300&dpr=4&quality=100&sign=e39365b&sv=2) To top up a BASED Visa card, you don’t need to off-ramp or preload fiat. Instead, the card auto-converts your crypto at the point of sale. Here’s how it works: * * * #### [](https://basedapp.gitbook.io/docs/card/top-up-and-spend#how-to-top-up-fund-your-based-card) How to Top Up / Fund Your BASED Card: 1. Deposit crypto into your BASED wallet * Supported networks: Solana, Arbitrum, Polygon, and Hyperliquid * Supported tokens: USDT, USDC, XSGD, and more 2. Use the card directly * When you tap your Visa card (physical or digital), BASED automatically converts your crypto into fiat in real time * No manual top-ups or off-ramps needed 3. Track balances & spending via the BASED mobile or web interface * * * #### [](https://basedapp.gitbook.io/docs/card/top-up-and-spend#key-benefits) Key Benefits: * No top-up fees * Spend directly from your on-chain balance * Works globally across 70M+ Visa merchants * Integrated with Apple Pay & Google Pay [PreviousCard Types](https://basedapp.gitbook.io/docs/card/card-types) [NextTake Profit / Stop Loss](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss) Last updated 2 months ago --- # Funding Rate | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) The funding rate is a periodic payment exchanged between traders holding long and short positions in perpetual contracts. Its primary purpose is to keep the perpetual contract price (mark price) closely aligned with the underlying spot index price. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FTgORKMwi0oX3Vzcw6dKC%252Fimage.png%3Falt%3Dmedia%26token%3D62aacfb5-9818-4cfc-8abc-5efa0cd75867&width=768&dpr=4&quality=100&sign=8b3b8fe&sv=2) * * * #### [](https://basedapp.gitbook.io/docs/trading/funding-rate#what-it-means) What It Means: * If the funding rate is positive: Traders holding long positions pay traders holding short positions. * If the funding rate is negative: Traders holding short positions pay traders holding long positions. This mechanism ensures that if the price of the perpetual diverges from spot (due to demand imbalance), there is a financial incentive for traders to take the opposite side, pulling prices back in line. * * * #### [](https://basedapp.gitbook.io/docs/trading/funding-rate#how-it-works-on-hyperliquid) How It Works on Hyperliquid: * Funding is calculated and settled every hour. This is more frequent than many other platforms, helping to maintain tighter alignment with the index price. * You only pay or receive funding if you’re holding a position at the funding timestamp. * The amount you pay/receive is proportional to your position size and the prevailing funding rate. * * * #### [](https://basedapp.gitbook.io/docs/trading/funding-rate#why-it-matters) Why It Matters: Funding rate directly affects your profit and loss (PnL) over time. Even if price doesn’t move, a high funding rate can eat into returns (if you’re paying), or enhance gains (if you’re receiving). [PreviousMargining](https://basedapp.gitbook.io/docs/trading/margining) [NextLiquidation](https://basedapp.gitbook.io/docs/trading/liquidation) Last updated 3 months ago --- # Desktop | BasedApp Docs Based is proud to introduce Based Desktop App, a platform created for Low-Latency Trades. The benefits of trading with desktop include: * 30% more performant than browser * Advanced trading orders exclusive to Desktop * Runs in the background without pausing * Native notifications on fills & liquidations Download Based Desktop App here: [http://based.one/desktop](http://based.one/desktop) [PreviousTelegram Bot](https://basedapp.gitbook.io/docs/based/telegram-bot) [NextAffiliate Program](https://basedapp.gitbook.io/docs/based/affiliate-program) Last updated 1 month ago --- # Based Cloud | BasedApp Docs We’re making it possible for anyone and any project to launch their very own exchange in under 5 minutes. No heavy dev work, no months of setup — just a few clicks to go live. With Based Cloud, you can: * Create a fully branded trading terminal with your own colors, logo, and layout * Enable plugins to customize functionality and features * Set your own fees and build a sustainable revenue stream * Provide your users with the full power of Hyperliquid’s infrastructure — unmatched speed, deep liquidity, and reliability #### [](https://basedapp.gitbook.io/docs/based/based-cloud#why-does-this-matter) Why does this matter? Because projects, communities, and NFT collections don’t need to be limited to someone else’s platform. With Based Cloud, you own the experience. You control the branding, the features, and the upside. Read more about Based Cloud: [https://medium.com/basedone/binance-cloud-try-based-cloud-c3428a957fb1](https://medium.com/basedone/binance-cloud-try-based-cloud-c3428a957fb1) Based Cloud Site: [https://based.one/cloud](https://based.one/cloud) If you’re a project owner, builder, or even an NFT project on Hyperliquid and want to give your community its very own trading terminal — reach out to us today via [Discord](https://discord.gg/basedapp) . [PreviousFees](https://basedapp.gitbook.io/docs/based/fees) [NextFunding Trading Account](https://basedapp.gitbook.io/docs/based/funding-trading-account) Last updated 1 month ago --- # Trailing Stop Loss | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) A trailing stop loss is a type of stop-loss order that moves with the market price, allowing you to lock in profits while still protecting against downside risk. Its one of the feature that makes us stand out within the Hyperliquid ecosystem and an added feature which Hyperliquid currently do not have. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FOUwEfe0wGQAglxQmRXLK%252Fimage.png%3Falt%3Dmedia%26token%3D52e50f1e-0ccd-4c91-a3f3-abbadeb3fa31&width=300&dpr=4&quality=100&sign=85cbef2c&sv=2)![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FMePS7bsvV4q2BhfX2lSH%252Fimage.png%3Falt%3Dmedia%26token%3D572090f6-a396-4c33-afd2-1309337799f2&width=300&dpr=4&quality=100&sign=aba2782d&sv=2) How it works: * Instead of setting a fixed stop-loss price, you set a trailing distance (e.g., $500 or 5%). * As the price moves in your favor, the stop price moves up (or down, for shorts) with it. * If the price reverses by the trailing amount, your position is automatically closed. Example (Long Position): * You buy ETH at $3,000 * You set a $200 trailing stop loss * Price rises to $3,400, the stop-loss trails up to $3,200 * If price drops from $3,400 to $3,200, the position is sold — locking in $200 profit Why Use It? * Protect profits without manually adjusting stop-loss levels * Automatically adapts to market moves * Great for trending markets or volatile assets like crypto [PreviousTake Profit / Stop Loss](https://basedapp.gitbook.io/docs/trading/take-profit-stop-loss) [NextMargining](https://basedapp.gitbook.io/docs/trading/margining) Last updated 2 months ago --- # Funding Trading Account | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FPG5o9ivPjjm5bzVKaGLK%252Fimage.png%3Falt%3Dmedia%26token%3Dc2c8a36a-594e-4d4c-bf97-a5d9e6f65de8&width=300&dpr=4&quality=100&sign=2da0d187&sv=2)![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FZ4364WifC4gugSPft7Hb%252Fimage.png%3Falt%3Dmedia%26token%3D8287f431-0f4f-4ca1-9b26-5734165d4d90&width=300&dpr=4&quality=100&sign=652f2ecf&sv=2) You can now fund your Hyperliquid trading account seamlessly via the BASED mobile or web app. Just tap “Add Funds” — we’ve integrated with [Unit on Hyperliquid](https://hyperunit.xyz/) to streamline onboarding and deposits. Hyperliquid users can: * Deposit _BTC, ETH, or SOL_ from their personal wallet or exchange account, directly to Hyperliquid. * Trade, transfer, or otherwise utilize these major assets, along with existing ones, on Hyperliquid's spot order book. * Withdraw assets directly to their preferred address on the respective asset’s native blockchain. Fast. Simple. On-chain. [PreviousBased Cloud](https://basedapp.gitbook.io/docs/based/based-cloud) [NextDepositing from Binance](https://basedapp.gitbook.io/docs/based/funding-trading-account/depositing-from-binance) Last updated 2 months ago --- # Liquidation | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FlLqB570677QQ7Y3v03JT%252Fimage.png%3Falt%3Dmedia%26token%3D6b65cbc1-2295-4744-8e9f-6fc7a665a55d&width=768&dpr=4&quality=100&sign=7b4f1ac8&sv=2) A liquidation occurs when a trader’s account equity drops below the required maintenance margin, which is set at 50% of the initial margin at maximum leverage. Depending on the asset, this margin can range from 1.25% (for 40x leverage) to 16.7% (for 3x leverage). When this threshold is breached: 1. The system attempts to close positions by placing market orders for the full position size. 2. If sufficient capital is recovered and margin requirements are restored, any leftover collateral stays with the trader. 3. If liquidation through the market fails and account equity falls below two-thirds of the maintenance margin, a backstop liquidation occurs through the Liquidator Vault. * Cross Margin: In backstop events, all cross margin and positions are transferred to the liquidator. If no isolated positions exist, the trader’s account equity becomes zero. * Isolated Margin: Only the isolated position and its margin are transferred. Other assets and cross positions remain unaffected. In backstop scenarios, maintenance margin is not returned to the trader — this buffer ensures liquidations remain profitable for the Liquidator Vault. To avoid backstop liquidation, traders are advised to use stop loss orders or manually exit before their mark price hits the liquidation threshold. * * * #### [](https://basedapp.gitbook.io/docs/trading/liquidation#mark-price-and-robust-liquidation) Mark Price & Robust Liquidation Hyperliquid (Basedapp uses HL systems) uses a mark price—an aggregated value based on both external CEX data and internal book state—making it more reliable than relying solely on a volatile order book price. This improves fairness and helps prevent unnecessary liquidations during market spikes. [PreviousFunding Rate](https://basedapp.gitbook.io/docs/trading/funding-rate) [NextEntry Price / PnL](https://basedapp.gitbook.io/docs/trading/entry-price-pnl) Last updated 3 months ago --- # Entry Price / PnL | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FklvuPNx9Ii4hmEaNzOrX%252Fimage.png%3Falt%3Dmedia%26token%3Db0b145a1-d0e2-4dd1-83d9-f2242601a24f&width=768&dpr=4&quality=100&sign=a28bf124&sv=2) #### [](https://basedapp.gitbook.io/docs/trading/entry-price-pnl#entry-price-and-pnl) Entry Price and PnL Entry price, unrealized PnL, and closed PnL are client-side calculations meant for user clarity — they are not part of the protocol’s on-chain accounting, which is instead based solely on margin (for perps) or balances (for spot) and executed trades. * * * #### [](https://basedapp.gitbook.io/docs/trading/entry-price-pnl#perpetuals-perps) Perpetuals (Perps) * A trade is considered opening if it increases the absolute size of your position — e.g., going longer while already long, or adding to a short. * A closing trade reduces your position size in the opposite direction. Entry Price Logic: * For opening trades, the entry price is recalculated using a size-weighted average of the current entry price and the new trade price. * For closing trades, the entry price remains unchanged. Unrealized PnL Formula: Unrealized PnL = side × (mark\_price − entry\_price) × position\_size Closed PnL Formula: Closed PnL = side × (exit\_price − entry\_price) × position\_size + fees #### [](https://basedapp.gitbook.io/docs/trading/entry-price-pnl#spot) Spot Spot PnL calculations follow similar logic to perps with a few key differences: * Buys are treated as opening trades, and sells as closing trades. * Transfers are treated as buys or sells at the current mark price. \*UBTC on Hyperliquid always matches the BTC held in custody, maintaining a 1:1 peg. [PreviousLiquidation](https://basedapp.gitbook.io/docs/trading/liquidation) [NextTypes of Order](https://basedapp.gitbook.io/docs/trading/types-of-order) Last updated 3 months ago --- # Card Types | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) Note: Card Signups are temporarily paused until further notice, as we are introducing a new line of cards. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FOdUJfGiwXAyzTJMmLJq1%252FScreenshot%25202025-07-16%2520at%25204.53.32%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D727a98a9-0bfa-436c-ad62-91417febf1c0&width=768&dpr=4&quality=100&sign=ecdd1584&sv=2) #### [](https://basedapp.gitbook.io/docs/card/card-types#spend-crypto-globally-with-based-visa-cards) Spend Crypto Globally with BASED Visa Cards BASED offers three tiers of Visa debit cards designed to let you spend crypto and stablecoins seamlessly, anywhere Visa is accepted worldwide — over 70 million merchants across 160+ countries. **Core Benefits (All Cards)** * Auto-convert crypto at point of sale — pay with USDT, USDC or major tokens without needing to off-ramp to fiat . * No top-up fees for the supported stablecoins. * Compatible with Apple Pay and Google Pay — instant digital wallet integration . * Deposit easily via Solana, Arbitrum, Polygon, or Hyperliquid network . ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FZcPC3j0rwedjo7GyBKOS%252FScreenshot%25202025-07-16%2520at%25204.54.21%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3Ddd268a3a-4ddc-4819-8fb4-627dfff4c4b4&width=768&dpr=4&quality=100&sign=b006e3a1&sv=2) #### [](https://basedapp.gitbook.io/docs/card/card-types#why-choose-based-cards) Why Choose BASED Cards? 1. Instant Crypto Spending Eliminate top-up and off-ramp delays — just tap and go. 2. Earn While You Spend & Trade Tiered perks enable higher rewards for power users. 3. Global, Multi-Network Access Spend anywhere Visa is accepted; deposits via multiple blockchains ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FKO7Kt9jAI3Z7CTCUBLQh%252FScreenshot%25202025-08-21%2520at%25202.46.18%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3Db8fca8ed-ec82-42a4-9c61-18caf605acde&width=768&dpr=4&quality=100&sign=a9796c1c&sv=2) [PreviousBased XP / Gold](https://basedapp.gitbook.io/docs/based/based-xp-gold) [NextTop up & Spend](https://basedapp.gitbook.io/docs/card/top-up-and-spend) Last updated 1 month ago --- # Based XP / Gold | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) **Season 1 – XP System** 🔸 Season 1 was based entirely on the XP system. 🔸 Users earned XP through activity and participation on Based. 🔸 All Season 1 XP is now locked in stone, no new XP will be issued. 🔸 Holders of Season 1 XP will be eligible for airdrop allocation of the Based Token. 🔸 The exact percentage and distribution details will be announced later. * * * **Season 2 – Based Gold System** 🔸 Season 2 introduces Based Gold, which replaces XP as the new progression system. 🔸 Each epoch lasts 3 days. 🔸 A fixed 10,000,000 Based Gold will be issued every epoch. 🔸 Other Based Gold allocations may be issued out for HIP-3 partners, or via Blind-boxes. 🔸 It represents a dynamic and ongoing incentive system for active users. 🔸 Categories of activities that earn Gold (exact weightage will not be disclosed): * Gold allocated for trading related activities * Gold allocated for affiliate activities * Gold allocated for PUP holders _For each of these activities, there are some specific ratios and filters being applied into the formula, and will not be revealed._ For affiliates, both the referrer and referee will get a share of Gold * If you refer a friend, they’ll receive a 10% boost in their daily Based Gold allocation. You’ll also earn the same bonus amount in Based Gold, matching what your friend received as their referral bonus. [PreviousDepositing from Binance](https://basedapp.gitbook.io/docs/based/funding-trading-account/depositing-from-binance) [NextCard Types](https://basedapp.gitbook.io/docs/card/card-types) Last updated 14 days ago --- # Depositing from Binance | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) You can fund your Hyperliquid trading account seamlessly via the BASED mobile or web app. Here's a step-by-step guide on how to do it with your Binance Account. Step 1: Click deposit, as shown in the top right hand corner. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252Ftf5hS8h66snYahUPR4KE%252Fimage.png%3Falt%3Dmedia%26token%3D1f38d019-3f6b-4d40-b681-c72c7c6b4b22&width=768&dpr=4&quality=100&sign=58627ea&sv=2) Step 2: Select your preferred chain and token of choice (In this case, USDC on Arbitrum). ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FFpHyLWd7UCyTZVRZU1FC%252Fimage.png%3Falt%3Dmedia%26token%3Da5e21406-c353-4f76-899c-6ef69625a2d8&width=768&dpr=4&quality=100&sign=3021fc30&sv=2) Step 3: Copy the wallet address. This is the wallet address to send funds to. Step 4: Head to Binance, copy the wallet address along with the right token in the right chain. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FqFRVEJV9WtHIx38ernTE%252Fimage.png%3Falt%3Dmedia%26token%3D8caa1c98-7ace-4ff0-8885-1d64ea51b790&width=768&dpr=4&quality=100&sign=566868bd&sv=2) Step 5: Once done, give it a couple of minutes for the deposit to arrive. Then, you just have to click the deposit button again and the amount should show up in the same view as the screenshot in Step 2. Just click deposit and you're done! [PreviousFunding Trading Account](https://basedapp.gitbook.io/docs/based/funding-trading-account) [NextBased XP / Gold](https://basedapp.gitbook.io/docs/based/based-xp-gold) Last updated 2 months ago --- # Types of Order | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FcGyU34adb2KF9C299UOa%252FScreenshot%25202025-07-16%2520at%25207.15.13%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D7c143f12-4fd7-4ac5-ae83-82e24b3243f0&width=768&dpr=4&quality=100&sign=d7ee4ca5&sv=2) **Basic Order Types** * Market Order: Executes immediately at the current market price. * Limit Order: Executes at a specified price or better. * Stop Market Order: Becomes a market order once the asset reaches the chosen stop price. Commonly used to limit losses or secure profits. * Stop Limit Order: Becomes a limit order once the stop price is hit. * Scale Order: Places a series of limit orders across a defined price range. * TWAP (Time-Weighted Average Price): Splits a large order into smaller chunks, executed every 30 seconds to minimize market impact. Each suborder is limited to a maximum slippage of 3%. * * * **TWAP Mechanics** * The TWAP algorithm targets execution based on elapsed time relative to total order duration. * A new suborder is placed every 30 seconds. * If early suborders don’t fill due to low liquidity or wide spreads, later suborders will increase in size (up to 3x the standard size) to catch up — while still respecting the 3% slippage cap. * Like regular market orders, TWAP suborders won’t execute during post-only periods (e.g. during network upgrades). * * * #### [](https://basedapp.gitbook.io/docs/trading/types-of-order#additional-order-options) Additional Order Options * Reduce Only: Ensures the order only reduces an existing position, never increases or flips it. * Good Til Canceled (GTC): Stays active on the order book until filled or manually canceled. * Post Only (ALO): Adds the order to the book without matching immediately — ensures maker-only execution. * Immediate or Cancel (IOC): Executes all or part of the order immediately; cancels any unfilled portion. * Take Profit (TP): Triggers a market order when the target price is reached, helping lock in gains. * Stop Loss (SL): Triggers a market order when the price hits a specified loss threshold, limiting downside. > TP and SL orders are typically used to automate trade exits. You can customize the trigger price, limit price, and the portion of your position to be affected. [PreviousEntry Price / PnL](https://basedapp.gitbook.io/docs/trading/entry-price-pnl) [NextTWAP](https://basedapp.gitbook.io/docs/trading/twap) Last updated 3 months ago --- # FairShare | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) **Example: FairShare Launchpad** * A project is raising 1,000 UP tokens at 1 UP = 1 HYPE. * This means the target raise = 1,000 HYPE. Participants: * Alice commits 500 HYPE * Bob commits 1,500 HYPE * Carol commits 3,000 HYPE * Dave commits 5,000 HYPE Total committed = 10,000 HYPE But since the raise target is only 1,000 HYPE, the sale is 10x oversubscribed. Allocations: * Alice: 500 ÷ 10,000 = 5% → gets 50 UP * Bob: 1,500 ÷ 10,000 = 15% → gets 150 UP * Carol: 3,000 ÷ 10,000 = 30% → gets 300 UP * Dave: 5,000 ÷ 10,000 = 50% → gets 500 UP Refunds (FairShare): Each participant gets their leftover HYPE refunded automatically: * Alice committed 500, used 50 → refunded 450 * Bob committed 1,500, used 150 → refunded 1,350 * Carol committed 3,000, used 300 → refunded 2,700 * Dave committed 5,000, used 500 → refunded 4,500 [PreviousParticipate](https://basedapp.gitbook.io/docs/launchpad/participate) [NextBased MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp) Last updated 1 month ago --- # TWAP | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) [](https://basedapp.gitbook.io/docs/trading/twap#what-is-twap) What is TWAP? --------------------------------------------------------------------------------- TWAP (Time-Weighted Average Price) is an order execution strategy that breaks a large order into smaller trades, executed at regular intervals over a set duration. Instead of placing one large order that may impact price, TWAP helps smooth execution, reducing slippage and market impact. ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252Fm8YFJAqRtNjxAmmeCfrt%252FScreenshot%25202025-08-24%2520at%252010.10.49%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3D9da90e9b-b79f-4b37-8ce8-2c9f6a85395a&width=768&dpr=4&quality=100&sign=279d7c60&sv=2) * * * ### [](https://basedapp.gitbook.io/docs/trading/twap#how-twap-works) How TWAP Works 1. Order Size – The user specifies the total amount to buy/sell. 2. Duration – The time over which the order will be executed. 3. Intervals – The order is split into smaller chunks, executed evenly at each interval. 4. Execution – Orders are placed automatically until the total size is filled. For example: Buying 100 ETH over 1 hour with 12 intervals means the system executes ~8.33 ETH every 5 minutes. * * * [](https://basedapp.gitbook.io/docs/trading/twap#reduce-only-mode) Reduce-Only Mode ---------------------------------------------------------------------------------------- When Reduce-Only is enabled: * The TWAP will only reduce your current position. * It prevents the strategy from flipping your position (e.g., closing a long and accidentally opening a short). * If no position exists, no orders are executed. This ensures TWAP is used strictly for scaling out, not scaling in. * * * [](https://basedapp.gitbook.io/docs/trading/twap#randomize-mode) Randomize Mode ------------------------------------------------------------------------------------ When Randomize is enabled: * The system slightly varies the size and/or timing of each order. * This makes execution less predictable and harder to track. * Helps mitigate predatory algorithms or bots attempting to anticipate TWAP orders. Example: Instead of executing exactly 10 ETH every 5 minutes, the bot may execute 8.5 ETH, then 11.2 ETH, with timing offsets of a few seconds. * * * [](https://basedapp.gitbook.io/docs/trading/twap#privacy-twap) Privacy TWAP -------------------------------------------------------------------------------- Normal TWAPs are executed fully on-chain, which makes them visible to everyone. Large players (whales) dislike this because: * Their execution path can be tracked. * They are vulnerable to frontrunning and other predatory trading behavior. Privacy TWAP executes trades client-side, directly inside the user’s browser: * Local Execution – Orders are created and sent from your browser only. * No Visibility – Neither the trading terminal nor external observers can see or frontrun your order path. * True Privacy – Even we, as the trading platform, cannot track or manipulate your order flow. Important Notes * Since orders run locally, if you refresh or close the terminal, the TWAP pauses. * Execution resumes only while the terminal/browser is active. This design ensures maximum privacy and security for users executing large trades. [PreviousTypes of Order](https://basedapp.gitbook.io/docs/trading/types-of-order) [NextParticipate](https://basedapp.gitbook.io/docs/launchpad/participate) Last updated 1 month ago --- # Participate | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) The rationale behind our launchpad is simple: it creates value for both projects and users. * For projects — Launching with us provides instant visibility and wide distribution across the Hyperliquid ecosystem. They gain access to a strong user base, liquidity, and credibility from being featured on our platform. * For users — It opens the door to exclusive token launches they wouldn’t normally have access to. By participating early, they benefit from being part of high-potential projects from the very start. * For loyal users — A portion of each sale will be whitelist-only, ensuring our long-term supporters get priority access and rewards for their commitment. Sales of token will be split into 2 section 1. Private Sales to qualified participants. Participants can commit HYPE up to the maximum commit limit if they are whitelisted. 2. Public Sales: Upheaval launchpad employs the "Fairshare" sale technique, where customers can subscribe to the launchpad for any amount they choose. When the sale finishes, tokens are allocated depending on the percentage of funds they provide compared to all funds supplied by users. Users receive any remaining HYPE tokens. [PreviousTWAP](https://basedapp.gitbook.io/docs/trading/twap) [NextFairShare](https://basedapp.gitbook.io/docs/launchpad/fairshare) Last updated 1 month ago --- # Fees | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) [](https://basedapp.gitbook.io/docs/based/fees#we-follow-hyperliquid-fee-model) We follow Hyperliquid Fee model -------------------------------------------------------------------------------------------------------------------- Fees are based on your rolling 14 day volume and are assessed at the end of each day in UTC. Sub-account volume counts toward the master account and all sub-accounts share the same fee tier. Vault volume is treated separately from the master account. Referral rewards apply for a user's first $1B in volume and referral discounts apply for a user's first $25M in volume. Maker rebates are paid out continuously on each trade directly to the trading wallet. Users can claim referral rewards from the Referrals page. There are separate fee schedules for perps vs spot. Perps and spot volume will be counted together to determine your fee tier, and spot volume will count double toward your fee tier. i.e., `(14d weighted volume) = (14d perps volume) + 2 * (14d spot volume)` #### [](https://basedapp.gitbook.io/docs/based/fees#perps-fee-tiers) Perps fee tiers Base rate Diamond Platinum Gold Silver Bronze Wood Tier 14d weighted volume ($) Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker 0 0.045% 0.015% 0.0270% 0.0090% 0.0315% 0.0105% 0.0360% 0.0120% 0.0383% 0.0128% 0.0405% 0.0135% 0.0428% 0.0143% 1 \>5M 0.040% 0.012% 0.0240% 0.0072% 0.0280% 0.0084% 0.0320% 0.0096% 0.0340% 0.0102% 0.0360% 0.0108% 0.0380% 0.0114% 2 \>25M 0.035% 0.008% 0.0210% 0.0048% 0.0245% 0.0056% 0.0280% 0.0064% 0.0298% 0.0068% 0.0315% 0.0072% 0.0333% 0.0076% 3 \>100M 0.030% 0.004% 0.0180% 0.0024% 0.0210% 0.0028% 0.0240% 0.0032% 0.0255% 0.0034% 0.0270% 0.0036% 0.0285% 0.0038% 4 \>500M 0.028% 0.000% 0.0168% 0.0000% 0.0196% 0.0000% 0.0224% 0.0000% 0.0238% 0.0000% 0.0252% 0.0000% 0.0266% 0.0000% 5 \>2B 0.026% 0.000% 0.0156% 0.0000% 0.0182% 0.0000% 0.0208% 0.0000% 0.0221% 0.0000% 0.0234% 0.0000% 0.0247% 0.0000% 6 \>7B 0.024% 0.000% 0.0144% 0.0000% 0.0168% 0.0000% 0.0192% 0.0000% 0.0204% 0.0000% 0.0216% 0.0000% 0.0228% 0.0000% #### [](https://basedapp.gitbook.io/docs/based/fees#spot-fee-tiers) Spot fee tiers Spot Base rate Diamond Platinum Gold Silver Bronze Wood Tier 14d weighted volume ($) Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker Taker Maker 0 0.070% 0.040% 0.0420% 0.0240% 0.0490% 0.0280% 0.0560% 0.0320% 0.0595% 0.0340% 0.0630% 0.0360% 0.0665% 0.0380% 1 \>5M 0.060% 0.030% 0.0360% 0.0180% 0.0420% 0.0210% 0.0480% 0.0240% 0.0510% 0.0255% 0.0540% 0.0270% 0.0570% 0.0285% 2 \>25M 0.050% 0.020% 0.0300% 0.0120% 0.0350% 0.0140% 0.0400% 0.0160% 0.0425% 0.0170% 0.0450% 0.0180% 0.0475% 0.0190% 3 \>100M 0.040% 0.010% 0.0240% 0.0060% 0.0280% 0.0070% 0.0320% 0.0080% 0.0340% 0.0085% 0.0360% 0.0090% 0.0380% 0.0095% 4 \>500M 0.035% 0.000% 0.0210% 0.0000% 0.0245% 0.0000% 0.0280% 0.0000% 0.0298% 0.0000% 0.0315% 0.0000% 0.0333% 0.0000% 5 \>2B 0.030% 0.000% 0.0180% 0.0000% 0.0210% 0.0000% 0.0240% 0.0000% 0.0255% 0.0000% 0.0270% 0.0000% 0.0285% 0.0000% 6 \>7B 0.025% 0.000% 0.0150% 0.0000% 0.0175% 0.0000% 0.0200% 0.0000% 0.0213% 0.0000% 0.0225% 0.0000% 0.0238% 0.0000% #### [](https://basedapp.gitbook.io/docs/based/fees#staking-tiers) Staking tiers Tier HYPE staked Trading fee discount Wood \>10 5% Bronze \>100 10% Silver \>1,000 15% Gold \>10,000 20% Platinum \>100,000 30% Diamond \>500,000 40% #### [](https://basedapp.gitbook.io/docs/based/fees#maker-rebates) Maker rebates Tier 14d weighted maker volume Maker fee 1 \>0.5% \-0.001% 2 \>1.5% \-0.002% 3 \>3.0% \-0.003% **Builder Fees** A small builder fee is applied on top of trading fees: * 0.025% for perpetuals * 0.1% for spot sells No builder fees are charged on spot buys. The majority of these fees (up to 76%) are redistributed as affiliate rewards to our community. Refer to affiliate program rewards [here](https://basedapp.gitbook.io/docs/~/revisions/5GW8FKtVkWPXTy9p5mTK/hyperapp/affiliate-program) [PreviousAffiliate Program](https://basedapp.gitbook.io/docs/based/affiliate-program) [NextBased Cloud](https://basedapp.gitbook.io/docs/based/based-cloud) Last updated 2 months ago --- # Switching over from Legacy to HyperApp | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) This page is only relevant for users who signed up for BASED before July 2025. BASED accounts created before July 2025 are by considered as "Legacy" account. If you have an account then, you would most likely have logged in from app.based.one or have the PWA added to your phone. This is the wallet that was connected to a Safe wallet. Moving forward, we are transiting to a simpler architecture and there may be some action required on your end. [](https://basedapp.gitbook.io/docs/guides/switching-over-from-legacy-to-hyperapp#what-are-the-technical-differences) **What are the technical differences?** ------------------------------------------------------------------------------------------------------------------------------------------------------------------ When we launched in 2023, we introduced a smart contract wallet (powered by Safe) that is connected to a Visa Debit Card. We pioneered the first non-custodial Visa Debit card back in 2023. Users could login to BASED either by connecting through Web3 Wallets or by using Magic.link, an authentication provider. But since July 2025, we are introduce a shift to a simpler architecture by completely removing the smart contract wallet layer. Users could still use the simple Web3 wallet to connect or to use social logins. We also took the opportunity to switch from Magic to Privy for the authentication. On the new HyperApp, you could log in with Google or Email. This service is provided by Privy (now part of Stripe). We no longer support phone number logins. This change however has some implications as many of our Visa card services was tied to the Safe smart contract layer. To continue using BASED Visa Card on the new apps, you will have to go through a one-time setup process. [](https://basedapp.gitbook.io/docs/guides/switching-over-from-legacy-to-hyperapp#migration) Migration ----------------------------------------------------------------------------------------------------------- To facilitate the change, our engineers work on a smooth migration flow which automatically creates a linkage from the legacy account (Safe wallet) to the new HyperApp wallet. If you have logged in to BASED with an email or Google, you could simply log in with the same account and the linkage will be done automatically. ### [](https://basedapp.gitbook.io/docs/guides/switching-over-from-legacy-to-hyperapp#link-card-manually) Link Card Manually Note: Linking card accounts require logging in via email on the app. You will have to link card manually if you Logged in to legacy BASED with: * Web3 Wallet such as Metamask or Rabby * Phone number * An email address that you no longer wish to use anymore Go to the "Cash" tab and click on "Link Existing Card" ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252Fzn1a8GqAQ6HlJxKXUhZo%252FIMG_2461.jpg%3Falt%3Dmedia%26token%3D53931f72-eabb-4ec4-9939-2413a636267f&width=768&dpr=4&quality=100&sign=7ca3f99d&sv=2) It will route you to a browser where you have to connect to the legacy BASED. Click on "Link Card" ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FCg01kxpJVxH68FcaQRPs%252FIMG_2462.PNG%3Falt%3Dmedia%26token%3Dc0324fba-3d15-49e9-a1f0-7e518d9c709b&width=768&dpr=4&quality=100&sign=618fbd31&sv=2) Your card is successfully linked! ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FYBsfli98HsZPSKgSQvXP%252FIMG_2463.PNG%3Falt%3Dmedia%26token%3Dd64594bd-4e0d-448e-ae52-ff611f13f5f0&width=768&dpr=4&quality=100&sign=8e8b492b&sv=2) [PreviousAPI Traders](https://basedapp.gitbook.io/docs/developers/api-traders) [NextAdding Agent Wallet](https://basedapp.gitbook.io/docs/guides/adding-agent-wallet) Last updated 1 month ago --- # Builder-on-Builder Program | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FRXtyTgvcWaXYfkkBD1Ud%252FScreenshot%25202025-08-04%2520at%25204.32.47%25E2%2580%25AFPM.png%3Falt%3Dmedia%26token%3Db73c737f-cc05-4221-9091-9d293c2eda42&width=768&dpr=4&quality=100&sign=ba27594&sv=2) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#builder-on-builder-program-by-based) Builder-on-Builder Program by BASED What it is: A pioneering initiative on Hyperliquid that allows external teams and developers to build directly on top of BASED infrastructure — creating the first true sub-ecosystem within Hyperliquid. * * * #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#what-builders-can-build) What Builders Can Build Builders can plug into BASED infrastructure to create: * Custom trading tools and bots * Strategy layers or smart order routing * Community or social trading interfaces * Analytics dashboards and data products * On-chain automation, trading signals, or wallets that route through BASED * * * #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#why-build-on-basedapp) Why Build on BasedApp * Ready-to-use infrastructure — skip building core UI, wallet, or order routing * Instant user access — tap into BasedApp’s growing trader base * Revenue sharing — earn through builder fees and affiliate incentives (earn up to 76% of affiliate fees from trading volume that comes from you) * Faster go-to-market — launch and iterate quickly * Network effects — benefit from an integrated ecosystem of users and products * * * #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#the-bigger-vision) The Bigger Vision Just like protocols build on blockchains, BasedApp enables teams to build on applications. This creates a new layer of app-native ecosystems — where tools, bots, and strategies thrive on top of existing platforms. This is the first builder-on-builder flywheel on Hyperliquid. * * * #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#who-its-for) Who It’s For * Trading tool developers * Quant or strategy teams * Smart contract engineers * Product builders with UI/UX ideas * Developers who want to build useful utilities for Hyperliquid traders * * * #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program#interested-in-building) Interested in Building? Reach out to the BasedApp team via [Discord](https://discord.com/invite/basedapp) or [Twitter](https://x.com/basedappHQ) if you currently already have an APPLICATION with users or a DAPP that's currently running and would like to integrate BasedApp into your platform to earn affiliate fees from users using BasedApp to trade. If you currently do not have a platform and would like to build one (eg a telegram bot) that runs with BasedApp on the backend, feel free to reach out to us too. We are not HIRING builders or giving out grants, we are looking for deeper partnerships and integrations. We’re actively looking to support and grow this new wave of Hyperliquid-native builders. Let’s build the future of on-chain trading — together. [PreviousReact Sample MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps/react-sample-miniapp) [NextBuilder API access](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access) Last updated 2 months ago --- # Adding Agent Wallet | BasedApp Docs 1. Visit [https://app.based.one/accounts](https://app.based.one/accounts) on your desktop, 2. Click Add Hyperliquid account, connect your metamask/browser wallet, 3. Enter a nickname (eg. "BasedApp") and add, 4. Scan QR with our mobile app (Home, Click display picture, Create new wallet, Link to hyperliquid wallet), 5. Now you can trade with multiple accounts on app and web! [PreviousSwitching over from Legacy to HyperApp](https://basedapp.gitbook.io/docs/guides/switching-over-from-legacy-to-hyperapp) Last updated 1 month ago --- # Monetization | BasedApp Docs Developers can monetize their apps by aligning with desirable outcomes for Based users: * Enhance Based traders' edge * Increase Based terminal screen time and stickiness * Provide an out of the world experience, create something never seen before ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/monetization#monetization-channels) Monetization channels This section will evolve over time as we figure out more meaningful ways to provide monetization channels for developers on Based terminal. For the time-being, there are 2 main channels of doing so: * **CTA based:** When orders are placed and executed via your mini-app, the trade will be attributed to your app. In doing so, we will share a portion of fees to your app. * **Session based:** If your mini-app is open in the **MiniApp side panel** when users are placing trades, these trades are attributed to the trading session, and you will be accorded a portion of fees to your app. **Revenue Share for App marketplace** Early Teams (First Five Developers): Developer receives 30% of Based Platform Fees. Based Platform Fees are defined as the 2.5 bps builder fees charged by Based on top of Hyperliquid. Developer share is calculated on gross revenue before affiliate payouts. Subsequent Developers (Beyond First Five): Revenue share is determined by Monthly Trading Volume attributed to the developer’s app: First $100M monthly volume: 10% $100M – $500M monthly volume: 20% $500M+ monthly volume: 30% For more information on fee sharing schedule, reach out to the Based team at [https://based.one/contact](https://based.one/contact) [PreviousMiniApp API](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api) [NextSample Apps](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps) Last updated 1 month ago --- # Sample Apps | BasedApp Docs This section showcases a few different sample usage scenarios. [PreviousMonetization](https://basedapp.gitbook.io/docs/developers/based-miniapp/monetization) [NextHTML Sample MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps/html-sample-miniapp) Last updated 1 month ago --- # API Traders | BasedApp Docs API traders can execute trades via hyperliquid [exchange](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#place-an-order) endpoints with Based builder code and client id, allowing API trades to earn XP. Based builder wallet: Copy 0x1924b8561eeF20e70Ede628A296175D358BE80e5 Recommended builder fee: _0.025%_ (perp), _0.1%_ (spot) Client ID (cloid): Copy 0xba5ed11067f2cc08ba5ed10000ba5ed1 _Sample perp order:_ Copy { "action": { "type": "order", "orders": [\ {\ "a": 0,\ "b": true,\ "p": "111951",\ "s": "0.0012",\ "r": false,\ "t": {\ "limit": {\ "tif": "Gtc"\ }\ },\ "c": "0xba5ed11067f2cc08ba5ed10000ba5ed1"\ }\ ], "grouping": "na", "builder": { "b": "0x1924b8561eef20e70ede628a296175d358be80e5", "f": 25 } }, "nonce": .., "signature": { ... } } 901B [api-trader.md](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2FeaTxt5iKjXA6LrYOHddg%2Fapi-trader.md?alt=media&token=65e38d8a-b251-414c-ac69-baa2955fa5db) Download[Open](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2FeaTxt5iKjXA6LrYOHddg%2Fapi-trader.md?alt=media&token=65e38d8a-b251-414c-ac69-baa2955fa5db) [PreviousBuilder API access](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access) [NextSwitching over from Legacy to HyperApp](https://basedapp.gitbook.io/docs/guides/switching-over-from-legacy-to-hyperapp) Last updated 1 month ago --- # Builder API access | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#methodology) Methodology * We use actual Hyperliquid builder trade data published by Hyperliquid, which is subject to a 48-hour time lag. * To provide near real-time accuracy, we fill in the most recent 48-hour gap using our own live trade tracking system, which may carry a small margin of error. * Important: When calculating commissions, we do not use the real-time (rolling) data. Only confirmed on-chain data is used once it becomes available through Hyperliquid’s official stream. [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#builders-referrals-api-documentation) Builders Referrals API Documentation ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This API provides access to referral data and trading volume information for specific referral codes. All endpoints are read-only and require API key authentication. ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#base-url) Base URL Copy https://app.based.one/api/builders/referrals ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#authentication) Authentication All API requests must include a valid API key in the request headers. #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#header-required) Header Required Copy x-api-key: YOUR_API_KEY #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#authentication-error-response) Authentication Error Response Copy { "error": "Invalid or missing API key" } * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-1.-get-all-referrals-by-code) 1\. Get All Referrals by Code Retrieve a complete list of all referrals (tier 1, 2, and 3) under a specific referral code with their trading performance and commission data. #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#endpoint) Endpoint Copy GET /api/builders/referrals/[code] #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#parameters) Parameters * `code` (path parameter, required): The referral code to query #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#query-parameters) Query Parameters * `sortBy` (optional): Sort field - `registrationDate`, `totalTraded`, `commissionEarned` (default: `registrationDate`) * `sortDirection` (optional): Sort direction - `asc`, `desc` (default: `desc`) * `tier` (optional): Filter by tier - `all`, `tier1`, `tier2`, `tier3` (default: `all`) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-request) Sample Request Copy curl -X GET "https://app.based.one/api/builders/referrals/ABC123?sortBy=totalTraded&sortDirection=desc&tier=tier1" \ -H "x-api-key: YOUR_API_KEY" #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-response) Sample Response Copy { "success": true, "data": { "referralCode": "ABC123", "referralOwner": { "username": "trader_pro", "address": "0x1234567890abcdef1234567890abcdef12345678" }, "referrals": [\ {\ "address": "0xabcdef1234567890abcdef1234567890abcdef12",\ "registrationDate": "2024-01-15T10:30:00.000Z",\ "totalTraded": 15750.25,\ "commissionEarned": 945.02,\ "builderFees": 1575.03,\ "tier": 1,\ "commissionRate": 60\ },\ {\ "address": "0x9876543210fedcba9876543210fedcba98765432",\ "registrationDate": "2024-02-01T14:20:00.000Z",\ "totalTraded": 8420.50,\ "commissionEarned": 101.05,\ "builderFees": 842.05,\ "tier": 2,\ "commissionRate": 12\ }\ ], "summary": { "tier1Count": 15, "tier2Count": 8, "tier3Count": 3, "totalTier1Commission": 2450.75, "totalTier2Commission": 245.30, "totalTier3Commission": 48.15, "commissionRates": { "tier1": 60, "tier2": 12, "tier3": 4 } } } } * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-2.-get-30-day-rolling-volume-by-code) 2\. Get 30-Day Rolling Volume by Code Retrieve referral data showing only the last 30 days of trading volume and commission earnings. #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#endpoint-1) Endpoint Copy GET /api/builders/referrals/volume_30d/[code] #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#parameters-1) Parameters * `code` (path parameter, required): The referral code to query #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#query-parameters-1) Query Parameters * `sortBy` (optional): Sort field - `registrationDate`, `totalTraded`, `commissionEarned` (default: `registrationDate`) * `sortDirection` (optional): Sort direction - `asc`, `desc` (default: `desc`) * `tier` (optional): Filter by tier - `all`, `tier1`, `tier2`, `tier3` (default: `all`) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-request-1) Sample Request Copy curl -X GET "https://app.based.one/api/builders/referrals/volume_30d/ABC123" \ -H "x-api-key: YOUR_API_KEY" #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-response-1) Sample Response Copy { "success": true, "data": { "referralCode": "ABC123", "referralOwner": { "username": "trader_pro", "address": "0x1234567890abcdef1234567890abcdef12345678" }, "period": { "startDate": "2024-12-06T01:45:59.378Z", "endDate": "2025-01-05T01:45:59.378Z", "days": 30 }, "referrals": [\ {\ "address": "0xabcdef1234567890abcdef1234567890abcdef12",\ "registrationDate": "2024-01-15T10:30:00.000Z",\ "totalTraded": 5240.75,\ "commissionEarned": 314.45,\ "builderFees": 524.08,\ "tier": 1,\ "commissionRate": 60\ }\ ], "summary": { "totalVolume": 12450.50, "totalCommission": 745.25, "tier1Count": 12, "tier2Count": 5, "tier3Count": 2, "totalTier1Commission": 620.30, "totalTier2Commission": 98.45, "totalTier3Commission": 26.50, "commissionRates": { "tier1": 60, "tier2": 12, "tier3": 4 } } } } * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-3.-get-individual-user-volume-by-address) 3\. Get Individual User Volume by Address Retrieve detailed trading volume and commission data for a specific user address under a referral code, including trade history and asset breakdown. #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#endpoint-2) Endpoint Copy GET /api/builders/referrals/[code]/user/[address] #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#parameters-2) Parameters * `code` (path parameter, required): The referral code to query * `address` (path parameter, required): The wallet address of the specific user #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#query-parameters-2) Query Parameters * `days` (optional): Number of days to look back (default: `30`) * `includeAllTime` (optional): Set to `true` to get all-time data instead of rolling window (default: `false`) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-request-2) Sample Request Copy curl -X GET "https://basedapp.io/api/builders/referrals/ABC123/user/0xabcdef1234567890abcdef1234567890abcdef12?days=7" \ -H "x-api-key: YOUR_API_KEY" #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#sample-response-2) Sample Response Copy { "success": true, "data": { "referralCode": "ABC123", "referralOwner": { "username": "trader_pro", "address": "0x1234567890abcdef1234567890abcdef12345678" }, "user": { "address": "0xabcdef1234567890abcdef1234567890abcdef12", "registrationDate": "2024-01-15T10:30:00.000Z", "tier": 1, "commissionRate": 60 }, "period": { "type": "rolling_days", "days": 7, "startDate": "2024-12-29T01:49:03.790Z", "endDate": "2025-01-05T01:49:03.790Z" }, "summary": { "totalVolume": 2450.75, "totalBuilderFees": 61.27, "totalCommission": 36.76, "tradeCount": 15, "assetBreakdown": { "BTC": { "volume": 1500.50, "builderFees": 37.51, "commission": 22.51, "tradeCount": 8 }, "ETH": { "volume": 950.25, "builderFees": 23.76, "commission": 14.25, "tradeCount": 7 } } }, "trades": [\ {\ "source": "TraderTrade",\ "tradeTime": "2025-01-05T01:30:00.000Z",\ "volume": 250.50,\ "builderFee": 6.26,\ "commissionEarned": 3.76,\ "coin": "BTC",\ "side": "B"\ },\ {\ "source": "BuilderTrade",\ "tradeTime": "2025-01-04T18:45:00.000Z",\ "volume": 180.25,\ "builderFee": 4.51,\ "commissionEarned": 2.70,\ "coin": "ETH",\ "side": "S"\ }\ ] } } * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#error-responses) Error Responses All endpoints return consistent error responses: #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-401-unauthorized) 401 Unauthorized Copy { "error": "Invalid or missing API key" } #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-400-bad-request) 400 Bad Request Copy { "error": "Referral code is required" } #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-403-forbidden) 403 Forbidden Copy { "error": "User is not a referral under this referral code" } #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-404-not-found) 404 Not Found Copy { "error": "Referral code not found" } #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#id-500-internal-server-error) 500 Internal Server Error Copy { "error": "An error occurred while fetching referrals" } * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#data-definitions) Data Definitions #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#commission-rates) Commission Rates * **Tier 1** (Direct referrals): 60% of builder fees * **Tier 2** (Sub-referrals): 12% of builder fees * **Tier 3** (Sub-sub-referrals): 4% of builder fees #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#data-sources) Data Sources * **BuilderTrade**: Historical trading data (cleaned, up to cutoff date) * **TraderTrade**: Recent trading data (real-time, from cutoff date onwards) #### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#volume-calculation) Volume Calculation All volume figures represent the total USD value of trades (price × size) executed by the referral users within the specified time period. * * * ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#getting-api-access) Getting API Access To obtain an API key for accessing these endpoints, please contact the development team. API keys are issued for legitimate business use cases. ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#rate-limits) Rate Limits These endpoints currently have no rate limits, but reasonable usage is expected. For high-volume integrations, please contact support. ### [](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program/builder-api-access#support) Support For API support, API key requests, or questions, please contact the development team. [PreviousBuilder-on-Builder Program](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program) [NextAPI Traders](https://basedapp.gitbook.io/docs/developers/api-traders) Last updated 2 months ago --- # Based MiniApp | BasedApp Docs ![Page cover](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252F1PgFTNm4rLJauxQszo0u%252FIMG_9849.PNG%3Falt%3Dmedia%26token%3D0e9bb1a9-af56-46ce-ae51-4404f627c20e&width=1248&dpr=4&quality=100&sign=28a1f391&sv=2) [](https://basedapp.gitbook.io/docs/developers/based-miniapp#introduction-to-based.one-miniapps) Introduction to Based.One MiniApps ---------------------------------------------------------------------------------------------------------------------------------------- Welcome to the Based.One MiniApp ecosystem! This guide will introduce you to the concepts, capabilities, and possibilities of building mini-applications for the Based.One trading terminal. The API specification will evolve rapidly as we work with developers to figure out what APIs they need, and remove redundant ones to limit scope. ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#what-are-miniapps) What Are MiniApps? MiniApps are lightweight, focused applications that run directly within the Based.One trading terminal. They extend the platform's functionality by providing specialized tools, custom interfaces, and automated trading strategies - all while maintaining seamless integration with the core trading experience. Think of MiniApps as **plugins for traders** - small, powerful applications that solve specific problems or provide unique functionality without leaving the trading environment. The north-star for MiniApps is to enhance the experience within the Based.One trading terminal: * Enhance Based traders' edge * Increase Based terminal screen time and stickiness * Provide an out of the world experience, create something never seen before ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#why-build-miniapps) Why Build MiniApps? #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#focused-solutions) 🎯 **Focused Solutions** Instead of building a complete trading platform, create targeted tools that solve specific problems, some example ideas: * A position sizing calculator * A market scanner for specific strategies * A risk management dashboard * An automated DCA (Dollar Cost Averaging) bot * Price alerts * AI agent chatbot with trade recommendations * Liquidation heatmaps * Data-analysis tools for traders * Grid-trading bots #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#native-integration) 🔌 **Native Integration** MiniApps have direct access to: * **Trading functions** - Place orders, manage positions, cancel trades * **Real-time market data** - Live prices, order books, trade feeds (feel free to plug your own data instead) * **Account information** - Balances, positions, trading history #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#instant-deployment) ⚡ **Instant Deployment** * No separate infrastructure needed * Built-in security and permissions * Automatic updates and distribution * Cross-platform compatibility ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#what-can-you-build) What Can You Build? #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#trading-automation) 🤖 **Trading Automation** * **Grid Trading Bots** - Automated buy/sell grids for ranging markets * **DCA Bots** - Dollar cost averaging with custom schedules * **Arbitrage Tools** - Cross-exchange price difference monitoring * **Stop Loss Managers** - Advanced stop loss and take profit systems #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#analytics-and-insights) 📊 **Analytics & Insights** * **Portfolio Analyzers** - Advanced portfolio tracking and reporting * **P&L Calculators** - Real-time profit/loss analysis with projections * **Risk Meters** - Position sizing and portfolio risk assessment * **Performance Trackers** - Trading statistics and improvement metrics #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#market-tools) 🔍 **Market Tools** * **Custom Scanners** - Find trading opportunities based on technical patterns * **Alert Systems** - Price, volume, and technical indicator alerts * **Correlation Analyzers** - Asset correlation tracking and visualization * **Market Sentiment** - Social sentiment and on-chain data aggregation #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#educational-and-utility) 📚 **Educational & Utility** * **Trading Simulators** - Paper trading with real market data * **Strategy Backtesting** - Test strategies against historical data * **Learning Tools** - Interactive tutorials and trading guides * **Calculators** - Position size, leverage, and risk calculators #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#games-and-entertainment) 🎮 **Games & Entertainment** * **Video Streaming** - Livestream FED meetings for trade execution, or simply videos for entertainment * **Idle Games** - Simple games while waiting for trade execution ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#how-miniapps-work) How MiniApps Work #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#architecture-overview) 🏗️ **Architecture Overview** Copy ┌─────────────────────────────────────────────┐ │ Based.One Terminal │ ├─────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ MiniApp │ │ Trading Engine │ │ │ │ │◄─┤ │ │ │ │ Your Code │ │ • Market Data │ │ │ │ │─►│ • Order Management │ │ │ │ │ │ • Account Info │ │ │ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────┘ #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#communication-flow) 🔄 **Communication Flow** 1. **Your MiniApp** sends requests to the terminal 2. **Terminal** processes requests with proper permissions (if insufficient permissions, end-user will be prompted to grant permissions) 3. **Trading Engine** executes operations (orders, data requests) 4. **Real-time updates** flow back to your MiniApp 5. **Your UI** updates to reflect current state #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#security-model) 🛡️ **Security Model** * **Permission-based access** - Users explicitly grant capabilities * **Sandboxed execution** - MiniApps run in isolated environments * **Secure communication** - All data exchange is validated * **User control** - Users can revoke permissions at any time ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#development-approaches) Development Approaches We provide three different approaches to building MiniApps, each suited for different skill levels and requirements: #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#simple-api-recommended-for-beginners) 🟢 **Simple API (Recommended for Beginners)** Perfect for getting started quickly: Copy import { createSimpleMiniApp } from '@basedone/miniapp-sdk/simple'; const miniApp = createSimpleMiniApp({ appId: 'my-scanner' }); // Subscribe to market data await miniApp.subscribeToMarketData(['ETH', 'BTC']); // Place a quick buy order await miniApp.quickBuy('ETH', 0.1); // Listen for price updates miniApp.on('marketData', (data) => { console.log(`${data.symbol}: $${data.price}`); }); **Pros:** * Minimal setup and configuration * Strongly-typed TypeScript APIs * Automatic permission handling * Built-in error handling and retries **Best for:** Simple trading bots, basic market tools, learning projects #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#react-integration-recommended-for-ui-rich-apps) 🟡 **React Integration (Recommended for UI-Rich Apps)** Great for building interactive interfaces: Copy import { useSimpleMiniApp, SimpleOrderForm } from '@basedone/miniapp-sdk/react'; function TradingDashboard() { const { marketData, connected } = useSimpleMiniApp({ appId: 'dashboard' }); if (!connected) return
Connecting...
; return (

Trading Dashboard

); } **Pros:** * Ready-to-use React components * Automatic state management * Real-time data binding * Professional UI components **Best for:** Dashboards, portfolio analyzers, complex trading interfaces #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#full-sdk-advanced-use-cases) 🔴 **Full SDK (Advanced Use Cases)** Maximum control and customization: Copy import { MiniAppSDK } from '@basedone/miniapp-sdk'; const sdk = new MiniAppSDK({ appId: 'advanced-bot', permissions: ['trading', 'market_data', 'account_read'] }); // Custom trading logic with full control sdk.commands.trading.placeOrder({ symbol: 'ETH', side: 'buy', type: 'limit', quantity: 0.5, price: 2500, timeInForce: 'GTC', customParameters: { /* advanced options */ } }); **Pros:** * Complete control over all functionality * Access to advanced features * Custom event handling * Maximum performance **Best for:** Professional trading systems, complex algorithms ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#real-world-example-market-scanner) Real-World Example: Market Scanner Here's a simple market scanner that alerts when prices move beyond certain thresholds: Copy import { createSimpleMiniApp } from '@basedone/miniapp-sdk/simple'; class PriceAlertBot { constructor() { this.miniApp = createSimpleMiniApp({ appId: 'price-alerts' }); this.alerts = new Map(); // Store price thresholds } async start() { // Subscribe to market data for monitored symbols await this.miniApp.subscribeToMarketData(['ETH', 'BTC', 'SOL']); // Listen for price updates this.miniApp.on('marketData', (data) => { this.checkAlerts(data); }); } addAlert(symbol, threshold, direction) { this.alerts.set(`${symbol}-${direction}`, { threshold, direction }); } checkAlerts(marketData) { const { symbol, price } = marketData; // Check if price crossed any thresholds for (const [alertId, alert] of this.alerts) { if (alertId.startsWith(symbol)) { const crossed = alert.direction === 'above' ? price > alert.threshold : price < alert.threshold; if (crossed) { this.sendNotification(`${symbol} price alert: $${price}`); this.alerts.delete(alertId); // Remove triggered alert } } } } sendNotification(message) { // Show notification in the terminal console.log(`🚨 ALERT: ${message}`); } } // Usage const bot = new PriceAlertBot(); bot.addAlert('ETH', 3000, 'above'); bot.addAlert('BTC', 40000, 'below'); bot.start(); This example shows how just a few lines of code can create a useful trading tool! ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp#whats-next) What's Next? Now that you understand what MiniApps are and what's possible, let's get you set up: 1. **Quick Start Guide** - Build your first MiniApp in 5 minutes 2. **Installation & Setup** - Detailed development environment setup 3. **Simple API Guide** - Learn the easiest way to build MiniApps Ready to build your first MiniApp? Let's continue with the Quick Start Guide! 🚀 * * * **Next:** Quick Start Guide → [PreviousFairShare](https://basedapp.gitbook.io/docs/launchpad/fairshare) [NextQuick Start Guide](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide) Last updated 1 month ago --- # Quick Start Guide | BasedApp Docs [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#quick-start-guide-build-your-first-miniapp-in-5-minutes) Quick Start Guide: Build Your First MiniApp in 5 Minutes ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Get up and running with your first Based.One MiniApp quickly. This guide will walk you through creating a simple trading bot that automatically places buy orders when prices drop below a threshold. ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#prerequisites) Prerequisites * Node.js 16+ installed * Basic knowledge of JavaScript/TypeScript * A code editor (VS Code recommended) ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#step-1-create-your-project-30-seconds) Step 1: Create Your Project (30 seconds) Copy # Create a new directory for your MiniApp mkdir my-first-miniapp cd my-first-miniapp # Initialize a new Node.js project npm init -y # Install the MiniApp SDK npm install @basedone/miniapp-sdk ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#step-2-create-your-first-miniapp-2-minutes) Step 2: Create Your First MiniApp (2 minutes) Create a React app with interactive trading interface: Copy # Create React app with TypeScript npx create-react-app my-first-miniapp --template typescript cd my-first-miniapp # Install MiniApp SDK npm install @basedone/miniapp-sdk Replace `src/App.tsx`: Copy // src/App.tsx import React, { useState } from 'react'; import { BasedMiniAppProvider, useMiniApp, useMarketData } from '@basedone/miniapp-sdk/react'; import './App.css'; function TradingBot() { const { connected, connecting } = useMiniApp(); const marketData = useMarketData(['ETH', 'BTC']); const [priceThreshold, setPriceThreshold] = useState(2500); const [autoBuyEnabled, setAutoBuyEnabled] = useState(false); // Auto-buy logic when price drops below threshold React.useEffect(() => { if (!autoBuyEnabled || !marketData.ETH) return; const ethPrice = marketData.ETH.price; if (ethPrice < priceThreshold) { console.log(`🎯 ETH at $${ethPrice} - below threshold $${priceThreshold}!`); // Auto-buy logic would go here } }, [marketData.ETH?.price, priceThreshold, autoBuyEnabled]); if (!connected) { return (

🤖 Trading Bot

Status: {connecting ? 'Connecting...' : 'Disconnected'}

Connecting to Based.One terminal...
); } return (

🤖 Trading Bot

{/* Connection Status */}
✅ Connected to Based.One terminal
{/* Market Data */}

📊 Market Data

{Object.entries(marketData).map(([symbol, data]) => (
= 0 ? '#f0f9f0' : '#fff0f0' }}>

{symbol}

${data.price.toLocaleString()}
= 0 ? 'green' : 'red', fontSize: '14px' }}> {data.change24h >= 0 ? '+' : ''}{data.change24h.toFixed(2)}% (24h)
))}
{/* Auto-Buy Settings */}

🎯 Auto-Buy Settings

setPriceThreshold(Number(e.target.value))} style={{ width: '100%' }} />
{autoBuyEnabled ? `⚡ Auto-buy ACTIVE: Will buy 0.01 ETH when price drops below $${priceThreshold}` : '⏸️ Auto-buy DISABLED: Manual trading only' }
{/* Manual Trading */}

💰 Manual Trading

{/* Order form component would go here */}

Order placement UI here

{/* Trading History */}

📈 Recent Activity

Recent trades and orders will appear here...

); } function App() { return (
); } export default App; ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#step-3-run-your-miniapp-30-seconds) Step 3: Run Your MiniApp (30 seconds) Copy # Start the React development server npm start Your browser will open to `http://localhost:3000` showing your trading bot interface with: * ✅ Real-time ETH and BTC price displays * 🎯 Interactive auto-buy threshold slider * 💰 Manual trading form with order placement * 📊 Market data updates in real-time ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#step-4.-load-miniapp-on-our-testkit) Step 4. Load miniapp on our testkit 1. Visit https://testnet.based.one 2. Click bug icon on lower right hand corner 3. Enter appId (12-letter alphanumeric) and url: http://localhost:3000 4. Load app ![](https://basedapp.gitbook.io/docs/~gitbook/image?url=https%3A%2F%2F893698931-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FD195DGgjp8wD1XdWWTcZ%252Fuploads%252FxDPaBG5oM8LIauLrjQqh%252Fimage.png%3Falt%3Dmedia%26token%3D5459320f-de04-45e4-91b6-d63ac212dc2f&width=768&dpr=4&quality=100&sign=426fbbad&sv=2) You should see console output like this: Copy 🤖 Starting Trade Bot... ✅ Connected to Based.One terminal ✅ Trading permissions granted ✅ Subscribed to ETH market data 🚀 Bot is now running! Watching for ETH price drops... 📊 ETH Price: $2487.50 🎯 Price trigger activated! ETH at $2487.50, buying 0.01 ETH... 📈 Buy order placed successfully! 📝 New threshold set to: $2462.63 ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#step-5-customize-your-bot-1-minute) Step 5: Customize Your Bot (1 minute) Now that your bot is running, try customizing it: Copy // Change the asset and parameters this.priceThreshold = 40000; // Watch BTC instead this.buyAmount = 0.001; // Smaller position size // Subscribe to different markets await this.sdk.subscribeToMarkets(['BTC', 'ETH', 'SOL']); // Add more sophisticated logic handlePriceUpdate(marketData) { const { symbol, price, volume24h } = marketData; // Only trade if there's sufficient volume if (volume24h > 1000000) { // Your trading logic here... } } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#what-just-happened) What Just Happened? Congratulations! You've just built a functional trading bot with: ✅ **Real-time market data** - Your bot receives live price feeds ✅ **Automated trading** - Orders are placed automatically based on conditions ✅ **Permission management** - Users control what your bot can access ✅ **Error handling** - Robust error handling keeps your bot running ✅ **Event-driven architecture** - React to market changes in real-time ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#next-steps) Next Steps #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#add-a-user-interface) 🎨 Add a User Interface Want to add controls and displays? Try the React version: Copy // App.jsx import React from 'react'; import { BasedMiniAppProvider, useMiniApp } from '@basedone/miniapp-sdk/react'; function TradingBot() { const { marketData, connected } = useMiniApp(); if (!connected) return
Connecting to terminal...
; return (

My Trading Bot

Current Prices

{Object.entries(marketData).map(([symbol, data]) => (
{symbol}: ${data.price}
))}
{/* Order form component would go here */}
); } function App() { return ( ); } export default App; #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#common-customizations) 🔧 Common Customizations **Add Multiple Assets:** Copy await this.sdk.subscribeToMarkets(['ETH', 'BTC', 'SOL', 'AVAX']); **Implement Stop Loss:** Copy async placeOrderWithStopLoss(symbol, size, stopLossPrice) { const order = await this.sdk.placeOrder({ symbol, side: 'buy', orderType: 'market', size }); // Set stop loss await this.sdk.placeOrder({ symbol, side: 'sell', orderType: 'market', size, tpsl: { slLossPercent: 5, } }); } **Add Portfolio Tracking:** Copy // Get current positions const positions = await this.sdk.getPositions(); const totalValue = positions.reduce((sum, pos) => sum + pos.marketValue, 0); console.log(`Portfolio value: $${totalValue}`); ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#troubleshooting) Troubleshooting #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#connection-issues) Connection Issues Copy // Add connection retry logic const sdk = new MiniAppSDK({ appId: 'my-bot', autoConnect: true }); // Manual retry logic if needed let retries = 5; while (retries > 0) { try { await sdk.connect(); break; } catch (error) { retries--; await new Promise(r => setTimeout(r, 2000)); } } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#permission-denied) Permission Denied Copy try { await this.sdk.requestPermissions(['place_orders', 'read_market_data']); } catch (error) { console.log('Trading permissions required. Please approve in the terminal.'); } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#order-failures) Order Failures Copy this.sdk.on('error', (error) => { console.error('Order failed:', error.message); // Implement retry logic or fallback strategy }); ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#security-reminders) Security Reminders ⚠️ **Important Security Notes:** * Never share your private keys or API credentials * Start with small position sizes while testing * Always implement proper error handling * Test thoroughly before using real funds * Monitor your bots regularly ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide#congratulations) Congratulations! 🎉 You've successfully built and deployed your first MiniApp! This simple bot demonstrates the core concepts: * Connecting to the Based.One terminal * Requesting permissions * Subscribing to market data * Placing automated trades * Handling real-time events Ready to build something more complex? Check out the Complete Tutorial Series or explore Advanced Examples. * * * **Next:** Installation & Setup → Learn about development environments and tooling [PreviousBased MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp) [NextMiniApp Architecture](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture) Last updated 16 minutes ago --- # MiniApp Architecture | BasedApp Docs [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#miniapp-architecture-guide) MiniApp Architecture Guide --------------------------------------------------------------------------------------------------------------------------------------------- This guide provides a comprehensive overview of how Based.One MiniApps work under the hood, including communication patterns, security models, and architectural decisions. ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#high-level-architecture) High-Level Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#system-overview) System Overview Copy ┌─────────────────────────────────────────────────────────────────────┐ │ Based.One Terminal │ ├─────────────────────────────────────────────────────────────────────┤ │ ┌───────────────┐ ┌─────────────────────────────────────────────┐ │ │ │ MiniApp │ │ Core Systems │ │ │ │ Container │ │ │ │ │ │ │ │ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ │ ┌─────────┐ │◄─┤ │ Permission │ │ Trading Engine │ │ │ │ │ │Your App │ │ │ │ Manager │ │ │ │ │ │ │ │ │ │─►│ │ │ │ • Order Management │ │ │ │ │ │ │ │ │ └─────────────┘ │ • Risk Controls │ │ │ │ │ └─────────┘ │ │ │ • Portfolio Tracking │ │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ iframe │ │ │ Market Data │ └─────────────────────────┘ │ │ │ │ sandbox │ │◄─┤ Service │ │ │ │ │ │ │ │ │ ┌─────────────────────────┐ │ │ │ └───────────────┘ │ │ • WebSocket │ │ Account Service │ │ │ │ │ │ • REST API │ │ │ │ │ │ │ │ • Caching │ │ • Balance Management │ │ │ │ │ │ │ │ • Position Tracking │ │ │ │ │ └─────────────┘ │ • Transaction History │ │ │ │ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ └─────────────────────────────────────────────────────────────────────┘ ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#communication-architecture) Communication Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-postmessage-communication) 1\. PostMessage Communication MiniApps run in sandboxed iframes and communicate with the terminal via the PostMessage API: Copy // MiniApp to Terminal window.parent.postMessage({ type: 'MINIAPP_REQUEST', requestId: 'uuid-123', payload: { action: 'place_order', data: { symbol: 'ETH', side: 'buy', quantity: 0.1, type: 'market' } } }, '*'); // Terminal to MiniApp window.addEventListener('message', (event) => { if (event.data.type === 'MINIAPP_RESPONSE') { const { requestId, success, data, error } = event.data; // Handle response } }); #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-message-flow-diagram) 2\. Message Flow Diagram Copy MiniApp Terminal Trading Engine │ │ │ │ 1. place_order │ │ ├─────────────────────────►│ │ │ │ 2. validate_permissions │ │ ├──────────────┐ │ │ │◄─────────────┘ │ │ │ 3. execute_order │ │ ├─────────────────────────►│ │ │ 4. order_confirmation │ │ 5. order_response │◄─────────────────────────┤ │◄─────────────────────────┤ │ │ │ 6. broadcast_update │ │ 7. market_data_update │ │ │◄─────────────────────────┤ │ #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-3.-event-driven-architecture) 3\. Event-Driven Architecture The SDK uses an event-driven pattern for real-time updates: Copy class SimpleMiniAppClient extends EventEmitter { constructor(config: SimpleConfig) { super(); this.setupMessageHandlers(); } private setupMessageHandlers() { window.addEventListener('message', (event) => { const { type, data } = event.data; switch (type) { case 'MARKET_DATA_UPDATE': this.emit('marketData', data); break; case 'ORDER_CONFIRMATION': this.emit('orderConfirmation', data); break; case 'ACCOUNT_UPDATE': this.emit('accountUpdate', data); break; } }); } } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#security-architecture) Security Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-permission-model) 1\. Permission Model MiniApps operate under a strict permission-based security model: Copy interface PermissionScope { // Market data access market_data_read: boolean; // Trading permissions trading_read: boolean; // View orders, positions trading_write: boolean; // Place orders trading_cancel: boolean; // Cancel orders // Account permissions account_read: boolean; // View balances, history // Advanced permissions api_access: boolean; // External API calls } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-permission-request-flow) 2\. Permission Request Flow Copy // Simple API handles permissions automatically const miniApp = createSimpleMiniApp({ appId: 'my-app', requestedPermissions: ['trading_read', 'trading_write', 'market_data_read'] }); // Permission request is automatic await miniApp.requestTradingPermissions(); // Manual permission checking if (await miniApp.hasPermission('trading_write')) { await miniApp.placeOrder(orderData); } else { console.log('Trading permission required'); } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-3.-sandboxing) 3\. Sandboxing MiniApps run in isolated iframe sandboxes with restricted capabilities: Copy **Sandbox Restrictions:** * No direct DOM access to parent window * No access to terminal's localStorage/cookies * Limited network access (proxied through terminal) * No popup windows or modal dialogs * Communication only via PostMessage API ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#data-flow-architecture) Data Flow Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-real-time-data-pipeline) 1\. Real-Time Data Pipeline Copy External Data Sources → Terminal → MiniApp SDK → Your Application ↓ ┌─────────────┐ │ WebSocket │ ← Market feeds, order updates │ Manager │ └─────────────┘ ↓ ┌─────────────┐ │ Data │ ← Normalization, validation │ Processor │ └─────────────┘ ↓ ┌─────────────┐ │ Event │ ← Broadcast to subscribed MiniApps │ Dispatcher │ └─────────────┘ ↓ ┌─────────────┐ │ MiniApp │ ← Your event handlers │ SDK │ └─────────────┘ #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-state-management) 2\. State Management The SDK provides different state management patterns: **Simple API - Event-Based:** Copy const miniApp = createSimpleMiniApp({ appId: 'my-app' }); // State is managed through events let currentPrice = 0; miniApp.on('marketData', (data) => { if (data.symbol === 'ETH') { currentPrice = data.price; } }); **React API - Hook-Based:** Copy function TradingComponent() { // State is managed by hooks const { marketData, positions, balance } = useSimpleMiniApp({ appId: 'trading-ui', symbols: ['ETH', 'BTC'] }); // Automatic re-renders on state changes return
ETH: ${marketData.ETH?.price}
; } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#sdk-architecture-layers) SDK Architecture Layers #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-layered-architecture) 1\. Layered Architecture Copy ┌─────────────────────────────────────────────────────┐ │ React Components │ ← SimpleOrderForm, etc. ├─────────────────────────────────────────────────────┤ │ React Hooks │ ← useSimpleTrade, etc. ├─────────────────────────────────────────────────────┤ │ Simple API │ ← createSimpleMiniApp ├─────────────────────────────────────────────────────┤ │ Core SDK │ ← MiniAppSDK class ├─────────────────────────────────────────────────────┤ │ Communication Layer │ ← PostMessage handling ├─────────────────────────────────────────────────────┤ │ Browser APIs │ ← iframe, postMessage └─────────────────────────────────────────────────────┘ #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-simple-api-architecture) 2\. Simple API Architecture Copy // High-level Simple API class SimpleMiniAppClient { private coreSDK: MiniAppSDK; private eventEmitter: EventEmitter; private permissionManager: PermissionManager; constructor(config: SimpleConfig) { this.coreSDK = new MiniAppSDK(config); this.setupAutomaticPermissions(); this.setupEventBridge(); } // Convenience methods wrap core SDK async quickBuy(symbol: string, quantity: number) { await this.ensureTradingPermissions(); return this.coreSDK.commands.trading.placeOrder({ symbol, side: 'buy', type: 'market', quantity }); } } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#performance-architecture) Performance Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-connection-management) 1\. Connection Management Copy class ConnectionManager { private reconnectAttempts = 0; private maxReconnectAttempts = 5; private reconnectDelay = 1000; async connect() { try { await this.establishConnection(); this.reconnectAttempts = 0; } catch (error) { await this.handleConnectionFailure(); } } private async handleConnectionFailure() { if (this.reconnectAttempts < this.maxReconnectAttempts) { this.reconnectAttempts++; const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts); setTimeout(() => this.connect(), delay); } } } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-message-queuing) 2\. Message Queuing Copy class MessageQueue { private queue: Message[] = []; private processing = false; async sendMessage(message: Message) { this.queue.push(message); if (!this.processing) { await this.processQueue(); } } private async processQueue() { this.processing = true; while (this.queue.length > 0) { const message = this.queue.shift()!; try { await this.sendMessageToTerminal(message); } catch (error) { // Handle retry logic if (message.retryCount < 3) { message.retryCount++; this.queue.unshift(message); // Retry first } } } this.processing = false; } } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-3.-data-caching) 3\. Data Caching Copy class DataCache { private cache = new Map(); private readonly TTL = 5000; // 5 seconds get(key: string): any { const entry = this.cache.get(key); if (entry && Date.now() - entry.timestamp < this.TTL) { return entry.data; } return null; } set(key: string, data: any) { this.cache.set(key, { data, timestamp: Date.now() }); } } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#error-handling-architecture) Error Handling Architecture #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-error-classification) 1\. Error Classification Copy enum ErrorType { CONNECTION_ERROR = 'connection', PERMISSION_ERROR = 'permission', VALIDATION_ERROR = 'validation', TRADING_ERROR = 'trading', NETWORK_ERROR = 'network' } class MiniAppError extends Error { constructor( public type: ErrorType, message: string, public code?: string, public recoverable = true ) { super(message); this.name = 'MiniAppError'; } } #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-error-recovery-strategies) 2\. Error Recovery Strategies Copy class ErrorHandler { async handleError(error: MiniAppError, context: any) { switch (error.type) { case ErrorType.CONNECTION_ERROR: return this.handleConnectionError(error); case ErrorType.PERMISSION_ERROR: return this.handlePermissionError(error); case ErrorType.TRADING_ERROR: return this.handleTradingError(error); default: throw error; // Re-throw unhandleable errors } } private async handleConnectionError(error: MiniAppError) { // Implement reconnection logic await this.reconnect(); } private async handlePermissionError(error: MiniAppError) { // Request missing permissions await this.requestPermissions(); } } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#key-architectural-decisions) Key Architectural Decisions #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-1.-why-iframe-sandboxing) 1\. Why iframe Sandboxing? * **Security**: Complete isolation from terminal code * **Stability**: MiniApp crashes don't affect terminal * **Flexibility**: Support for any web technology * **Updates**: Independent deployment and versioning #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-2.-why-postmessage-communication) 2\. Why PostMessage Communication? * **Security**: Controlled communication channel * **Standards**: Built on web standards * **Reliability**: Browser-native implementation * **Debugging**: Easy to inspect and debug #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-3.-why-event-driven-design) 3\. Why Event-Driven Design? * **Real-time**: Immediate updates from markets * **Scalability**: Efficient one-to-many broadcasting * **Flexibility**: Easy to add new event types * **Performance**: Non-blocking operations #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#id-4.-why-multiple-api-layers) 4\. Why Multiple API Layers? * **Progressive Enhancement**: Start simple, add complexity as needed * **Developer Experience**: Choose the right abstraction level * **Maintenance**: Clear separation of concerns * **Testing**: Each layer can be tested independently ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture#next-steps) Next Steps Now that you understand the architecture: 1. **Simple API Reference** - Detailed API documentation 2. **React Integration** - Building UIs with React * * * **Next:** Simple API Reference → Complete API documentation [PreviousQuick Start Guide](https://basedapp.gitbook.io/docs/developers/based-miniapp/quick-start-guide) [NextMiniApp API](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api) Last updated 1 month ago --- # MiniApp API | BasedApp Docs ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#api-reference) API Reference The TypeScript client provides a strongly-typed interface for building MiniApps that talk to the Based Terminal via `postMessage`. This guide documents the SDK surface: setup, connection lifecycle, permissions, commands, responses, subscriptions, events, and message envelopes—with concise examples. ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#core-api) Core API #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#creating-an-instance) Creating an instance Copy import { createMiniApp, getMiniApp } from "@based-one/miniapp-sdk"; const app = createMiniApp(config); // If called again, a new instance replaces the old singleton const same = getMiniApp(); // returns current instance or null #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#miniappconfig) MiniAppConfig * appId: string (required) max 12 letters, alphanumeric lowercased * appSecret?: string (optional; enables signature signing/verification) * targetOrigin?: string (default "\*") * autoConnect?: boolean (default true) * version?: string (default "1.0.0") * permissions?: AppPermission\[\] (requested on connect) * tenantId?: string (used by theming) * debug?: boolean (controls debug logs) #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#lifecycle) Lifecycle * connect(): Promise * disconnect(): void * destroy(): void * getConnectionState(): { connected: boolean; sessionId?: string; permissions: Set; lastHeartbeat?: number } Example: Copy await app.connect(); const state = app.getConnectionState(); #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#events-emitted) Events (emitted) The SDK extends EventEmitter and emits: * "connected" | "disconnected" | "error" * All terminal events from Event Registry (see Events section), e.g. "market.prices", "order.status", "theme.change", etc. Copy app.on("permission.change", (payload) => { // payload.permissions: AppPermission[] }); app.on("market.prices", ({ prices, timestamp }) => { console.log(prices, timestamp); }); #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#permissions) Permissions * requestPermissions(permissions: AppPermission\[\]): Promise * hasPermission(p: AppPermission): boolean Copy import { AppPermission } from "@based-one/miniapp-sdk"; const approved = await app.requestPermissions([\ AppPermission.READ_MARKET_DATA,\ AppPermission.PLACE_ORDERS,\ ]); if (app.hasPermission(AppPermission.PLACE_ORDERS)) { // safe to trade } **AppPermission values** * Market data: READ\_MARKET\_DATA, READ\_ORDERBOOK, READ\_CANDLES * Account: READ\_ACCOUNT, READ\_POSITIONS, READ\_ORDERS, READ\_BALANCE, READ\_TRADES * Trading: PLACE\_ORDERS, CANCEL\_ORDERS, MODIFY\_ORDERS, POPULATE\_ORDERS * UI: READ\_NAVIGATION, WRITE\_NAVIGATION, WRITE\_CHART, SEND\_NOTIFICATIONS * User settings: READ\_USER\_SETTINGS, MODIFY\_USER\_SETTINGS * Advanced: EXECUTE\_STRATEGIES, ACCESS\_ANALYTICS **Permission categories** * trading (high risk) * account\_read (medium) * market\_data (low) * navigation (medium) * notifications (low) * user\_settings (medium) #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#subscriptions) Subscriptions * subscribe(type: MiniAppSubscriptionType, payload?: SubcriptionPayload): Promise<{ subscriptionId: string; unsubscribe: () => Promise }> * unsubscribe(subscriptionId: string): Promise * subscribeToMarkets(symbols: string\[\]): Promise<{ subscriptionId: string; unsubscribe: () => Promise }> Copy const { subscriptionId, unsubscribe } = await app.subscribeToMarkets(["BTC-USDT", "ETH-USDT"]); app.on("market.prices", ({ prices }) => console.log(prices)); await unsubscribe(); ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#commands) Commands Commands are validated with zod schemas before being sent. Use high-level helpers or `sendCommand` directly. #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#high-level-helpers) High-level helpers * placeOrder(order: SubmitOrderCommand): Promise> * placeOrders(orders: SubmitOrderCommand\[\]): Promise> * populateOrder(order: SubmitOrderCommand): Promise> * cancelOrder(orderId: string, symbol?: string): Promise> * cancelOrders(orders: CancelOrderCommand\[\]): Promise> * modifyOrder(orderId: string, modifications: { price?: number; quantity?: number; stopPrice?: number; trailingPercent?: number }): Promise> * getAccount(): Promise> * getPositions(symbol?: string): Promise> * getOrders(symbol?: string, status?: "open" | "filled" | "cancelled" | "partial" | "all"): Promise> * getWalletAddress(): Promise #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#sendcommand) sendCommand Copy // Generic form const resp = await app.sendCommand("order.submit", { symbol: "BTC", side: "buy", orderType: "limit", size: 0.1, price: 100000, }); #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#command-registry) Command Registry Supported command names and payload shapes (abbrev.): * order.populate: SubmitOrderCommand * order.submit: SubmitOrderCommand * order.submitMultiple: { orders: SubmitOrderCommand\[\] } * order.cancel: { orderId: string; symbol?: string } * order.cancelMultiple: { orders: { orderId: string; symbol?: string }\[\] } * order.modify: { orderId: string; modifications: { price?: number; quantity?: number; stopPrice?: number; trailingPercent?: number } } * orders.query: { symbol?: string; status?: "open" | "filled" | "cancelled" | "partial" | "all" } * leverage.query: { symbol: string } // note: registry uses update schema for validation * leverage.update: { symbol: string; leverage: number; isCross: boolean } * position.query: { symbol?: string } * position.close: { symbol: string; size?: number; percentage?: number; marketOrder?: boolean; limitPrice?: number } * wallet.balance: { assets?: string\[\]; includeSmallBalances?: boolean } * wallet.address: {} * notification.success | .error | .warning | .info: { title: string; message: string } * navigation.navigate: { symbol: string } * navigation.status: undefined * chart.draw: { symbol: string; drawings: Array<...> } * analytics.query: { metric: "pnl" | "volume" | "win\_rate" | "sharpe" | "roi"; period: "1d" | "7d" | "30d" | "90d" | "all"; groupBy?: "day" | "week" | "month" | "symbol" } **SubmitOrderCommand** Copy type SubmitOrderCommand = { symbol: string; side: "buy" | "sell"; orderType: "market" | "limit" | "stop" | "stop_limit"; size?: number; price?: number; stopPrice?: number; reduceOnly?: boolean; postOnly?: boolean; tpsl?: { tpPrice?: number | null; tpGainPercent?: number | null; slPrice?: number | null; slLossPercent?: number | null }; tif?: "Gtc" | "Ioc" | "Alo"; }; **ModifyOrderCommand** Copy type ModifyOrderCommand = { orderId: string; modifications: { price?: number; quantity?: number; stopPrice?: number; trailingPercent?: number; // 0-100 }; }; **Orders/Positions/Wallet Query Types** Copy type QueryOrdersCommand = { symbol?: string; status?: "open" | "filled" | "cancelled" | "partial" | "all" }; type PositionQueryCommand = { symbol?: string }; type WalletBalanceCommand = { assets?: string[]; includeSmallBalances?: boolean }; ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#command-responses) Command Responses Every command resolves to `CommandResponse`: Copy type CommandResponse = { success: boolean; data?: any; // typed per command below error?: string; timestamp?: number; }; Per-command response payloads: * order.submit → { cloid: string; statuses: \[OrderStatus\] } * order.submitMultiple → { results: BatchOrderResult\[\]; successCount: number; failureCount: number } * order.cancel → undefined * order.cancelMultiple → { results: BatchCancelResult\[\]; successCount: number; failureCount: number } * order.modify → undefined * order.populate → undefined * orders.query → { orders: Order\[\]; totalCount: number } * leverage.update → { symbol: string; leverage: number; isCross: boolean } * leverage.query → { symbol: string; leverage: number; isCross: boolean } * position.query → { positions: Position\[\]; totalUnrealizedPnl: number; totalMargin: number } * position.close → { cloid: string; statuses: \[OrderStatus\] } * wallet.balance → { assets: string\[\]; positions: Position\[\] } * wallet.address → { address: string } * notification.\* → undefined * navigation.navigate → undefined * navigation.status → { symbol?: string } * chart.draw → undefined * analytics.query → same shape as request (metric/period/groupBy) #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#important-types) Important types Copy type OrderStatus = { resting: { oid: string } } | { filled: { oid: string; totalSz: string; avgPx: string } } | { error: string }; type BatchOrderResult = | { index: number; success: true; status: { resting: { oid: string } } | { filled: { oid: string; totalSz: string; avgPx: string } } } | { index: number; success: false; status: { error: string } }; type CancelStatus = { success: { oid: string } } | { error: string }; #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#type-guards-helpers) Type guards (helpers) Copy import { isRestingStatus, isFilledStatus, isErrorStatus, isCancelSuccess, isCancelError } from "@based-one/miniapp-sdk"; if (isFilledStatus(status)) { console.log(status.filled.avgPx); } ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#events) Events The terminal emits events; the SDK relays them via `app.on(eventType, handler)`. Event types and payloads: * market.ticker: { symbol, price, volume24h, high24h, low24h, change24h, changePercent24h, timestamp } * market.bbo: { symbol, price, bid, ask, spread, timestamp } * market.prices: { prices: Record; timestamp } * market.trades: { symbol, trades: Array<{ price, size, side, id, timestamp }> } * order.status: { orderId, symbol, status, side, orderType, price?, quantity, filledQuantity, remainingQuantity, averagePrice?, timestamp, message? } * order.update: { orderId, symbol, side, price, quantity, fee, feeAsset, timestamp, tradeId } * position.update: Array<{ symbol, size, entryPrice, leverage, positionValue, liquidationPx, pnl, timestamp }> * wallet.update: { asset, free, locked, total, usdValue, timestamp } * wallet.switch: { address } * theme.change: { colors, typography, mode } * navigation.update: { symbol } * auth.status: { authenticated, address?, permissions?, sessionExpiry? } * permission.change: { permissions: AppPermission\[\] } * permission.granted: { permissions: AppPermission\[\] } * connection.status: { connected, sessionId, appId, timestamp } * notification: { id, type: "info" | "success" | "warning" | "error", title, message, timestamp, actions? } Example: Copy app.on("order.status", (e) => { if (e.status === "filled") console.log("Filled!", e.orderId); }); ``; ## Message Envelopes (advanced) Low-level shapes used over postMessage. Most users do not need this. ### MiniAppMessage → Terminal ```ts type MiniAppMessage = { id: string; timestamp: number; appId: string; sessionId?: string; type: "connect" | "disconnect" | "command" | "subscribe" | "unsubscribe" | "heartbeat" | "requestPermission" | "getPermissions"; command?: string; // command or subscription type payload?: any; signature?: string; nonce?: string; source: "based-miniapp"; }; #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#miniappresponse-terminal) MiniAppResponse ← Terminal Copy type MiniAppResponse = { id: string; type: "response" | "event" | "connected" | "disconnected" | "error"; correlationId: string | undefined; timestamp: number; success: boolean; data?: T; error?: string; }; ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#examples) Examples #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#batch-submit-and-cancel) Batch submit and cancel Copy // Submit multiple const submit = await app.placeOrders([\ { symbol: "BTC-USDT", side: "buy", orderType: "limit", size: 0.1, price: 60000 },\ { symbol: "ETH-USDT", side: "sell", orderType: "limit", size: 1, price: 3500 },\ ]); // Cancel by specific ids await app.cancelOrders([\ { orderId: "abc123" },\ { orderId: "def456", symbol: "ETH-USDT" },\ ]); #### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#querying-account-state) Querying account state Copy const { data: orders } = await app.getOrders(undefined, "open"); const { data: positions } = await app.getPositions(); const walletAddress = await app.getWalletAddress(); ### [](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-api#notes) Notes * All commands time out after ~30s if no response is received. * When `appSecret` is provided, messages are signed and verified. * Heartbeats are sent every 30s while connected. [PreviousMiniApp Architecture](https://basedapp.gitbook.io/docs/developers/based-miniapp/miniapp-architecture) [NextMonetization](https://basedapp.gitbook.io/docs/developers/based-miniapp/monetization) Last updated 4 minutes ago --- # Card Types | BasedApp Docs Card Types | BasedApp Docs --- # React Sample MiniApp | BasedApp Docs This section showcases a sample React MiniApp: Copy /** * React Usage Examples * Shows how to use the Simple API with React hooks and components */ import React, { useEffect, useState } from 'react'; import { // Simple React hooks useSimpleMiniApp, useSimpleTrade, useSimpleMarketData, useSimplePositions, useSimpleBalance, useSimplePermissions, useSimpleConnection, // Context provider and hooks SimpleMiniAppProvider, useSimpleMiniAppContext, useSimpleTrading, useSimpleAccount, useSimplePermissionsContext, // Types SimpleOrderData, SimpleMarketData, SimplePermission } from '../index'; // ============================================ // Example 1: Basic Hook Usage // ============================================ /** * Simple trading app using individual hooks * This shows the most basic usage pattern */ export function BasicTradingApp() { const { client, connected, sessionId, error } = useSimpleMiniApp({ appId: 'basic-trader', debug: true }); const { placeOrder, loading: tradingLoading, error: tradingError } = useSimpleTrade(client); const { data: marketData, subscribe } = useSimpleMarketData(client); const { permissions, requestTradingPermissions } = useSimplePermissions(client); useEffect(() => { if (connected) { // Subscribe to market data on connection subscribe(['ETH', 'BTC', 'SOL']); // Request trading permissions requestTradingPermissions(); } }, [connected, subscribe, requestTradingPermissions]); const handleQuickBuy = async (symbol: string, size: number) => { try { await placeOrder({ symbol, side: 'buy', orderType: 'market', size }); alert(`Bought ${size} ${symbol}!`); } catch (err: any) { alert(`Order failed: ${err.message}`); } }; if (error) { return
Error: {error.message}
; } if (!connected) { return
Connecting to Based.One Terminal...
; } return (

🚀 Simple Trader

Session: {sessionId}

Permissions: {permissions.join(', ')}

📊 Market Data

{Object.entries(marketData).map(([symbol, data]) => (
{symbol}: ${data.price.toFixed(2)}
))}
{tradingError && (
Trading Error: {tradingError.message}
)}
); } // ============================================ // Example 2: Context Provider Usage // ============================================ /** * App using the context provider for global state management * This is the recommended pattern for larger applications */ export function ContextProviderApp() { return ( ); } function TradingDashboard() { const { connected, sessionId, marketData, placeOrder, hasPermission, loading, error } = useSimpleMiniAppContext(); if (!connected) { return
Connecting...
; } return (

🏗️ Trading Dashboard

Session: {sessionId}

{error && (
Error: {error.message}
)}
); } function MarketDataPanel() { const { marketData } = useSimpleMiniAppContext(); return (

📊 Market Data

{Object.entries(marketData).map(([symbol, data]) => (
{symbol} ${data.price.toFixed(2)} {data.changePercent24h !== undefined && ( = 0 ? 'green' : 'red' }}> {data.changePercent24h >= 0 ? '+' : ''}{data.changePercent24h.toFixed(2)}% )}
))}
); } function TradingPanel() { const { placeOrder, loading, hasPermission } = useSimpleMiniAppContext(); const [orderForm, setOrderForm] = useState>({ symbol: 'ETH', side: 'buy', orderType: 'market', size: 0.1 }); const canTrade = hasPermission('place_orders'); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!placeOrder || !orderForm.symbol || !orderForm.side || !orderForm.orderType || !orderForm.size) { return; } try { await placeOrder({ symbol: orderForm.symbol, side: orderForm.side, orderType: orderForm.orderType, size: orderForm.size, price: orderForm.price }); alert('Order placed successfully!'); } catch (err: any) { alert(`Order failed: ${err.message}`); } }; return (

📈 Place Order

{!canTrade && (
⚠️ Trading permissions required
)}
setOrderForm(prev => ({ ...prev, size: parseFloat(e.target.value) }))} style={{ marginLeft: '10px', padding: '5px' }} />
{orderForm.orderType === 'limit' && (
setOrderForm(prev => ({ ...prev, price: parseFloat(e.target.value) }))} style={{ marginLeft: '10px', padding: '5px' }} />
)}
); } function AccountPanel() { const { positions, balances, refreshPositions, refreshBalances } = useSimpleAccount(); useEffect(() => { refreshPositions(); refreshBalances(); }, [refreshPositions, refreshBalances]); return (

📋 Positions

{positions.length === 0 ? (

No open positions

) : ( positions.map(position => (
{position.symbol}
Size: {position.size}
Entry: ${position.entryPrice.toFixed(2)}
= 0 ? 'green' : 'red' }}> PnL: ${position.pnl.toFixed(2)} ({position.pnlPercent.toFixed(2)}%)
)) )}

💰 Balances

{Object.keys(balances).length === 0 ? (

No balances available

) : ( Object.entries(balances).map(([asset, balance]) => (
{asset}
Free: {balance.free.toFixed(4)}
Locked: {balance.locked.toFixed(4)}
USD Value: ${balance.usdValue.toFixed(2)}
)) )}
); } // ============================================ // Example 3: Permission Gate Component // ============================================ /** * Component that manages permissions and gates access to features */ interface PermissionGateProps { children: React.ReactNode; requiredPermissions: SimplePermission[]; fallback?: React.ReactNode; } export function PermissionGate({ children, requiredPermissions, fallback }: PermissionGateProps) { const { hasPermission, requestPermission } = useSimplePermissionsContext(); const { loading } = useSimpleMiniAppContext(); const missingPermissions = requiredPermissions.filter(permission => !hasPermission(permission)); if (missingPermissions.length === 0) { return <>{children}; } const handleRequestPermissions = async () => { for (const permission of missingPermissions) { await requestPermission(permission); } }; if (fallback) { return <>{fallback}; } return (

🔐 Permissions Required

This feature requires the following permissions:

    {missingPermissions.map(permission => (
  • {permission.replace(/_/g, ' ')}
    • ))}
); } // ============================================ // Example 4: Connection Status Component // ============================================ /** * Component showing connection status with reconnect functionality */ export function ConnectionStatus() { const config = { appId: 'connection-status-demo', debug: true }; const context = useSimpleMiniApp(config); const { client, connected, sessionId, error } = context; // Use the useSimpleConnection hook for connection management const { connecting, connect, disconnect } = useSimpleConnection(client); return (
Status: { connected ? `Connected (${sessionId})` : connecting ? 'Connecting...' : 'Disconnected' }
{!connected && !connecting && ( )} {connected && ( )}
{error && (
Error: {error.message}
)}
); } // ============================================ // Example 5: Complete Mini-App // ============================================ /** * Complete mini-app example showing all patterns together */ export function CompleteMiniApp() { return (

🚀 Complete Trading Mini-App

Trading features require permissions
} > ); } [PreviousHTML Sample MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps/html-sample-miniapp) [NextBuilder-on-Builder Program](https://basedapp.gitbook.io/docs/developers/builder-on-builder-program) Last updated 1 month ago --- # HTML Sample MiniApp | BasedApp Docs The following represents a sample pure HTML MiniApp: Copy Simple Trader MiniApp

🚀 Simple Trader

MiniApp for Based.One Terminal

Disconnected
Session: -

📈 Place Order

📊 Market Data

🔐 Permissions

🐛 Debug Log

[PreviousSample Apps](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps) [NextReact Sample MiniApp](https://basedapp.gitbook.io/docs/developers/based-miniapp/sample-apps/react-sample-miniapp) Last updated 1 month ago --- # Take Profit / Stop Loss | BasedApp Docs Take Profit / Stop Loss | BasedApp Docs --- # Participate | BasedApp Docs Participate | BasedApp Docs --- # Card Types | BasedApp Docs Card Types | BasedApp Docs --- # Switching over from Legacy to HyperApp | BasedApp Docs Switching over from Legacy to HyperApp | BasedApp Docs --- # Based MiniApp | BasedApp Docs Based MiniApp | BasedApp Docs ---