# API Endpoints Source: https://docs.hyperbloom.xyz/api-reference/endpoints Introduction to the HyperBloom API The `/swap/v1/price` endpoint in the HyperBloom protocol is designed to provide an indicative price for a transaction. Unlike the `/swap/v1/quote` endpoint, it does not return a transaction executable on an Ethereum node but rather offers pricing information that would be available for a similar call to `/swap/v1/quote`. This endpoint is particularly useful for Request for Quote (RFQ) scenarios. ### Request Schema The request schema for `/swap/v1/price` mirrors that of `/swap/v1/quote`, with specific exceptions applicable across all supported chains: #### Query Parameters | Query Param | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sellToken` | The ERC20 token address of the token you wish to sell. Always use the token address instead of symbols (e.g., ETH) to ensure API recognition. | | `buyToken` | The ERC20 token address of the token you wish to receive. Always use the token address instead of symbols (e.g., ETH) to ensure API recognition. | | `sellAmount` | (Optional) The amount of `sellToken` (in base units) you intend to send. | | `slippagePercentage` | (Optional, default is 0.01) Maximum acceptable slippage for `buyToken` if `sellAmount` is provided, or for `sellAmount` if `buyAmount` is provided. Default is 1% if not specified. | | `takerAddress` | (Optional) Address that will fill the quote. Recommended for accurate gas estimation and transaction validation. | | `excludedSources` | (Optional) Specifies liquidity sources to exclude (e.g., Uniswap, SushiSwap). Cannot be combined with `includedSources`. | | `includedSources` | (Optional) Specifies liquidity sources to include. Cannot be combined with `excludedSources`. | | `integratorPercentageFee` | (Optional) Fees to be charged. Example: 1% → `0.01`, 0.1% → `0.001`, 0.025% → `0.00025` | | `integratorRecipientAddress` | (Optional) HyperEVM address to receive fees specified with `integratorPercentageFee`. Both `integratorPercentageFee` and `integratorRecipientAddress` are required together. | {/* | `buyTokenPercentageFee` | (Optional) Percentage (0 - 1.0) of `buyAmount` attributed to `feeRecipient` as affiliate fees. Requires `feeRecipient` parameter. | */} {/* | `buyAmount` | (Optional) The amount of `buyToken` (in base units) you wish to receive. Either `sellAmount` or `buyAmount` must be included. Note: Some on-chain sources do not support `buyAmount`, excluding them if used.| */} {/* | `gasPrice` | (Optional, defaults to ethgasstation "fast") Target gas price (in wei) for the swap transaction. An error is returned if the price is too low to achieve the quote. | */} {/* | `skipValidation` | (Optional) Skips quote validation when set to `true`. Default for `/quote` is `false`, but can be overridden. | */} {/* | `priceImpactProtectionPercentage` | (Optional, defaults to 100%) Allowed price impact percentage. If estimated price impact exceeds this, an error is returned. Default value of 1.0 disables the feature. | */} ### Response Schema The response schema for `/swap/v1/price` is identical to `/swap/v1/quote`, except the `guaranteedPrice`, `to`, and `data` fields are always undefined. #### Response Fields | Field | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `price` | Provides the price of `buyToken` in `sellToken` and vice versa, excluding slippage. Includes fee if `buyTokenPercentageFee` and `feeRecipient` are set. | | `estimatedPriceImpact` | Estimated change in asset price due to swap execution. Returns `null` if estimation fails. | | `value` | Ether amount (in wei) to be sent with the transaction. | | `gasPrice` | Gas price (in wei) for transaction submission. Must be equal to or lower than this value for success. | | `gas` | Estimated gas limit for transaction settlement. Accurate estimate requires `takerAddress`. | | `estimatedGas` | Estimated actual gas usage, always less than `gas`. | | `protocolFee` | Maximum ether amount for protocol fee (in wei). | | `minimumProtocolFee` | Minimum ether amount for protocol fee (in wei). | | `buyAmount` | Amount of `buyToken` to be acquired. Excludes sources not supporting `buyAmount`. | | `sellAmount` | Amount of `sellToken` to be sold. Recommended for comprehensive on-chain source coverage. | | `sources` | Distribution of `buyAmount` or `sellAmount` across liquidity sources. | | `buyTokenAddress` | ERC20 token address for `buyToken`. | | `sellTokenAddress` | ERC20 token address for `sellToken`. | | `allowanceTarget` | Contract address requiring allowance for swap completion. Null address for "ETH" swaps. | | `sellTokenToEthRate` | Exchange rate between ETH and `sellToken`. | | `buyTokenToEthRate` | Exchange rate between ETH and `buyToken`. | {/* | `fees` | Fees to be charged, may include `zeroExFee`. | */} {/* | `grossPrice` | Similar to `price` but excludes fees. | */} {/* | `grossBuyAmount` | Similar to `buyAmount` but excludes fees. | */} {/* | `grossSellAmount` | Similar to `sellAmount` but excludes fees. | */} ### Example **Get Price for Selling WETH to Buy feUSD** To obtain a simple quote for exchanging 1 HYPE for feUSD, specify the `sellToken`, `buyToken`, and `sellAmount`. **Request** ```bash curl https://api.hyperbloom.xyz/swap/v1/price?sellToken=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&buyToken=0x02c6a2fa58cc01a18b8d9e00ea48d65e4df26c70&sellAmount=1000000000000000000 --header 'api-key: ' ``` **Response** ```json { "chainId": 999, "price": "36.749874001264005", "estimatedPriceImpact": "0", "value": "600000000000000000", "gasPrice": "47500000", "gas": "389135", "estimatedGas": "389135", "protocolFee": "0", "minimumProtocolFee": "0", "buyTokenAddress": "0x02c6a2fa58cc01a18b8d9e00ea48d65e4df26c70", "buyAmount": "22049924400758403000", "sellTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "sellAmount": "600000000000000000", "sources": [], "orders": [], "allowanceTarget": "0x0000000000000000000000000000000000000000", "sellTokenToEthRate": "1", "buyTokenToEthRate": "35.297931189190104285", "expectedSlippage": null } ``` # API Overview Source: https://docs.hyperbloom.xyz/api-reference/overview Introduction to the HyperBloom API The HyperBloom Swap API functions as a central hub for liquidity and data within the DeFi space, facilitating access to aggregated liquidity from a multitude of decentralized exchange networks, both on-chain and off-chain, across various blockchain platforms. It offers a comprehensive set of parameters to customize your requests according to your application's and users' specific requirements. We offer hosted solutions for the HyperEVM ecosystem. API Endpoint: `https://api.hyperbloom.xyz/` ## Endpoints Explore the various endpoints available in the Swap API: * `GET /swap/v1/quote` - Retrieve a straightforward quote for purchasing or selling any ERC20 token. This endpoint returns a transaction that can be executed on a HyperEVM node. * `GET /swap/v1/price` - The `/price` endpoint is similar to `/quote`, with some key distinctions. Unlike `/quote`, `/price` does not return a transaction for on-chain submission; it simply provides the same data. Consider it the `read-only` counterpart of `/quote`. * `GET /swap/v1/sources` - Provides the liquidity sources that are active for a specified blockchain. ## Authentication HyperBloom secures your API requests through your account's API keys. Once configured, ensure you include your key using the `api-key` header parameter in your requests. **To obtain an API key, please reach out to the HyperBloom team.** # Audits Source: https://docs.hyperbloom.xyz/audits Understand the audits of HyperBloom We have conducted one audit by Pashov Audit Group for HyperBloom Auto-Compounding Vaults from which all issues have been fixed. HyperBloom Security Review # 🔄 DEX Aggregator Source: https://docs.hyperbloom.xyz/concepts/dex-aggregator Understand the ideology behind the DEX Aggregator Hyperbloom’s DEX Aggregator delivers optimal trading outcomes by combining intelligent routing with efficient on-chain execution. ### Hyperbloom Smart Contract All trades are executed through the HyperBloom smart contract, deployed securely on-chain. * **Single Transaction Execution** Users complete their swaps in a single transaction, improving speed and reducing gas consumption. * **Secure, On-Chain Execution** Trades are handled in a trustless and non-custodial manner. Users retain full control of their assets throughout the process. ### Supported DEXs Hyperbloom currently aggregates liquidity from the following decentralized exchanges: * HyperSwap * KittenSwap * Curve * Laminar * Gliquid * Hybra * HyperCat * ProjectX * Valantis * Ramses Support for additional DEXs and chains is actively in development. # 💰 Fee Structure Source: https://docs.hyperbloom.xyz/concepts/fee-structure Understand the fee structure of HyperBloom ### Auto-compounding Vaults * **No deposit fees.** * **5% performance fee** on profits only. * Fees cover compounding costs and protocol maintenance. * APYs shown are **net of fees** — no need for manual calculations. ### DEX Aggregator * `0.025%` trading fees on all trades. * Positive slippage is captured by HyperBloom. # 🔒 Locker Source: https://docs.hyperbloom.xyz/concepts/locker Understand the ideology behind the HyperBloom locker The HyperBloom Locker enables users and external projects to securely lock ERC20 tokens or ERC721 NFTs for a specified duration. It's a simple, trustless tool designed for team vesting, liquidity locks, or community campaigns. ### 🔒 What is the Locker? The Locker is a non-custodial smart contract that holds your tokens until the chosen vesting duration ends. Once locked, tokens cannot be withdrawn or accessed until the vesting period is complete. HyperBloom Locker supports: * **ERC20** token locking * **Fixed locks**: Tokens are released in full after the period ends. * **Linear locks**: Tokens unlock gradually over time. * **ERC721** NFT locking # 🏦 Auto-compounding Vaults Source: https://docs.hyperbloom.xyz/concepts/yield-optimizer Understand the ideology behind the HyperBloom vaults When you deposit into a vault, the contract transfers your assets to a **strategy** that dynamically optimizes your liquidity position and continuously adjusts + compounds rewards to maximize your APY while minimizing unnecessary swaps and gas costs. In return, you receive **Vault Tokens**, which represent your claim on the original deposit plus any yield earned. When you’re ready to withdraw, simply return your Vault Token, and the vault sends back your underlying assets with all accumulated rewards. Vaults ### YieldIQ Strategy **YieldIQ** is powered by on-chain algorithms that dynamically adjust your positions to optimize yield and mitigate risk — all without manual intervention or external scripts. Below is a detailed look at how it works. ## 1. Single-Token Deposits ### 1.1 Why Single-Token Deposits? Traditional liquidity pools require two assets in a fixed ratio (e.g., 50/50), often leading to swap costs and exposure to volatility. YieldIQ simplifies this by allowing **single-token deposits**, so you can: * Deposit just one token (e.g., your project’s native token or a stablecoin). * Receive a **Vault Token** representing your share of the underlying liquidity pool. * Avoid unnecessary swaps that might dilute your position in volatile markets. ### 1.2 Directional Liquidity Depositing a single token also tells the strategy **which asset you prefer to hold** in greater quantity. YieldIQ’s algorithm automatically avoids over-selling that asset, maintaining a higher inventory of your preferred token. ## 2. Inventory-Based Rebalancing ### 2.1 Core Concept Instead of reacting to every price movement, YieldIQ tracks your **inventory ratio** — how much of each token you hold within the pool. Rebalancing only occurs when the pool’s composition deviates from a predefined target range. This reduces unnecessary swaps and gas fees while maintaining optimal liquidity exposure. **Key States:** * **Healthy:** Liquidity is well-balanced and earning fees efficiently. * **Over-Inventory:** You hold too much of your deposited token; the strategy may sell a portion to rebalance. * **Under-Inventory:** You hold too little; the strategy buys more to restore target levels. * **High Volatility:** The strategy broadens price ranges to mitigate risk. * **Extreme Volatility:** The vault may lock temporarily or require manual review for safety. ### 2.2 No Swap Costs in Rebalancing Because YieldIQ tracks deposits natively, it often repositions liquidity **without performing swaps**. This reduces gas usage and avoids unnecessary selling or buying of your core token unless absolutely necessary. ## 3. On-Chain Autonomy ### 3.1 100% Smart Contract Logic All YieldIQ functions operate entirely **on-chain** — without any privileged controller or off-chain script. This ensures: * **Transparency:** Every rebalance is verifiable on the blockchain. * **Fairness:** No entity can adjust positions for their own benefit. * **Security:** Funds remain under your control; no private keys or custodial access are required. ### 3.2 Automated Triggering Rebalances happen automatically based on **inventory thresholds, price triggers, or time intervals** defined in each vault’s parameters. You never need to pay extra gas fees or manually babysit the vault. ## 4. Yield Generation ### 4.1 Trading Fees As traders interact within your liquidity range, you earn a proportional share of trading fees. YieldIQ’s concentrated liquidity strategy keeps your position “in-range” as much as possible, **maximizing fee collection and auto-compounding yield** back into your position. *(In VE33’s, trading fees are routed to voting gauges.)* # DEX Aggregator Source: https://docs.hyperbloom.xyz/faq/dex-aggregator Frequently Asked Questions about DEX Aggregator ### Which DEXs are integrated? HyperBloom has **the most DEX integrations on HyperEVM**: * ✅ HyperSwap * ✅ KittenSwap * ✅ Curve * ✅ Laminar * ✅ Gliquid * ✅ Hybra * ✅ HyperCat * ✅ ProjectX * ✅ Ramses * ✅ Valantis * ✅ Balancer * 🔜 More coming soon ### Fees & Pricing **Swap fee**: 0.025% on all trades * Fee is already included in displayed output * No hidden costs * Positive slippage captured by protocol **Why use HyperBloom vs direct DEX?** * Better rates through multi-hop routing * Single transaction for complex routes * Access to all liquidity in one place * Automatic route optimization ### Common Swap Issues ### Transaction Failures **Causes**: * High slippage in volatile markets * Insufficient liquidity * Gas estimation issues * Stale quotes **Solutions**: * Increase slippage tolerance * Try smaller amounts * Refresh quote before swapping * Check specific pair liquidity ### Token Approval Issues **Current**: Need approval for each new token  **Coming:** Infinite approval option **Tip**: Approve larger amounts to reduce repeated approvals ### Routing Explained * **Multi-hop**: Can route through multiple DEXs in one swap * **Parallel paths**: Splits large trades for better rates * **Transparent**: See exact route before confirming * **Optimized**: Algorithm finds best combination of paths ### Adding Unlisted Tokens 1. Click on token selector 2. Paste token contract address 3. Click "Import" 4. Token now available for swapping ### Slippage Settings * **Default**: 1% * **Stable swaps**: 0.1-0.3% * **Volatile pairs**: 1-3% * **New tokens**: 5-10% Always check minimum received amount! # General Source: https://docs.hyperbloom.xyz/faq/general General questions about HyperBloom ### What is HyperBloom? HyperBloom is a DEX Aggregator and Yield Optimizer on HyperEVM. We provide: * **DEX Aggregator**: Finding the best swap rates across multiple DEXs * **Auto-compounding Vaults**: Maximizing yields through automated compounding * **Token/NFT Locker**: Secure locking for vesting and liquidity management ### Does HyperBloom have a token? No, HyperBloom does not have a token yet. Any tokens claiming to be HyperBloom are scams. We will announce through official channels when/if we launch a token. ### Will HyperBloom expand to other chains? Currently, we're focused on HyperEVM. ## Support & Community ### Official Channels * **Twitter**: [@hyperbloomxyz](https://twitter.com/hyperbloomxyz) * **Telegram**: [Join here](https://t.me/hyperbloomhl) * **Discord**: [Join here](https://discord.gg/AePtFQ57ft) * **Docs**: [docs.hyperbloom.xyz](https://docs.hyperbloom.xyz/) * **App**: [hyb.ag](https://hyb.ag/) ### Reporting Bugs **What to include**: * Exact error message * Transaction hash * Browser/wallet used * Steps to reproduce * Screenshots if possible **Where to report**: * [Telegram](https://t.me/hyperbloomhl)/[Discord](https://discord.gg/AePtFQ57ft) (help-ticket channel) for general bugs and security issues ### Team Contacts * **@jakubals**: Partnerships and Biz * **@kodziak**: Technical and UI/UX * @khendzel: Marketing ### Scam Prevention ⚠️ **Team will NEVER**: * DM you first * Ask for private keys * Request funds * Offer "support" via DM *** *Last updated: July 2025.* *For latest updates, follow [@hyperbloomxyz](https://twitter.com/hyperbloomxyz)* # Locker Source: https://docs.hyperbloom.xyz/faq/locker Frequently Asked Questions about Locker ### What is the Locker? A secure, non-custodial smart contract for time-locking: * **ERC20 tokens**: For vesting, liquidity locks, or holding * **ERC721 NFTs**: For collections and special campaigns * **Use cases**: Team vesting, liquidity locks, commitment campaigns ### Lock Types Explained ### Fixed Lock * All tokens unlock at end date * No early access * Best for: Definitive holding periods ### Linear Lock * Tokens unlock gradually * Can claim portions as they vest * Best for: Salary vesting, gradual releases ### Frequently Asked Questions **Q: Can I unlock early?**  A: No. This is a security feature. Choose your lock period carefully. **Q: Do locked tokens earn points?**  A: Coming soon! All locking activity is tracked for retroactive points. **Q: I locked my NFT but lost Discord roles?**  A: When you lock an NFT, it transfers to the locker contract. Some Discord bots can't see locked NFTs. **Q: What's the "claim" button in my locker?**  A: For linear locks only - lets you claim vested portions. ### Locker Fees * **Locking fee**: FREE * **Unlocking fee**: FREE * **No platform charges** ### Security Notes * Locker contract is non-custodial * Only you can unlock (after period ends) * Lost wallet = lost access # Vaults Source: https://docs.hyperbloom.xyz/faq/vaults Frequently Asked Questions about DEX Aggregator ### How do vaults work? 1. **Deposit**: Put in a pair of tokens or single assets 2. **Receive**: Get tokens as your receipt and share of the vault 3. **Earn**: Vaults compound your rewards automatically 4. **Withdraw**: Give back received tokens to get your assets + profits ### What makes HyperBloom vaults special? * **Auto-rebalancing every 10 minutes**: Keeps positions in optimal range * **Smart harvesting**: Bot checks gas prices before compounding * **Range management**: Automatically adjusts to market conditions * **Multiple range options**: From ±2% to ±10% depending on pool ### Vault Fees Structure * **Deposit fee**: 0% (FREE) * **Performance fee**: 5% on profits only * **Withdrawal fee**: 0.1% (goes to other vault users, not team) * **Hidden fees**: NONE - APYs shown are net of all fees ### Vault Ranges Explained | Vault Type | Range | Rebalance Frequency | Risk Level | | ------------ | ----- | ------------------- | ------------------ | | Aggressive | ±2% | Every 10 minutes | Higher risk/reward | | Moderate | ±5% | Every 10 minutes | Balanced | | Conservative | ±10% | Every 10 minutes | Lower risk/reward | ### Performance Tracking **Current features**: * View deposited amounts * See current value * Track APY **Coming soon**: * Detailed P\&L breakdown * Fees earned display * Historical performance * IL calculator # Introduction Source: https://docs.hyperbloom.xyz/index Learn about the HyperBloom ecosystem Hero Dark **What is HyperBloom?** HyperBloom is a **DeFi SuperApp** built on HyperEVM that offers all needed tools for navigating through the House of Finance. HyperBloom offers seamless swap infrastructure connected to all major exchanges on HyperEVM and liquidity from HyperCore together with **non-custodial vaults** that let you earn **compound interest** on liquidity pools. Our smart contracts automatically route your assets through HyperEVM DeFi protocols. With **HyperBloom**, you get **the best rates for swaps** & **highest APYs possible** through automated strategies. Open HyperBloom App Swap tokens across HyperEVM ecosystem on multi-market DEX Aggregator Deposit your assets into HyperBloom vaults to earn compound interest Earn HB points by using HyperBloom # 🌸 Points Source: https://docs.hyperbloom.xyz/points/points Understand the points system of HyperBloom The **HyperBloom Points Program** rewards users for their on-chain activity. Whether you’re swapping tokens or earning yield through vaults, your participation helps grow the ecosystem. ### How It Works Users accumulate points based on activity in two core areas: * **Swapping**: Every swap made through the Hyperbloom DEX Aggregator earns points based on trade volume * **Vaults**: Depositing assets into Hyperbloom Vaults generates points, scaled by deposit amount and time staked * **Locker:** Locking your assets in HyperBloom generates points Points are calculated and **distributed every Thursday at 3 PM CET**. # FAQ Source: https://docs.hyperbloom.xyz/points/points-faq Frequently asked questions about the HyperBloom Points Program **Wanna play a game?** Track your progress by using HyperBloom services and join the HyperBloom Points game. Become an active HyperBloom community member—climb the leaderboard and earn points! ### FAQ **Q: What is this all about?**\ A: You can collect points by using HyperBloom services and reach higher tiers. In the future, we may introduce additional elements or features to the game. **Q: How do points work?**\ A: You collect points by using the HyperBloom services such as the SWAP Instruction Transfer, the VAULT Smart Contract, the LOCKING Smart Contract and the REFERRAL (as described in the [Terms](https://app.hyperbloom.xyz/files/terms-of-service.pdf)). The points are calculated once a week every Thursday at 3:00 PM CET. **Q: Can I win anything?**\ A: The more points you have, the higher your tier and rank on the leaderboard. **Q: What tiers are there?**\ A: There are five tiers: * **Seeder**: 1-99 points * **Grower**: 100-499 points * **Vegeter**: 500-1,499 points * **Harvester**: 1,500-4,999 points * **Bloomer**: more than 5,000 points **Q: What can I do with points?**\ A: You can increase your tier and rank on the leaderboard. The points are non-tradable (you can’t sell or buy them), non-exchangeable (you can’t exchange them for any currency, goods, assets, or services), and non-transferable (you can’t give them to another person). # Getting Started Source: https://docs.hyperbloom.xyz/widget/getting-started Learn how to set up the HyperBloom widget HyperBloom offers two types of widgets to enhance your web application's functionality: the `Package Manager Widget` and the `Iframe-based Widget`. This guide will help you understand and configure both types. ### Iframe-based Widget The Iframe-based Widget is a quick and easy solution for those who want to embed the widget without altering their codebase significantly. It can be configured and accessed through our dedicated widget configuration page. To configure the Iframe-based Widget, visit the following link: Configure HyperBloom widget ### Package Manager Widget (Coming Soon) The Package Manager Widget is designed for developers who prefer integrating directly into their codebase. It can be installed via popular package managers, allowing for seamless integration and customization within your development environment. This widget type is ideal for those who want full control over the widget's behavior and appearance. ### Key Features of the HyperBloom Widget * **Wide Ecosystem Support**: Compatible with all exchanges HyperBloom supports. * **Customizable Settings**: Configure to allow or restrict specific chains and tokens. * **Theming Options**: Pre-set themes and customization options, including dark mode, to match your app's aesthetics. * **SDK Ecosystem**: Built on libraries such as Viem and Wallet Standard. * **Wallet Management**: Curated wallet lists and bookmarking capabilities. * **Advanced Route Settings**: Local storage of advanced settings for power users. By understanding these options, you can choose the widget type that best fits your needs and enhance your application's capabilities with HyperBloom's powerful tools.