# Welcome to Liminal {% hint style="info" %} This documentation is continuously updated as Liminal evolves. {% endhint %} ### Introduction Liminal is Hyperliquid’s Native Yield Layer, designed to capture every yield sources offered by Hyperliquid and distribute them through fully automated strategies across all ecosystems. Liminal offers two product lines: Customized and Tokenized. Tokenized includes xTokens for asset-level yield and limUSD for portfolio-optimized USD yield. Whether you’re a retail user, institution, protocol, or a treasury, one of Liminal’s two products is built for you. Together, these products make Liminal the Native Yield Layer of Hyperliquid: transparent, automated, and open to all. # What is delta-neutral? Delta-neutral strategies are the foundation of Liminal. They aim to capture consistent returns from structural market mechanisms, including funding payments, lending rates, and other on-chain yield sources, while maintaining zero directional exposure to price movements. This method, long used by professional trading desks, is designed to make capital work efficiently, without relying on speculation or price appreciation. #### 1. Understanding “Delta” In trading, delta measures how much a position’s value changes when the underlying asset’s price fluctuates. It reflects the sensitivity of a portfolio to price fluctuations. * A position with delta = 1 moves one-to-one with the asset’s price. → Example: if you hold 1 ETH and price goes up, it means your portfolio value increases accordingly. * A position with delta = –1 moves inversely to the asset’s price. → Example: being short 1 ETH perpetual means your value rises if ETH goes down. * When positions are balanced so that total delta = 0, the exposure is delta-neutral, unaffected by price changes in either direction. Mathematically: > Δ(total) = Σ (Δᵢ × Position Sizeᵢ) = 0 When this condition is met, the portfolio becomes insensitive to market price movements. This doesn't mean the portfolio is inactive, it simply means its profit and loss no longer depend on whether the market goes up or down. Instead, returns come from structural variables, such as funding payments or lending rates, which exist independently of price direction.
#### 2. The Logic Behind Delta-Neutrality Financial markets constantly create structural imbalances between participants, and these imbalances generate predictable yield flows that delta-neutral strategies can capture. One well-known source is the perpetual futures market. Perpetual futures require a funding mechanism, periodic payments between long and short traders, to keep perpetual prices anchored to spot prices. \ When most traders are long, funding turns positive and short traders receive payments. \ When most are short, funding becomes negative and longs receive payments. A delta-neutral strategy running long spot and short perp captures these payments consistently, without taking any directional bet on the underlying asset price. A second structural source is the on-chain lending market. Borrowers pay interest to access liquidity, regardless of whether the market is rising or falling. As long as there is demand to borrow, lenders earn a rate that exists independently of price direction. \ For example, a strategy that supplies stablecoins to a money market earns the lending rate with zero exposure to the price of the underlying asset, making it structurally delta-neutral by design. In both cases, the yield stems from market structure itself, not from token emissions, price appreciation, or speculative positioning. #### 3. Understanding Yield Sources Delta-neutral strategies on Liminal can draw yield from two distinct structural mechanisms. Each operates independently of asset price direction. Yield Source 1 : Funding Rates \ Funding rates are periodic payments exchanged between long and short traders in perpetual futures markets. They exist to keep perpetual contract prices aligned with spot prices, as perpetual futures have no expiry date. When the majority of traders are long, funding turns positive and longs pay shorts. Even in balanced conditions, perpetual markets exhibit a baseline funding rate, known as neutral funding, reflecting the structural equilibrium between participants. On Hyperliquid, this neutral funding rate historically averages around 10.95% annualized. Strategies like xHYPE and xBTC capture this yield by running long spot and short perp simultaneously, remaining neutral to price while collecting funding flows.\ In addition, when applicable, these strategies also capture staking yield on the underlying asset, further enhancing returns without introducing directional exposure. Yield Source 2 : Lending Rates\ On-chain money markets generate interest by connecting lenders and borrowers. Borrowers pay a rate to access liquidity, whether to leverage a position, hedge, or simply bridge a cash need. This borrowing demand exists in all market conditions: in bull markets, traders borrow to increase exposure; in bear markets, they borrow to short or to manage collateral. The lending rate is therefore a structural yield that does not depend on price direction. It cannot turn negative: if the rate drops toward zero, lenders withdraw capital, reducing supply and mechanically pushing the rate back up. \ \ Strategies like xLEND capture this yield by supplying liquidity to money markets, with no directional exposure to any underlying asset price.\ \ Liminal is designed to continuously expand its yield capture surface as the Hyperliquid ecosystem evolves. Beyond funding and lending, the protocol will progressively integrate additional structural yield sources, including carry trades on traditional assets enabled by HIP-3, as well as options-based strategies and new primitives introduced through HIP-4. Each new primitive expands the opportunity set. Liminal’s architecture is built to aggregate, optimize, and distribute these yields into unified, delta-neutral strategies. #### 4. Neutrality in Practice Being delta-neutral doesn’t mean being passive. Because markets evolve, maintaining neutrality requires continuous balancing between long and short positions as prices move. In traditional finance, this is achieved through dynamic hedging or options portfolios. In DeFi, it typically involves spot and perpetual markets or lending protocols, where exposure can be adjusted or structured in real time on-chain. The objective is to keep: * Δ ≈ 0 → near-zero price sensitivity * Leverage balanced → stable margin requirements, * Yield exposure optimized → capturing net positive structural flows. Even as volatility fluctuates, the portfolio remains focused on yield consistency, rather than making directional bets. #### 5. Why Delta-Neutral Matters Delta-neutrality represents one of the few ways to earn real yield in crypto, a yield that stems from market demand and trading activity, not token inflation or rewards. This is why it has become a cornerstone of modern on-chain strategies. By design, it offers: * **Capital preservation:** price-neutral exposure protects against large swings. * **Diversified return profile:** earnings come from market behavior, not price trends. * **Predictable yield sources:** funding rates and lending rates are both transparent, measurable, and verifiable on-chain in real time. * **Sustainability:** as long as there is market activity like leverage demand, borrowing demand, or trading volume, structural yield persists. It’s a structure that thrives on market activity rather than price direction, producing real yield that remains resilient across diverse market environments. #### 6. The Liminal Perspective Liminal builds on this principle to make delta-neutral yield accessible, automated, and transparent. Rather than requiring users to manually hedge, rebalance, or monitor positions, Liminal abstracts this complexity away and provides a fully market-neutral yield layer built on the structural mechanics of on-chain markets, including perpetual futures and lending protocols. The focus is not on predicting markets, but on understanding and systematizing the flows within them. That’s what enables Liminal to deliver yield that is both real and structurally grounded in the dynamics of modern on-chain trading. # Liminal’s Two Product Lines ### Liminal’s Two Product Lines Liminal offers two complementary ways to access **delta-neutral yield**, both available at any time depending on your needs and custody preferences. #### **1. Liminal Customized** Liminal Customized is the original product line, designed for users who want maximum control, transparency, and customization. Each user runs their strategy in a segregated account, ensuring that positions remain fully isolated and independently managed. Users can put each asset into a delta-neutral position and choose the leverage they want to apply, effectively choosing the degree of capital allocated toward capturing funding yield on specific perpetual markets. Execution and rebalancing are handled automatically by Liminal, while each strategy operates independently on Hyperliquid infrastructure. Two custody modes are available: * Regular Mode: Liminal manages a linked account (EOA) on your behalf. Keys are encrypted and operated within secure enclaves, never exposed or shared. * Self-Custody Mode: For institutions or advanced users, Liminal executes trades directly on your Hyperliquid subaccount using the native Agent system. Liminal has no withdrawal access, keeping full ownership in your hands. This setup combines institutional-grade infrastructure with a fully transparent and verifiable on-chain architecture. #### **2. Liminal Tokenized (xTokens and limUSD)** Liminal Tokenized, represents the next evolution of delta-neutral yield, packaging Liminal’s strategies into pooled, omnichain tokens designed for seamless use across DeFi. For example, xHYPE represents a pooled delta-neutral strategy on $HYPE, xBTC on $BTC, and so on.\ For users seeking optimized yield with no operational overhead, limUSD provides a turnkey solution that dynamically allocates across xTokens and money market yield. By depositing stablecoins, users mint xTokens or limUSD that automatically accrue in value as structural yield is captured. Each vault aggregates all user deposits into a single institutional-grade delta-neutral strategy running directly on Hyperliquid.\ This pooled design improves execution efficiency, reduces costs, and increases net yield reflected in each token's on-chain value. As tokens with omnichain support, they are: * Portable and composable: transferable across HyperEVM and other EVM chains via a hub-and-spoke architecture (LayerZero-powered). * Fully composable within DeFi: usable as productive collateral by providing liquidity on AMMs, borrowing stablecoins against it, and trading the underlying yield on yield derivatives markets. * Frictionless: no setup required, no account management, instant yield exposure. This product line makes delta-neutral yield accessible through a simple, token-based interface, combining on-chain transparency, cross-chain mobility, and DeFi-native liquidity. #### **In Summary** * **Choose *****Customized*** for **maximum control**, **tailored strategies**, and **self-custody optionality.** * **Choose *****Tokenized*** for **portability**, **capital efficiency**, **scalability**, and **seamless DeFi integration.** Both product lines rely on the same foundation, automated delta-neutral yield strategies on Hyperliquid, but serve different user profiles and needs. # Introduction The Tokenized product line is Liminal’s cross-chain, pooled approach to delta-neutral yield on Hyperliquid. It is built around two complementary layers: xTokens, which capture yield from a single market or source, and limUSD, which aggregates yield across multiple sources at the portfolio level. ### xTokens, Asset-Level Yield xTokens are omnichain OFT tokens that each represent a share in a pooled delta-neutral strategy for a specific market or yield source. Instead of each user running their own strategy, capital is aggregated into one institutional-grade strategy per market. Users deposit stablecoins and receive yield-bearing xTokens in return. As the underlying strategy earns structural yield, from funding rates, lending rates, or staking rewards depending on the xToken, each xToken automatically increases in value over time. Each xToken captures yield from a specific structural source on Hyperliquid: * $xHYPE → delta-neutral strategy on $HYPE * $xBTC → delta-neutral strategy on $BTC * $xLEND → delta-neutral lending yield from on-chain money market rates * …and more as new markets are added. ### limUSD, Portfolio-Level Yield While xTokens give exposure to a single yield source, limUSD sits one level above: it dynamically allocates across multiple xTokens and money market strategies to maximize risk-adjusted USD yield. Depositors mint limUSD with stablecoins and receive a single token whose value grows as the underlying portfolio earns. Allocation decisions are managed by Liminal, so holders benefit from diversified yield without needing to rebalance between strategies themselves. For a full breakdown, see the dedicated *limUSD* page. ### Natively Cross-Chain Thanks to a hub-and-spoke architecture powered by LayerZero, all Tokenized products, xTokens and limUSD alike, are natively cross-chain: * Users can mint by depositing stablecoins from any supported chain (HyperEVM, Arbitrum, Ethereum, etc.), or directly from their Hyperliquid balance. * They receive an OFT token on the chain of their choice, while the strategy itself is managed on Hypercore/HyperEVM. * Tokens can move freely between supported chains, so users can mint on one chain, bridge, and use them on another. Because they are omnichain OFTs, all Tokenized products are: * Liquid: easy to trade or exit. * Transferable: move between wallets and chains. * Composable: plug directly into DeFi primitives (collateral, liquidity pools, lending markets, yield derivatives, and more). In short, the Tokenized line turns Liminal’s delta-neutral yield strategies on Hyperliquid into cross-chain, plug-and-play yield primitives, from single-market exposure with xTokens to diversified, hands-off USD yield with limUSD, that can be held passively or actively integrated into DeFi across multiple ecosystems. # About xTokens Each xToken mirrors Liminal Customized’s delta-neutral strategies but is managed via a single pooled position. Let’s dive into how xTokens work: #### **1. Pooled Capital** When users mint xTokens with stablecoins, their deposits are grouped into one shared strategy for that market. Instead of running many small positions, Liminal Tokenized operates a single pooled delta-neutral line, and each xToken represents the holder’s share of it. #### **2. Delta-Neutral Position** The structure of the delta-neutral position depends on the yield source of the xToken. For asset-based xTokens such as xHYPE and xBTC, stablecoins are used to open a two-legged position on the underlying asset. The long spot leg acquires direct exposure using native assets and, where available, Liquid Staked Tokens to earn staking yield on top of funding. The two legs offset each other directionally : the portfolio holds the asset but is short the same amount in perps, resulting in delta approximately equal to zero. For lending-based xTokens such as xLEND, stablecoins are deployed directly into on-chain money markets. There is no spot position and no perpetual short. Delta-neutrality comes from the nature of the instrument itself, lending rates are generated by borrower demand and do not depend on asset price direction. The strategy earns the lending rate as yield while maintaining zero directional exposure. #### **3. Yield & Token Value** The strategy continuously earns structural yield from its position, whether funding payments, lending rates, or staking rewards depending on the xToken type. These earnings accumulate in real time, increasing the overall value of the xToken. **For holders, the process is seamless: just hold xTokens and watch them appreciate over time.** #### **4. Oracle** An **oracle** updates the **on-chain value of the xToken** to reflect accumulated yield. For example, 1 $xHYPE initially starts at $1, if the strategy earns 5%, **its price-per-share will update to $1.05**. This ensures transparency and accurate redemption. #### **5. Custody and Management** Underlying assets are secured by institutional-grade custodians and smart contracts. \ For asset-based xTokens, this covers stablecoins, spot positions, and perpetual futures.\ For lending-based xTokens, this covers stablecoins held in lending protocol smart contracts. #### **6. Scalability & Limits** Because strategies are pooled, Tokenized can handle larger total capital per asset more efficiently than individualized accounts. Each pooled strategy will still have prudent TVL caps based on the capacity of its underlying market, whether perpetual market depth for funding-based xTokens or lending pool capacity for lending-based xTokens, but per-user limits can be higher since everyone shares a single large position. Operationally, one consolidated strategy is also easier to manage than many smaller ones, making Tokenized inherently more scalable. # About limUSD ### What is limUSD Hyperliquid’s Native Yield is fragmented and emerges from multiple underlying sources: funding rates, staking rewards, and money markets. limUSD is the USD expression of this native yield, unifying it into a single, accessible primitive. Built on top of xTokens, limUSD acts as a unified access point to Hyperliquid’s full yield opportunity set, dynamically positioning capital where it can be most effectively deployed. Where individual xTokens (xHYPE, xBTC, xLEND) expose yield at the asset level, limUSD operates one layer above as a portfolio-level allocator across xTokens. Instead of holding a single delta-neutral strategy, limUSD maintains a dynamic basket of xTokens. ### How limUSD Works limUSD operates as a meta-strategy that continuously routes capital toward the most attractive expressions of Hyperliquid’s Native Yield. Token Mechanics * Price: Its price starts at $1 and increases as the underlying strategy earns yield from funding rates and money market yield. * Minting: Users can mint limUSD using stablecoins such as $USDC, $USDT0 or $USDT directly from their Hyperliquid balance, HyperEVM, Ethereum, or Arbitrum. * Yield: Once minted, users benefit from limUSD’s yield automatically, simply by holding it. There is no staking step or further action required. * Passive: The yield is embedded in the token itself. Mint limUSD [here](https://liminal.money/app/tokenized/limusd). ### From Asset-Level to Portfolio-Level Holding individual xTokens requires choosing which asset to allocate to and rebalancing as conditions evolve. limUSD removes that overhead by automating allocation across the full set of available yield sources. As Hyperliquid’s ecosystem grows and new yield sources emerge (carry trades on new asset classes, HIP-3 instruments, money market expansions), limUSD’s opportunity set widens automatically. Allocation becomes the primary driver of performance, and it’s handled entirely by the protocol. ### xTokens vs limUSD

xTokenslimUSD
LevelAsset-levelPortfolio-level
ControlUser chooses specific assetAutomated allocation
Yield sourceSingle carry strategyDynamic basket of xTokens
Best forPrecision & asset-level controlOptimized yield, no operational overhead
ManagementRequires allocation decisionsFully automated, turnkey solution
Both coexist. xTokens provide the foundation, limUSD optimizes across them. For users who value precision and asset-level control, xTokens are the right tool. For those seeking optimized yield with no operational overhead, limUSD provides a turnkey solution. ### DeFi Composability Like xTokens (see *Composability and DeFi*), limUSD is fully composable across the DeFi ecosystem. It can be used as productive collateral on money markets, paired in AMM pools to earn additional swap fees, or split into PTs and YTs on yield-derivative platforms like Pendle. The key difference is that while xTokens expose yield from a single strategy, limUSD offers a diversified, auto-optimized yield profile as the underlying collateral. This makes it particularly suited as a base yield layer in DeFi strategies where users want optimized performance without managing allocations themselves. As limUSD gets integrated across partner protocols, it may also accrue ecosystem incentives (points, rewards) that are redistributed to holders at the vault level. ### Scaling with Hyperliquid’s Infrastructure As Hyperliquid expands into new asset classes, limUSD’s opportunity set expands with it. HIP-3s enable permissionless market creation directly on Hyperliquid, allowing new commodities, equities, and alternative assets to be listed natively, broadening the surface from which limUSD can source yield. The progressive roll-out of Portfolio Margin across xTokens represents the next structural step. As unified margining improves capital efficiency, reduces idle buffers, and enables cleaner carry execution at the pooled level, limUSD will benefit from higher net performance for holders. Improvements at the execution layer (xTokens) compound at the aggregation layer (limUSD). Over time, limUSD reflects the full breadth of Hyperliquid’s funding economy in one composable, yield-bearing primitive. ### Availability limUSD is natively available on HyperEVM, Ethereum, and Arbitrum. The strategy is executed on Hyperliquid’s infrastructure, while the asset itself circulates across supported chains. Wherever limUSD is deployed, the underlying collateral continues to accrue yield. Mint limUSD [here](https://liminal.money/app/tokenized/limusd). # Minting, Redeeming and Bridging ### 1. How to mint xTokens & limUSD (Deposit) 1. Choose your Token and Destination Chain: Select which token you want to mint (e.g. $xHYPE, $xBTC, $xETH, $xLEND, or $limUSD), each tracking the overall performance of its underlying delta-neutral yield strategy. You can also select on which supported chain you want to receive the token. 2. Deposit stablecoin & mint: Enter the amount of stablecoins you want to deposit and from which supported chain. Once confirmed, your funds are added to the pooled strategy and you immediately receive your tokens. 3. Holding and using your tokens: You’re now holding yield-bearing tokens. Your position is automatically earning yield as the token’s value grows over time. From here, you can put your tokens to work across DeFi: use them as collateral, provide liquidity, or build new strategies on top. ### 2. How to redeem xTokens & limUSD (Withdrawal) Exiting a position means redeeming your tokens for stablecoins, including both your initial deposit and accrued yield. There are two modes of redemption: #### Instant Redemption, Omnichain This option allows you to redeem your tokens from any supported chain for stablecoins immediately at the current price-per-share, as long as sufficient liquidity is available in the redemption buffer. A fixed instant redemption fee always applies, designed to protect the pool against sandwich attacks and fast-unwind risks:
Token(s)Instant Redemption Fee
xHYPE, xBTC, xETH, limUSD0.3%
xLEND0.01%
These fees are redistributed back to token holders, effectively boosting their overall yield. #### Standard Redemption (Queued withdrawal), HyperEVM only This method lets you submit a redemption request, after which the strategy gradually unwinds positions to return your stablecoins. Processing times vary by token:
Token(s)Processing TimeReason
xHYPE, xBTCUp to 3 daysPositions close safely over multiple funding cycles
xLENDUp to 24 hoursLending positions can be unwound faster
limUSDUp to 3 daysPortfolio-level unwind across multiple underlying strategies
Standard redemptions are particularly useful when a large withdrawal exceeds the available instant redemption liquidity buffer, ensuring users are never blocked from exiting their position. Requested withdrawals also ensure fairness, preventing a single large exit from negatively impacting remaining holders. In the event of a withdrawal representing a significant share of the vault’s total value, processing times may be extended beyond the standard window to ensure the strategy unwinds safely and minimizes impact on remaining vault participants. ### 3. Bridging xTokens & limUSD (Cross-Chain Transfer) 1. Choose your token: Select the token you want to bridge (e.g., xHYPE, xBTC, xLEND, limUSD). 2. Select the source chain and destination chain: Pick any supported chain. Because xTokens and limUSD are OFTs, they can freely move between all enabled networks. 3. Enter the amount to bridge: You can bridge any amount, including your full balance. 4. Receive your tokens: Once the LayerZero message is delivered, your tokens appear on the destination chain. Your share count and accumulated yield remain exactly the same. # Composability and DeFi Liminal’s Tokenized products are not just yield-bearing assets, their real strength lies in being composable building blocks for DeFi. Both xTokens and limUSD represent tokenized, delta-neutral yield strategies that continuously accrue in price. But unlike traditional yield products, they remain fully liquid and usable across DeFi, enabling holders to unlock additional layers of utility and capital efficiency. By putting xTokens or limUSD to work in DeFi, holders can earn additional yield and utilities on top of the native yield they receive from the underlying strategy. ### Core DeFi Use Cases #### Liquidity Provision xTokens and limUSD can be paired with stablecoins on AMMs such as Project X. By providing liquidity, holders: * Earn trading fees on top of the native yield * Help deepen liquidity for Liminal’s Tokenized products * Improve market efficiency and reduce slippage for other users This allows Tokenized products to function as yield-bearing liquidity primitives within the Hyperliquid ecosystem. #### Lending & Borrowing xTokens and limUSD can be supplied as productive collateral on money market protocols such as HyperLend. By supplying them, users can: * Use their tokens as collateral * Borrow stablecoins against their position * Reuse the borrowed capital to mint additional xTokens or limUSD This enables users to increase exposure to yield-bearing positions while maintaining their existing holdings. In practice, tokens continue to accrue their native yield while the same capital is reused across DeFi to improve capital efficiency, without relying on additional lending yield.
#### Yield Derivatives xTokens and limUSD are integrated into yield-derivatives protocols such as Pendle or Spectra. This unlocks advanced strategies, including: * Secure fixed rates with Principal Tokens (PTs) * Speculate on yield via Yield Tokens (YTs) * Sophisticated yield management without touching the underlying strategy These tools allow users to tailor their risk and return profile around Liminal’s delta-neutral yields, whether from a single xToken or from limUSD’s diversified portfolio. ### In Summary Liminal’s Tokenized products transform Hyperliquid’s native yield into productive, liquid, and composable DeFi assets. They can be: * Held passively to earn from their native structural yield * Actively deployed across DeFi for additional returns * Used as building blocks for advanced capital-efficient strategies By combining native yield with DeFi composability, xTokens and limUSD unlock new dimensions of utility and efficiency for on-chain capital. # Cross-chain ### 1. Architecture Overview #### Hub-and-Spoke Model xTokens are omnichain OFTs that use a hub-and-spoke architecture powered by LayerZero V2: ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Arbitrum │ │ HyperEVM │ │ Ethereum │ │ (Spoke) │◄───────►│ (Hub) │◄───────►│ (Spoke) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` **HyperEVM (Hub)** **Where the strategy lives:** * Logic and asset management * NAV tracking and share price calculation * Liquidity management for instant redemptions * Share minting and burning **Spoke Chains (Arbitrum, Ethereum..)** **Where users interact:** * OFT (Omnichain Fungible Token) contracts for assets and shares * Cross-chain message composition * Local balance tracking via LayerZero ### **2. Cross-Chain Flow** #### 1. Deposit Flow **Example: Deposit from Arbitrum (Spoke) → HyperEVM (Hub) → Ethereum (Spoke)** 1. User deposits USDT0 on Arbitrum 2. USDT0 OFT sends tokens to Hub (HyperEVM) via LayerZero 3. Composer receives compose message on Hub 4. DepositPipe accepts USDT0, mints shares to user 5. LayerZero Composer sends shares to Ethereum 6. User receives xTokens on Ethereum **Example: Deposit from Arbitrum (Spoke) → HyperEVM (Hub)** 1. User deposits USDT0 on Arbitrum 2. USDT0 OFT sends tokens to HyperEVM (hub) via LayerZero 3. LayerZero Composer receives the compose message on HyperEVM 4. DepositPipe accepts the USDT0 and mints shares 5. User receives xTokens on HyperEVM **Example: Deposit from HyperEVM (Hub) → Ethereum (Spoke)** 1. User deposits USDT0 directly on HyperEVM 2. DepositPipe mints shares immediately 3. LayerZero Composer sends the minted shares to Ethereum 4. User receives xTokens on Ethereum #### 2. Redemption Flow LayerZero composer only handle synchronous operations, therefore making it only possible to perform instant redemption using the cross-chain infrastructure. If the user wants a standard redemption he needs to bridge his shares on HyperEVM. **Example: Redeem from Ethereum (Spoke) → HyperEVM (Hub)** 1. User sends xToken shares from Ethereum via LayerZero 2. Shares arrive on HyperEVM (hub) 3. Redemption is performed, shares are burned and USDT0 released to the user on HyperEVM **Example: Redeem from HyperEVM (Hub) → Ethereum (Spoke)** 1. User perform the redemption on HyperEVM to redeem shares 2. Shares are burned and USDT0 is released 3. LayerZero sends the USDT0 to Ethereum 4. User receives USDT0 on Ethereum **Example: Redeem from Arbitrum (Spoke) → HyperEVM (Hub) → Ethereum (Spoke)** 1. User sends shares from Arbitrum using LayerZero 2. Shares arrive on HyperEVM (hub) 3. Redemption is performed, burns the shares and releases USDT0 4. USDT0 are sent to Ethereum using LayerZero 5. User receives USDT0 on Ethereum #### 3. Bridge flow xTokens are omnichain OFTs, meaning bridging simply moves your xToken shares from one chain to another without interacting with the underlying strategy. No minting, burning, or position changes occur during a bridge. Only the chain location of your shares changes. **Example: Bridge from Arbitrum → HyperEVM** 1. User initiates a bridge of xToken shares on Arbitrum 2. LayerZero sends the shares to HyperEVM 3. Shares arrive on HyperEVM and are credited to the user 4. No redemption, no minting, only a chain transfer 5. User now holds the same xToken shares on HyperEVM *** # Developers ### Architecture Overview #### Hub-and-Spoke Model xTokens are omnichain OFTs that use a hub-and-spoke architecture powered by LayerZero V2: ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Arbitrum │ │ HyperEVM │ │ Base │ │ (Spoke) │◄───────►│ (Hub) │◄───────►│ (Spoke) │ └─────────────┘ └─────────────┘ └─────────────┘ User xTokens Logic User Interaction Asset Management Interaction Share Minting ``` ### Key Concepts #### Share Tokens Share tokens represent proportional ownership in the vault: * **Decimals**: Always 18 decimals across all chains * **Ticker**: Specific to each xToken (e.g., xHYPE, xBTC) * **Cross-Chain**: Can be transferred between any supported chain via LayerZero * **Yield-Bearing**: Share value increases as vault assets grow (tracked via NAV) The "Hub Share" are managed by the `ShareManager` contract while the cross-chain "Spoke Share" are managed by ShareOFT. This ensure the `ShareManager` on the hub (HyperEVM) always hold the total supply of shares available on all supported chain. The ShareManager (Hub Share) is wrapped by an OFTAdapter for cross-chain capacity and linking with the Spoke Share. #### Deposit Deposits are done through the `DepositPipe` contracts, there is 1 DepositPipe per asset per xToken. | Asset | Decimals | Example Amount | | ----- | -------- | ----------------- | | USDT0 | 6 | 1000000 = 1 USDT0 | | USDC | 6 | 1000000 = 1 USDC | | USDH | 6 | 1000000 = 1 USDH | **Note**: Each XToken may support different assets. Check the specific XToken documentation for supported assets. #### Redemption Asset Redemptions are done through the `RedemptionPipe` contract, there is only 1 RedemptionPipe per xToken. As of now, shares can only be redeemed for USDT0. #### OFT (Omnichain Fungible Tokens) LayerZero V2 OFT enables cross-chain token transfers: * **AssetOFT**: Wraps deposit assets (USDC, USDT0, etc.) for cross-chain transfers * **ShareOFT**: Wraps vault shares for cross-chain transfers * **OFTAdapter**: For tokens with existing supply (e.g., on the hub chain) * **Compose Messages**: Trigger vault operations (deposits/redemptions) on message receipt #### Oracle NAV determines the share price: ``` Share Price = Total NAV / Total Share Supply Share Price = NAVOracle.getNAV() / ShareManager.totalSupply() ``` * **18 Decimals**: NAV is always tracked in 18 decimals internally * **On-Chain Oracle**: Real-time NAV available via `NAVOracle.getNAV()` * **Dynamic**: Updates with deposits, redemptions, and vault performance A **Pyth** price feed is also available for each xTokens. # Interfaces This section provides an overview of the core interfaces used in the vault system. Each interface defines the standard methods for interacting with key components of the architecture. ### Core Interfaces #### `DepositPipe` Interface for deposit operations. Each DepositPipe handles deposits for a specific asset type and implements ERC4626 compatibility. **Use Cases:** * User deposits from same chain (hub) * Cross-chain deposits via LayerZero * Integration with DeFi protocols *** #### `RedemptionPipe` Interface for redemption operations. Handles instant and standard redemptions with liquidity management. **Use Cases:** * User redemptions on hub chain * Cross-chain redemptions * Liquidity provider integrations *** #### `ShareManager` Interface for managing vault shares. Tracks total supply on all chains and enforces limits on deposits, supply, and withdrawals. **Use Cases:** * Share minting/burning operations * Limit enforcement * Cross-chain share transfers * Security controls *** #### `NAVOracle` Interface for Net Asset Value (NAV) management. Tracks the total value of assets in the vault and provides controlled mechanisms for updating it. **Use Cases:** * NAV tracking for share pricing * Deposit/redemption NAV updates * External valuation integrations *** ### Standard Interfaces The system also implements standard ERC interfaces: * **ERC20**: ShareManager implements standard ERC20 for share tokens * **OFT:** xTokens Share implements the LayerZero OFT standard * **ERC4626**: DepositPipe and RedemptionPipe implements ERC4626 and ERC7545 vault standard *** ### Decimal Handling * **Shares**: Always 18 decimals * **NAV**: Always 18 decimals (normalized internally) * **Deposit Assets**: Native decimals (USDC = 6, USDT = 6, USDe = 18) # Deposit Pipe The DepositPipe handles deposits and implements ERC4626 compatibility. Each DepositPipe handles a specific asset, meaning that for a given xToken there can be multiple DepositPipe (1 per accepted deposit asset). **Key Functions** **`deposit(uint256 assets, address receiver, address controller, uint256 minShares)`** Deposit assets and receive shares with slippage protection. ```solidity /** * @param assets Amount of deposit asset (in asset's native decimals) * @param receiver Address to receive minted shares * @param controller Address that owns the assets being deposited * @param minShares Minimum shares to receive (slippage protection, 18 decimals) * @return shares Amount of shares minted (18 decimals) */ function deposit( uint256 assets, address receiver, address controller, uint256 minShares ) external returns (uint256 shares); ``` **Overloads:** * `deposit(uint256 assets, address receiver)` - Uses `msg.sender` as controller, no slippage protection * `deposit(uint256 assets, address receiver, address controller)` - No slippage protection * `deposit(uint256 assets, address receiver, uint256 minShares)` - Uses `msg.sender` as controller *** **`mint(uint256 shares, address receiver, address controller, uint256 maxAssets)`** Mint specific amount of shares by depositing assets. ```solidity /** * @param shares Exact amount of shares to mint (18 decimals) * @param receiver Address to receive shares * @param controller Address that owns the assets * @param maxAssets Maximum assets willing to spend (slippage protection, native decimals) * @return assets Amount of assets deposited (native decimals) */ function mint( uint256 shares, address receiver, address controller, uint256 maxAssets ) external returns (uint256 assets); ``` **Overloads:** * `mint(uint256 shares, address receiver)` - Uses `msg.sender`, no slippage limit * `mint(uint256 shares, address receiver, address controller)` - No slippage limit * `mint(uint256 shares, address receiver, uint256 maxAssets)` - Uses `msg.sender` *** **Preview Functions** ```solidity // Preview how many shares you'll receive for assets function previewDeposit(uint256 assets) external view returns (uint256 shares); // Preview how many assets required for shares function previewMint(uint256 shares) external view returns (uint256 assets); // Convert between assets and shares function convertToShares(uint256 assets) external view returns (uint256); function convertToAssets(uint256 shares) external view returns (uint256); ``` *** **View Functions** ```solidity // Get the deposit asset address function asset() external view returns (address); ``` # Redemption Pipe The RedemptionPipe handle the whole redemption process and implement ERC4626 compatibility., It supports two redemption types with different speed/fee tradeoffs. There is only one RedemptionPipe per xToken, meaning that only a single asset can be redeemed. ### **Redemption Types** | Type | Speed | Fee | Settlement | Use Case | | ------------ | --------- | ---- | ------------------ | -------------------------- | | **Instant** | Immediate | 0.3% | On-chain liquidity | Time-sensitive redemptions | | **Standard** | 1-3 days | 0 | Request/fulfill | Large redemptions, no rush | **Instant Redemption** **`redeem(uint256 shares, address receiver, address controller)`** Instantly redeem shares for assets using liquidity provider. ```solidity /** * @param shares Amount of shares to redeem (18 decimals) * @param receiver Address to receive assets * @param controller Address that owns the shares * @return assets Amount of assets received (underlying decimals, after fees) */ function redeem( uint256 shares, address receiver, address controller ) external returns (uint256 assets); ``` **`withdraw(uint256 assets, address receiver, address controller)`** Instantly withdraw specific asset amount by burning shares. ```solidity /** * @param assets Amount of assets to withdraw (underlying decimals) * @param receiver Address to receive assets * @param controller Address that owns shares * @return shares Amount of shares burned (18 decimals) */ function withdraw( uint256 assets, address receiver, address controller ) external returns (uint256 shares); ``` **Standard Redemption** Two-step process: request, then fulfill (no fee). **`requestRedeem(uint256 shares, address controller, address owner)`** Submit a standard redemption request. ```solidity /** * @param shares Amount of shares to redeem (18 decimals) * @param controller Address that will control the redemption * @param owner Address that owns shares * @return requestId Always returns 0 */ function requestRedeem( uint256 shares, address controller, address owner ) external returns (uint256 requestId); ``` **Check Pending Request** ```solidity /** * @param owner Owner address * @return shares Amount of pending shares */ function pendingRedeemRequest(address owner) external view returns (uint256 shares); ``` **Preview Functions** ```solidity // Convert shares to underlying assets function convertToAssets(uint256 shares) external view returns (uint256); // Convert assets to shares function convertToShares(uint256 assets) external view returns (uint256); // Preview withdraw - calculates required shares for net asset amount function previewWithdraw(uint256 assets) public view returns (uint256) // Preview redeem - converts shares to underlying assets after fees function previewRedeem(uint256 shares) public view returns (uint256) ``` **Fee Information** ```solidity // Get fee basis points (10000 = 100%) function instantRedeemFeeBps() external view returns (uint256); ``` # Oracle & ShareManager ### NAV Oracle The NAVOracle tracks the total value of assets in the vault. It normalizes all values to 18 decimals internally, regardless of the underlying asset's decimals. The contract enforces percentage-based limits on NAV changes to prevent large swings and potential manipulation. **`getNAV()`** Get the current Net Asset Value. ```solidity /** * @return Current NAV in 18 decimals */ function getNAV() external view returns (uint256); ``` ### Share Manager The ShareManager maintains the total supply of vault shares and provides controlled mechanisms for minting and burning them. There is only one ShareManager per xToken and it exists only on the hub chain (HyperEVM). `maxSupply()` Get the maximum total supply of shares across all users. ```solidity /** * @return Maximum total supply of shares (18 decimals) * @dev Enforced in DepositPipe when minting shares * @dev Controls overall vault growth and prevents unlimited expansion */ function maxSupply() external view returns (uint256); ``` `maxWithdraw()` Get the maximum shares that can be redeemed per user per transaction. ```solidity /** * @return Maximum shares per redemption transaction (18 decimals) * @dev Enforced in RedemptionPipe for instant and pending redemptions * @dev Limits redemption size to prevent large withdrawals */ function maxWithdraw() external view returns (uint256); ``` `maxDeposit()` Get the maximum shares that can be deposited per user per transaction. ```solidity /** * @return Maximum shares per deposit transaction (18 decimals) * @dev Enforced in DepositPipe for deposit and mint */ function maxDeposit() external view returns (uint256); ``` `totalSupply()` Get the current total supply of shares (include shares on spoke chains). ```solidity /** * @return Current total supply of shares (18 decimals) * @dev Standard ERC20 function * @dev Represents total shares minted across all users */ function totalSupply() external view returns (uint256); ``` ### Price per share The price per share of a xToken can be determined using the following formula: ``` Share Price = Total NAV / Total Share Supply Share Price = NAVOracle.getNAV() / ShareManager.totalSupply() ``` ### Price Feed For each xToken, a **Pyth Price Feed** is available for integrations in money markets and other DeFi protocols. To obtain the Pyth price feed ID for a specific xToken, please refer to the xTokens specifications documentation. # Common Patterns The SendParam in the following pattern are based on LayerZero patterns extensions: https\://docs.layerzero.network/v2/developers/evm/oft/oft-patterns-extensions ### Integration Patterns #### Pattern 1: Same-Chain Deposit (Hub Only) Fastest and cheapest—no LayerZero fees. ```solidity // Direct deposit on hub chain uint256 usdtAmount = 1000 * 1e6; uint256 minShares = 990 * 1e18; IERC20(usdt).approve(depositPipe, usdtAmount); uint256 shares = IDepositPipe(depositPipe).deposit( usdtAmount, msg.sender, msg.sender, minShares ); // Shares minted instantly ``` **Note:** The `deposit` function signatures are: * `deposit(uint256 assets, address receiver)` - ERC4626 standard * `deposit(uint256 assets, address receiver, address controller)` - With controller * `deposit(uint256 assets, address receiver, uint256 minShares)` - With slippage protection * `deposit(uint256 assets, address receiver, address controller, uint256 minShares)` - Full control The `mint` function signatures are: * `mint(uint256 shares, address receiver)` - ERC4626 standard * `mint(uint256 shares, address receiver, address controller)` - With controller * `mint(uint256 shares, address receiver, uint256 maxAssets)` - With slippage protection * `mint(uint256 shares, address receiver, address controller, uint256 maxAssets)` - Full control #### Pattern 2: Cross-Chain Deposit (Spoke → Hub) Deposit from any spoke, receive shares on hub. ```solidity // On Arbitrum (spoke), send USDT0 to hub for shares uint256 usdtAmount = 1000 * 1e6; uint32 hubEid = 30167; // HyperEVM (example) // Build compose message for deposit // ACTION_DEPOSIT_ASSET params: (address targetAsset, bytes32 receiver, SendParam, uint256 minMsgValue, bytes32 feeRefundRecipient, uint32 originEid) bytes memory composeMsg = abi.encode( uint8(1), // ACTION_DEPOSIT_ASSET abi.encode( usdtAddressOnHub, // targetAsset addressToBytes32(msg.sender), // receiver (shares recipient if same chain) SendParam({ dstEid: 0, // 0 = same chain, non-zero = cross-chain to: addressToBytes32(msg.sender), // Share recipient if cross-chain amountLD: 0, // Will be set by composer minAmountLD: 990 * 1e18, // Min shares (slippage protection) extraOptions: "", composeMsg: "", oftCmd: "" }), uint256(0), // minMsgValue (native fee for compose) addressToBytes32(msg.sender), // feeRefundRecipient uint32(0) // originEid (source chain for multi-hop refunds) ) ); SendParam memory sendParam = SendParam({ dstEid: hubEid, to: addressToBytes32(composer), amountLD: usdtAmount, minAmountLD: usdtAmount, extraOptions: OptionsBuilder.newOptions().addExecutorLzComposeOption(0, 700_000, 0), composeMsg: composeMsg, oftCmd: "" }); MessagingFee memory fee = IOFT(usdtOFT).quoteSend(sendParam, false); IERC20(usdt).approve(usdtOFT, usdtAmount); IOFT(usdtOFT).send{value: fee.nativeFee}(sendParam, fee, msg.sender); // Shares received on hub in ~1-3 minutes ``` #### Pattern 3: Cross-Chain Deposit (Spoke → Hub → Different Spoke) Deposit on one spoke, receive shares on another spoke. ```solidity // Deposit USDT on Arbitrum, receive shares on Ethereum uint256 usdtAmount = 1000 * 1e6; uint32 hubEid = 30167; // HyperEVM uint32 ethereumEid = 30101; // Ethereum // Build compose message with cross-chain share distribution bytes memory composeMsg = abi.encode( uint8(1), // ACTION_DEPOSIT_ASSET abi.encode( usdtAddressOnHub, addressToBytes32(address(msg.sender)), SendParam({ dstEid: ethereumEid, // Send shares to Ethereum to: addressToBytes32(msg.sender), // Share recipient on Ethereum amountLD: 0, minAmountLD: 990 * 1e18, extraOptions: OptionsBuilder.newOptions().addExecutorLzReceiveOption(200_000, 0), composeMsg: "", oftCmd: "" }), uint256(0), // minMsgValue for compose addressToBytes32(msg.sender), // feeRefundRecipient getSourceEid() // originEid (Arbitrum) ) ); SendParam memory sendParam = SendParam({ dstEid: hubEid, to: addressToBytes32(composer), amountLD: usdtAmount, minAmountLD: usdtAmount, extraOptions: OptionsBuilder.newOptions().addExecutorLzComposeOption(0, 700_000, 0), composeMsg: composeMsg, oftCmd: "" }); MessagingFee memory fee = IOFT(usdtOFT).quoteSend(sendParam, false); IERC20(usdt).approve(usdtOFT, usdtAmount); IOFT(usdtOFT).send{value: fee.nativeFee}(sendParam, fee, msg.sender); // Shares received on Ethereum in ~1-3 minutes ``` #### Pattern 4: Same-Chain Instant Redemption Fastest redemption with highest fee. ```solidity // Redeem shares for USDT on hub uint256 shares = 1000 * 1e18; IShareManager(shareManager).approve(redemptionPipe, shares); uint256 usdtReceived = IRedemptionPipe(redemptionPipe).redeem( shares, msg.sender, msg.sender ); // USDT received instantly (after fee) ``` **Alternative: Withdraw specific asset amount** ```solidity // Withdraw specific amount of assets (net, after fees) uint256 desiredAssets = 1000 * 1e6; // Want 1000 USDT net IShareManager(shareManager).approve(redemptionPipe, type(uint256).max); uint256 sharesBurned = IRedemptionPipe(redemptionPipe).withdraw( desiredAssets, msg.sender, msg.sender ); // Shares burned, assets received (after fee) ``` **Note:** * Instant redemption (`redeem`) applies a fee (`instantRedeemFeeBps`) which is deducted from the assets received. The fee stays with the liquidity provider. * `withdraw` calculates the required shares based on the net asset amount (after fees), while `redeem` burns a specific number of shares. #### Pattern 5: Cross-Chain Redemption (Spoke → Hub → Spoke) Redeem shares on spoke for assets on hub or different spoke. ```solidity // On Ethereum, redeem shares for USDT on hub uint256 shares = 1000 * 1e18; uint32 hubEid = 30167; // HyperEVM // Build compose message for redemption // ACTION_REDEEM_SHARES params: (address receiver, SendParam, uint256 minMsgValue, uint256 minAssets, bytes32 feeRefundRecipient, uint32 originEid) bytes memory composeMsg = abi.encode( uint8(2), // ACTION_REDEEM_SHARES abi.encode( msg.sender, // receiver (USDT recipient if same chain) SendParam({ dstEid: 0, // 0 = same chain, non-zero = cross-chain to: addressToBytes32(msg.sender), // Asset recipient if cross-chain amountLD: 0, // Will be set by composer minAmountLD: 990 * 1e6, // Min USDT (slippage protection) extraOptions: "", composeMsg: "", oftCmd: "" }), uint256(0), // minMsgValue (native fee for compose) 990 * 1e6, // minAssets (slippage protection) addressToBytes32(msg.sender), // feeRefundRecipient getSourceEid() // originEid (Ethereum ) ) ); SendParam memory sendParam = SendParam({ dstEid: hubEid, to: addressToBytes32(composer), amountLD: shares, minAmountLD: shares, extraOptions: OptionsBuilder.newOptions().addExecutorLzComposeOption(0, 700_000, 0), composeMsg: composeMsg, oftCmd: "" }); MessagingFee memory fee = IOFT(shareOFT).quoteSend(sendParam, false); IShareManager(shareERC20).approve(shareOFT, shares); IOFT(shareOFT).send{value: fee.nativeFee}(sendParam, fee, msg.sender); // USDT received on hub in ~1-3 minutes ``` #### Pattern 6: Transfer Shares Between Spokes Simple cross-chain share transfer (no vault operation). ```solidity // Transfer shares from Arbitrum to Ethereum (no deposit/redeem) uint256 shares = 1000 * 1e18; uint32 ethereumEid = 30101; SendParam memory sendParam = SendParam({ dstEid: ethereumEid, to: addressToBytes32(msg.sender), amountLD: shares, minAmountLD: shares, extraOptions: OptionsBuilder.newOptions().addExecutorLzReceiveOption(200_000, 0), composeMsg: "", // No compose message oftCmd: "" }); MessagingFee memory fee = IOFT(shareOFT).quoteSend(sendParam, false); IShareManager(shareERC20).approve(shareOFT, shares); IOFT(shareOFT).send{value: fee.nativeFee}(sendParam, fee, msg.sender); // Shares arrive on Ethereum in ~1-3 minutes ``` #### Pattern 7: Direct Composer Methods (Hub Only) For same-chain operations on the hub, you can use direct composer methods: ```solidity // Deposit and send shares cross-chain in one call uint256 usdtAmount = 1000 * 1e6; uint32 ethereumEid = 30101; SendParam memory shareSendParam = SendParam({ dstEid: ethereumEid, to: addressToBytes32(msg.sender), amountLD: 0, // Will be set by composer minAmountLD: 990 * 1e18, extraOptions: OptionsBuilder.newOptions().addExecutorLzReceiveOption(200_000, 0), composeMsg: "", oftCmd: "" }); IERC20(usdt).approve(composer, usdtAmount); MessagingFee memory fee = IOFT(shareOFT).quoteSend(shareSendParam, false); IOVaultComposerMulti(composer).depositAssetAndSend{value: fee.nativeFee}( usdt, usdtAmount, shareSendParam, msg.sender // refund address ); // Redeem and send assets cross-chain in one call uint256 shares = 1000 * 1e18; SendParam memory assetSendParam = SendParam({ dstEid: ethereumEid, to: addressToBytes32(msg.sender), amountLD: 0, // Will be set by composer minAmountLD: 990 * 1e6, extraOptions: OptionsBuilder.newOptions().addExecutorLzReceiveOption(200_000, 0), composeMsg: "", oftCmd: "" }); IShareManager(shareERC20).approve(composer, shares); MessagingFee memory fee = IOFT(underlyingAssetOFT).quoteSend(assetSendParam, false); IOVaultComposerMulti(composer).redeemAndSend{value: fee.nativeFee}( shares, assetSendParam, msg.sender // refund address ); ``` #### Pattern 8: Standard Redemption Request (Hub Only) Standard redemption requests are fulfilled later by the protocol. ```solidity // Request standard redemption uint256 shares = 1000 * 1e18; // Transfer shares to redemption pipe (they will be held in custody) IShareManager(shareManager).transfer(redemptionPipe, shares); uint256 requestId = IRedemptionPipe(redemptionPipe).requestRedeem( shares, msg.sender, // receiver msg.sender, // controller msg.sender // owner ); // Later, a FULFILL_MANAGER_ROLE will fulfill the request // Users receive assets after fulfillment (no fees) ``` ### Developer Guide #### 1. Reading NAV and Share Prices ```solidity // Get current NAV (18 decimals) uint256 nav = INAVOracle(navOracle).getNAV(); // Get total share supply (18 decimals) uint256 supply = IShareManager(shareManager).totalSupply(); // Calculate share price (18 decimals) uint256 sharePrice = (nav * 1e18) / supply; // Calculate user's USD value uint256 userShares = IShareManager(shareManager).balanceOf(user); uint256 userValue = (userShares * nav) / supply; ``` #### 2. Handling Different Asset Decimals All internal calculations use 18 decimals, but deposit assets may vary. ```solidity // Normalize asset amount to 18 decimals function normalizeToDecimals18(uint256 amount, uint8 decimals) internal pure returns (uint256) { if (decimals == 18) return amount; if (decimals < 18) { return amount * (10 ** (18 - decimals)); } else { return amount / (10 ** (decimals - 18)); } } // Denormalize from 18 decimals to asset decimals function normalizeFromDecimals18(uint256 amount18, uint8 decimals) internal pure returns (uint256) { if (decimals == 18) return amount18; if (decimals < 18) { return amount18 / (10 ** (18 - decimals)); } else { return amount18 * (10 ** (decimals - 18)); } } ``` **Example:** ```solidity // User wants to deposit $1000 worth of USDT (6 decimals) uint256 usdtAmount = 1000 * 1e6; // 1000 USDT // Preview shares (returns 18 decimals) uint256 expectedShares = IDepositPipe(depositPipe).previewDeposit(usdtAmount); // expectedShares might be 1000 * 1e18 (if 1:1 ratio) // User wants 1000 shares (18 decimals) uint256 desiredShares = 1000 * 1e18; // Preview required USDT (returns 6 decimals) uint256 requiredUSDT = IDepositPipe(depositPipe).previewMint(desiredShares); // requiredUSDT might be 1000 * 1e6 ``` #### 3. Slippage Protection Best Practices Always use slippage protection for better UX. ```solidity // For deposits: calculate minimum shares uint256 depositAmount = 1000 * 1e6; // USDT uint256 expectedShares = IDepositPipe(depositPipe).previewDeposit(depositAmount); uint256 minShares = (expectedShares * 99) / 100; // 1% slippage IDepositPipe(depositPipe).deposit(depositAmount, receiver, controller, minShares); // For mints: calculate maximum assets uint256 desiredShares = 1000 * 1e18; uint256 expectedAssets = IDepositPipe(depositPipe).previewMint(desiredShares); uint256 maxAssets = (expectedAssets * 101) / 100; // 1% slippage // Note: Use mint(shares, receiver, maxAssets) or mint(shares, receiver, controller, maxAssets) IDepositPipe(depositPipe).mint(desiredShares, receiver, maxAssets); // For redemptions: calculate minimum assets uint256 sharesToRedeem = 1000 * 1e18; uint256 expectedAssets = IRedemptionPipe(redemptionPipe).previewRedeem(sharesToRedeem); uint256 minAssets = (expectedAssets * 99) / 100; // 1% slippage // Note: For instant redemptions, slippage is implicit in fee // For cross-chain redemptions, include minAssets in compose message ``` #### 4. Gas Estimation for LayerZero Operations Always get fee quotes before cross-chain operations. ```solidity // Quote fee for cross-chain send SendParam memory sendParam = /* ... */; MessagingFee memory fee = IOFT(oft).quoteSend(sendParam, false); // Total gas needed uint256 totalGas = fee.nativeFee; // For compose operations, add compose gas if (sendParam.composeMsg.length > 0) { totalGas += estimateComposeGas(); // 0.01-0.05 ETH typical } // Execute with proper value IOFT(oft).send{value: totalGas}(sendParam, fee, refundAddress); ``` #### 5. Error Handling Common errors and how to handle them: ```solidity // DepositPipe errors try IDepositPipe(depositPipe).deposit(amount, receiver, controller, minShares) returns (uint256 shares) { // Success } catch Error(string memory reason) { if (keccak256(bytes(reason)) == keccak256("DepositPipe: slippage exceeded")) { // Handle slippage - increase minShares or retry } if (keccak256(bytes(reason)) == keccak256("DepositPipe: shares below minimum")) { // Amount too small - increase deposit } if (keccak256(bytes(reason)) == keccak256("ShareManager: max deposit exceeded")) { // User or global deposit limit exceeded } if (keccak256(bytes(reason)) == keccak256("DepositPipe: max supply exceeded")) { // Global supply limit exceeded } } // RedemptionPipe errors try IRedemptionPipe(redemptionPipe).redeem(shares, receiver, controller) returns (uint256 assets) { // Success } catch Error(string memory reason) { if (keccak256(bytes(reason)) == keccak256("RedemptionPipe: insufficient liquidity")) { // Instant redemption unavailable - use fast/standard } if (keccak256(bytes(reason)) == keccak256("RedemptionPipe: insufficient shares")) { // User doesn't have enough shares } if (keccak256(bytes(reason)) == keccak256("RedemptionPipe: shares below minimum")) { // Amount too small } if (keccak256(bytes(reason)) == keccak256("RedemptionPipe: maximum redeem per user exceeded")) { // User redemption limit exceeded } } // LayerZero errors try IOFT(oft).send{value: fee.nativeFee}(sendParam, fee, refund) returns (MessagingReceipt memory receipt) { // Success - track receipt.guid on LayerZero scanner } catch { // Insufficient gas, invalid parameters, or OFT paused } ``` #### 6. Monitoring Cross-Chain Transactions Track LayerZero messages using the GUID. ```solidity // After sending cross-chain MessagingReceipt memory receipt = IOFT(oft).send{value: fee}(sendParam, fee, refund); bytes32 guid = receipt.guid; // Emit event for frontend tracking emit CrossChainOperationInitiated(guid, sendParam.dstEid, user); // Users can track on: https://layerzeroscan.com/tx/{guid} ``` **Frontend Integration:** ```javascript // Listen for LayerZero events const receipt = await oft.send(sendParam, fee, refund, {value: totalGas}); const guid = receipt.guid; // Poll LayerZero scanner API const checkStatus = async (guid) => { const response = await fetch(`https://api.layerzeroscan.com/tx/${guid}`); const data = await response.json(); return data.status; // "INFLIGHT", "DELIVERED", "FAILED" }; ``` #### 7. Important Limits and Constraints ```solidity // Check minimum share amounts uint256 minShares = IDepositPipe(depositPipe).MIN_AMOUNT_SHARES(); uint256 minRedeemShares = IRedemptionPipe(redemptionPipe).MIN_AMOUNT_SHARES(); // Check deposit limits uint256 maxDeposit = IShareManager(shareManager).maxDeposit(); uint256 maxSupply = IShareManager(shareManager).maxSupply(); uint256 userBalance = IShareManager(shareManager).balanceOf(user); uint256 remainingCapacity = maxDeposit > userBalance ? maxDeposit - userBalance : 0; // Check redemption limits uint256 maxWithdraw = IShareManager(shareManager).maxWithdraw(); uint256 userBalance = IShareManager(shareManager).balanceOf(user); uint256 maxRedeem = IRedemptionPipe(redemptionPipe).maxRedeem(user); uint256 maxWithdrawAssets = IRedemptionPipe(redemptionPipe).maxWithdraw(user); ``` #### 8. Fee Information ```solidity // Get redemption fees (uint256 instantFeeBps, _) = IRedemptionPipe(redemptionPipe).fees(); // Fees are in basis points (10000 = 100%) // Calculate instant redemption fee uint256 shares = 1000 * 1e18; uint256 assets = IRedemptionPipe(redemptionPipe).convertToAssets(shares); uint256 fee = (assets * instantFeeBps) / 10000; uint256 assetsAfterFee = assets - fee; ``` #### 9. Operator Pattern The ShareManager supports an operator pattern for contract-based integrations: ```solidity // User sets operator IShareManager(shareManager).setOperator(operatorContract, true); // Operator can now act on behalf of user ``` #### 10. Blacklist Handling Users can be blacklisted, preventing deposits, redemptions, and transfers: ```solidity // Check if user is blacklisted bool isBlacklisted = IShareManager(shareManager).isBlacklisted(user); // If blacklisted, operations will revert with: // "ShareManager: receiver address is blacklisted" // "ShareManager: sender address is blacklisted" ``` #### 11. Pause Handling All contracts support emergency pause: ```solidity // Check if contract is paused bool isPaused = Pausable(depositPipe).paused(); // If paused, operations will revert with: // "Pausable: paused" ``` #### 12. Composer Message Structure Reference **ACTION\_DEPOSIT\_ASSET (1):** ```solidity abi.encode( address targetAsset, // Asset to deposit on hub bytes32 receiver, // Share recipient if same chain (bytes32(0) if cross-chain) SendParam shareSendParam, // Share distribution (dstEid=0 for same chain) uint256 minMsgValue, // Minimum native fee for compose operation bytes32 feeRefundRecipient, // Fee refund recipient (bytes32(0) = depositor) uint32 originEid // Source chain for multi-hop refunds ) ``` **ACTION\_REDEEM\_SHARES (2):** ```solidity abi.encode( address receiver, // Asset recipient if same chain SendParam assetSendParam, // Asset distribution (dstEid=0 for same chain) uint256 minMsgValue, // Minimum native fee for compose operation uint256 minAssets, // Minimum assets (slippage protection) bytes32 feeRefundRecipient, // Fee refund recipient (bytes32(0) = redeemer) uint32 originEid // Source chain for multi-hop refunds ) ``` #### 13. Helper Functions ```solidity // Convert address to bytes32 for LayerZero function addressToBytes32(address _addr) internal pure returns (bytes32) { return bytes32(uint256(uint160(_addr))); } // Convert bytes32 to address function bytes32ToAddress(bytes32 _b) internal pure returns (address) { return address(uint160(uint256(_b))); } ``` # limUSD #### 1. Network Configuration **Hub Chain** **HyperEVM (Mainnet)** * Chain ID: `999` * LayerZero Endpoint ID: `30367` * Role: Primary share logic, asset management, NAV tracking **Spoke Chains** | Chain | Chain ID | LZ Endpoint ID | Status | | -------- | -------- | -------------- | -------- | | Arbitrum | 42161 | 30110 | ✅ Active | | Ethereum | 1 | 30101 | ✅ Active | #### 2. Contract Addresses **HyperEVM (Hub Chain)** | Contract | Address | Description | | ----------------------- | -------------------------------------------- | --------------------------- | | **ShareManager** | `0x1822bd335489d84abdd0779a7dCAeDa0625e83c8` | limUSD share token | | **DepositPipe (USDC)** | `0xe56d115dD2107e1F7199c7AcCf68D68835A0fAa9` | USDC deposits | | **DepositPipe (USDT0)** | `0xbf9a411FD1832E716574f3796b05898d167533F5` | USDT0 deposits | | **RedemptionPipe** | `0x2E8c1256356e261150120a384d95DC0d0D00ae29` | All redemption types - USDC | | **OVaultComposerMulti** | `0x4c17aD5458EF8600229397baf61459eFE5C118e3` | Cross-chain operations | | **NAVOracle** | `0x47f8d4847f528C18Ea5A6dcb9E0940F6b2977CA7` | Net Asset Value tracking | | **PriceOracle** | `0xC415641F4207643126655197789Bd4C524B71d5D` | Asset price feeds | **Arbitrum** | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0x9B74D3BD96f54dE689CfFDeb27EE34f68dFf086d` | limUSD OFT | | **USDT0 OFT** | `0x14e4a1b13bf7f943c8ff7c51fb60fa964a298d92` | USDT0 OFT | **Ethereum** | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0x9B74D3BD96f54dE689CfFDeb27EE34f68dFf086d` | limUSD OFT | | **USDT0 OFT** | `0x6c96de32cea08842dcc4058c14d3aaad7fa41dee` | USDT0 OFT | #### 3. Supported Assets **Deposit Assets** limUSD accepts the following stablecoins for deposits: | Asset | Decimals | Chains Available | Notes | | --------- | -------- | ---------------- | --------------------------------------- | | **USDT0** | 6 | All chains | All spokes supported + HyperCore | | **USDT** | 6 | Hyperliquid | Ethereum + Hypercore | | **USDC** | 6 | All chains | All spokes supported (CCTP) + Hypercore | **Underlying Asset** **Primary Redemption Asset**: USDC * All redemptions are settled in USDC (6 decimals) * NAV is tracked in USDC equivalent (normalized to 18 decimals internally) #### 4. Oracle Feeds | Provider | Link | Notes | | -------- | -------------------------------------------------------------- | ----- | | Pyth | | ​ |
# xLEND ### 1. Network Configuration #### Hub Chain **HyperEVM (Mainnet)** * Chain ID: `999` * LayerZero Endpoint ID: `30367` * Role: Primary share logic, asset management, NAV tracking #### Spoke Chains | Chain | Chain ID | LZ Endpoint ID | Status | | -------- | -------- | -------------- | -------- | | Arbitrum | 42161 | 30110 | ✅ Active | | Ethereum | 1 | 30101 | ✅ Active | ### 2. Contract Addresses #### HyperEVM (Hub Chain) | Contract | Address | Description | | ----------------------- | -------------------------------------------- | --------------------------- | | **ShareManager** | `0x95f6d66c09A22e6F2bB693306b3ed69663066cbB` | xLEND share token | | **DepositPipe (USDC)** | `0x309CF12b14Decb39852eBa8869DCA5bdf9a5b754` | USDC deposits | | **DepositPipe (USDT0)** | `0x29EB53A9046d26CAEeE809679BC58403Cd99a12f` | USDT0 deposits | | **RedemptionPipe** | `0xCE12c415019657083a8B985e7cd5CD6fC486f978` | All redemption types - USDC | | **OVaultComposerMulti** | `0xD1d88bf7b841b23739562928Ea46EcD9c5Fc685E` | Cross-chain operations | | **NAVOracle** | `0xdbB4da0f1548F6237DF6960532563804A901C2AE` | Net Asset Value tracking | | **PriceOracle** | `0xC415641F4207643126655197789Bd4C524B71d5D` | Asset price feeds | #### Arbitrum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0xD68700e70F1bC9BFc589082b27083f27ac85936C` | xLEND OFT | | **USDT0 OFT** | `0x14e4a1b13bf7f943c8ff7c51fb60fa964a298d92` | USDT0 OFT | #### Ethereum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0xD68700e70F1bC9BFc589082b27083f27ac85936C` | xLEND OFT | | **USDT0 OFT** | `0x6c96de32cea08842dcc4058c14d3aaad7fa41dee` | USDT0 OFT | ### 3. Supported Assets #### Deposit Assets xLEND accepts the following stablecoins for deposits: | Asset | Decimals | Chains Available | Notes | | --------- | -------- | ---------------- | --------------------------------------- | | **USDT0** | 6 | All chains | All spokes supported + HyperCore | | **USDT** | 6 | Hyperliquid | Ethereum + Hypercore | | **USDC** | 6 | All chains | All spokes supported (CCTP) + Hypercore | #### Underlying Asset **Primary Redemption Asset**: USDC * All redemptions are settled in USDC (6 decimals) * NAV is tracked in USDC equivalent (normalized to 18 decimals internally) ### 4. Oracle Feeds | Pyth | ​​ | ​ | | ---- | -------------------------------------------------------- | - | # xHYPE ### 1. Network Configuration #### Hub Chain **HyperEVM (Mainnet)** * Chain ID: `999` * LayerZero Endpoint ID: `30367` * Role: Primary share logic, asset management, NAV tracking #### Spoke Chains | Chain | Chain ID | LZ Endpoint ID | Status | | -------- | -------- | -------------- | -------- | | Arbitrum | 42161 | 30110 | ✅ Active | | Ethereum | 1 | 30101 | ✅ Active | ### 2. Contract Addresses #### HyperEVM (Hub Chain) | Contract | Address | Description | | ----------------------- | -------------------------------------------- | --------------------------- | | **ShareManager** | `0xac962fa04bf91b7fd0dc0c5c32414e0ce3c51e03` | xHYPE share token | | **DepositPipe (USDC)** | `0xE7E0B7D87c4869549a4a47A8F216e362D0efc9F9` | USDC deposits | | **DepositPipe (USDT0)** | `0xe2d9598D5FeDb9E4044D50510AabA68B095f2Ab2` | USDT0 deposits | | **RedemptionPipe** | `0x19f4881cdB479d01cE214F6908c99b4fe76C03e8` | All redemption types - USDC | | **OVaultComposerMulti** | `0x11b5078C327aCE6c42300A006a56D4c26906469f` | Cross-chain operations | | **NAVOracle** | `0xbF97a22B1229B3FfbA65003C01df8bA9e7bfF042` | Net Asset Value tracking | | **PriceOracle** | `0xC415641F4207643126655197789Bd4C524B71d5D` | Asset price feeds | | **TimelockController** | `0x75402596dbc63c450482E7bC895aa8B6c99B7491` | Governance timelock | #### Arbitrum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0xcffE430E9492966727Ddc60eb183fe93E5a218E4` | xHYPE OFT | | **USDT0 OFT** | `0x14e4a1b13bf7f943c8ff7c51fb60fa964a298d92` | USDT0 OFT | #### Ethereum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0xAc962FA04BF91B7fd0DC0c5C32414E0Ce3C51E03` | xHYPE OFT | | **USDT0 OFT** | `0x6c96de32cea08842dcc4058c14d3aaad7fa41dee` | USDT0 OFT | ### 3. Supported Assets #### Deposit Assets xHYPE accepts the following stablecoins for deposits: | Asset | Decimals | Chains Available | Notes | | --------- | -------- | ---------------- | -------------------------------- | | **USDT0** | 6 | All chains | All spokes supported + HyperCore | | **USDT** | 6 | Hyperliquid | Ethereum + Hypercore | | **USDC** | 6 | Hyperliquid | HyperEVM + Hypercore | #### Underlying Asset **Primary Redemption Asset**: USDC * All redemptions are settled in USDC (6 decimals) * NAV is tracked in USDC equivalent (normalized to 18 decimals internally) ### 4. Oracle Feeds | Provider | Link | Notes | | -------- | ------------------------------------------------------------------- | ----- | | Pyth | | | # xBTC ### 1. Network Configuration #### Hub Chain **HyperEVM (Mainnet)** * Chain ID: `999` * LayerZero Endpoint ID: `30367` * Role: Primary share logic, asset management, NAV tracking #### Spoke Chains | Chain | Chain ID | LZ Endpoint ID | Status | | -------- | -------- | -------------- | -------- | | Arbitrum | 42161 | 30110 | ✅ Active | | Ethereum | 1 | 30101 | ✅ Active | ### 2. Contract Addresses #### HyperEVM (Hub Chain) | Contract | Address | Description | | ----------------------- | -------------------------------------------- | --------------------------- | | **ShareManager** | `0x97df58CE4489896F4eC7D16B59B64aD0a56243a8` | xBTC share token | | **DepositPipe (USDC)** | `0x629010d62E54cfA49D6ac35e4e3DE2240d4cE4BF` | USDC deposits | | **DepositPipe (USDT0)** | `0x86826DfC171f1e0C6b6128CA05325B8cD9EcB68D` | USDT0 deposits | | **RedemptionPipe** | `0xfDF08966a8957FAfe1aB47488Fc97D15217e50Fe` | All redemption types - USDC | | **OVaultComposerMulti** | `0x846ca8EA8a22Bc36E3a1a7E85F3FCAE4d08d0C2F` | Cross-chain operations | | **NAVOracle** | `0x2A6448fc3A0FAde5811bb0087836a090EaA34715` | Net Asset Value tracking | | **PriceOracle** | `0xC415641F4207643126655197789Bd4C524B71d5D` | Asset price feeds | | **TimelockController** | `0xCB7DEE93B092f6b4a081A6F626670830DD17d2c5` | Governance timelock | #### Arbitrum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0xA06A65032b78106EA47d122387E40E1fbCBA942d` | xBTC OFT | | **USDT0 OFT** | `0x14e4a1b13bf7f943c8ff7c51fb60fa964a298d92` | USDT0 OFT | #### Ethereum | Contract | Address | Description | | ------------- | -------------------------------------------- | ----------- | | **ShareOFT** | `0x0c0104e35A101de9af2e0cb307A15e1175580Bd5` | xBTC OFT | | **USDT0 OFT** | `0x6c96de32cea08842dcc4058c14d3aaad7fa41dee` | USDT0 OFT | ### 3. Supported Assets #### Deposit Assets xBTC accepts the following stablecoins for deposits: | Asset | Decimals | Chains Available | Notes | | --------- | -------- | ---------------- | -------------------------------- | | **USDT0** | 6 | All chains | All spokes supported + HyperCore | | **USDT** | 6 | Hyperliquid | Ethereum + Hypercore | | **USDC** | 6 | Hyperliquid | HyperEVM + Hypercore | #### Underlying Asset **Primary Redemption Asset**: USDC * All redemptions are settled in USDC (6 decimals) * NAV is tracked in USDC equivalent (normalized to 18 decimals internally) ### 4. Oracle Feeds | Provider | Link | Notes | | -------- | ------------------------------------------------------------------ | ----- | | Pyth | | | # SDK The Tokenized SDK API provides programmatic access to xToken data, user holdings, and performance metrics. ### Base URL ``` https://api.liminal.money ``` All endpoints are prefixed with `/sdk/tokenized/:symbol` where `:symbol` is the xToken symbol (e.g., "xHYPE"). ### Authentication Currently, the SDK API is public and does not require authentication. ### Rate Limiting * Results are cached server-side (TTL varies by endpoint) * Rate limits are enforced but are generous for normal usage ### Available Endpoints #### Users Retrieve xToken holder data with detailed balance breakdowns and weighted LST holdings. | Endpoint | Description | | ----------------------------------------- | ------------------------------------ | | `GET /sdk/tokenized/:symbol/users` | Get all users with detailed balances | | `GET /sdk/tokenized/:symbol/lst-holdings` | Get users with weighted LST holdings | *** #### APY Retrieve historical APY data for xTokens. | Endpoint | Description | | -------------------------------- | ----------------------------- | | `GET /sdk/tokenized/:symbol/apy` | Get daily trailing 7d/30d APY | *** ### Balance Sources The SDK aggregates xToken holdings from multiple DeFi protocols: | Source | Description | | --------------- | -------------------------------------------------- | | Vault Balances | Direct xToken holdings in vault contracts | | Pendle PT/YT/LP | Pendle protocol positions (converted to xToken) | | DEX LP | Concentrated liquidity positions (Prjx, HyperSwap) | | Money Markets | Collateral in lending markets (HyperLend) | ### Supported xTokens | Symbol | Description | | ------- | ---------------------------- | | `xHYPE` | Tokenized HYPE delta-neutral | # Discovery Retrieve active xToken metadata for integrators. This endpoint returns the dynamic contract and asset data needed to integrate xTokens on a supported chain. Integrators can use it to discover xToken addresses, deposit pipe addresses, supported deposit assets, redemption pipes, and NAV oracle addresses without hardcoding them. #### Endpoint `GET /sdk/tokenized/xtokens` #### Base URL `https://api.liminal.money` #### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------- | | chainId | number | No | EVM chain ID to fetch xToken metadata for. Defaults to HyperEVM | #### Example Request ```actionscript-3 curl "https://api.liminal.money/sdk/tokenized/xtokens?chainId=999" ``` #### Example Response ```json { "chain": { "chainId": 999, "name": "HyperEVM" }, "data": [ { "id": "xhype", "name": "Liminal xHYPE", "symbol": "XHYPE", "address": "0xAc962FA04BF91B7fd0DC0c5C32414E0Ce3C51E03", "chainId": 999, "decimals": 18, "iconUrl": "https://liminal.money/icons/xtokens/x-hype.svg", "depositPipes": [ { "address": "0xe7e0b7d87c4869549a4a47a8f216e362d0efc9f9", "asset": { "address": "0xb88339cb7199b77e23db6e890353e22632ba630f", "symbol": "USDC", "decimals": 6, "iconUrl": "https://liminal.money/assets/USDC.svg" } }, { "address": "0xf64428046b62b6ce4750ab499b06b8a108e1e91c", "asset": { "address": "0x111111a1a0667d36bd57c0a9f569b98057111111", "symbol": "USDH", "decimals": 6, "iconUrl": "https://app.hyperliquid.xyz/coins/USDH_spot.svg" } }, { "address": "0xe2d9598d5fedb9e4044d50510aaba68b095f2ab2", "asset": { "address": "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb", "symbol": "USDT0", "decimals": 6, "iconUrl": "https://liminal.money/assets/USDT0.svg" } } ], "redemptionPipe": { "address": "0x19f4881cdb479d01ce214f6908c99b4fe76c03e8", "asset": { "address": "0xb88339cb7199b77e23db6e890353e22632ba630f", "symbol": "USDC", "decimals": 6, "iconUrl": "https://liminal.money/assets/USDC.svg" } }, "navOracle": "0xbf97a22b1229b3ffba65003c01df8ba9e7bff042" } ] } ``` #### Response Fields | Field | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | chain.chainId | Chain ID for the returned metadata. | | chain.name | Human-readable chain name. | | data\[].id | Stable lowercase xToken identifier. | | data\[].name | Display name. | | data\[].symbol | xToken symbol. | | data\[].address | xToken contract address on the selected chain. | | data\[].chainId | Chain ID for this xToken entry. | | data\[].decimals | xToken decimals. | | data\[].iconUrl | xToken icon URL. | | data\[].depositPipes\[].address | DepositPipe contract address for the listed | | deposit asset. | | | data\[].depositPipes\[].asset.address | Deposit asset token address. | | data\[].depositPipes\[].asset.symbol | Deposit asset symbol. | | data\[].depositPipes\[].asset.decimals | Deposit asset decimals. | | data\[].depositPipes\[].asset.iconUrl | Deposit asset icon URL. | | data\[].redemptionPipe.address | RedemptionPipe contract address. | | data\[].redemptionPipe.asset.address | Redemption output token address. | | data\[].redemptionPipe.asset.symbol | Redemption output token symbol. | | data\[].redemptionPipe.asset.decimals | Redemption output token decimals. | | data\[].redemptionPipe.asset.iconUrl | Redemption output token icon URL. | | data\[].navOracle | NAV oracle address for the xToken. | | data\[].oftAddress | LayerZero OFT or OFT adapter address on the selected chain. May equal `address` when the xToken itself is the OFT. | #### Notes * data\[].address is the xToken address users receive after depositing. * Each depositPipes\[] item maps one supported deposit asset to the DepositPipe that should be called for that asset. * redemptionPipe is singular because each xToken has one redemption pipe for the selected chain. * On Ethereum, Arbitrum, and other spoke chains, direct deposit/redemption pipe contracts do not exist; use the returned `oftAddress` for OFT-related integration. # Metrics Retrieve historical daily TVL, PPS (Price Per Share), and total supply for an xToken. #### Endpoint ``` GET /sdk/tokenized/:symbol/metrics ``` #### Parameters **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------- | | `symbol` | string | Yes | The xToken symbol (e.g., "xHYPE") | **Query Parameters** | Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------------- | | `range` | string | "30d" | Date range for the data | **Valid Range Values** | Value | Description | | ------ | ------------------ | | `7d` | Last 7 days | | `30d` | Last 30 days | | `90d` | Last 90 days | | `180d` | Last 180 days | | `max` | All available data | #### Response ```json [ { "timestamp": 1764028799999, "tvl": "1200000.123456789012345678", "pps": "1.045012345678901234", "totalSupply": "1148325.123456789012345678" }, { "timestamp": 1764115199999, "tvl": "1250000.987654321098765432", "pps": "1.048023456789012345", "totalSupply": "1192748.098765432109876543" }, { "timestamp": 1764201599999, "tvl": "1300000.555555555555555555", "pps": "1.051034567890123456", "totalSupply": "1237029.444444444444444444" } ] ``` #### Response Fields | Field | Type | Description | | ---------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------ | | `timestamp` | number | End of day UTC (23:59:59.999) in milliseconds | | `tvl` | string | Total Value Locked (totalAssets from vault contract) | | `pps` | string | Price Per Share (shareValue = totalAssets/totalSupply) | | `totalSupply` | string | Total supply of xToken shares | | All numeric values are returned as **strings** to preserve full precision (18 decimals). | | | #### Important Notes * Timestamps represent the **end of day UTC** (23:59:59.999) * Values are from the last available record of each day (end of day snapshot) * Data is collected hourly and aggregated to daily for this endpoint * If the requested range exceeds available data, all available data is returned * Empty array is returned if no historical data exists for the xToken #### Errors | Code | Description | | ---- | --------------------------------------------- | | 400 | Missing `symbol` parameter or invalid `range` | | 404 | xToken not found or no TVL data available | | 500 | Internal server error | #### Example Requests **Default Request (30 days)** ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/metrics" ``` **Last 7 Days** ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/metrics?range=7d" ``` **Last 90 Days** ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/metrics?range=90d" ``` **All Available Data** ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/metrics?range=max" ``` # APY Retrieve historical trailing APY for an xToken based on share value changes. ### Endpoint ``` GET /sdk/tokenized/:symbol/apy ``` ### Parameters #### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------- | | `symbol` | string | Yes | The xToken symbol (e.g., "xHYPE") | #### Query Parameters | Parameter | Type | Default | Description | | --------- | ------ | ------- | ----------------------- | | `range` | string | "30d" | Date range for the data | **Valid Range Values** | Value | Description | | ------ | ------------------ | | `7d` | Last 7 days | | `30d` | Last 30 days | | `90d` | Last 90 days | | `180d` | Last 180 days | | `max` | All available data | ### Response ```json [ { "timestamp": 1764028799999, "trailing3d": 0.510996879274972, "trailing7d": 0.510996879274972, "trailing30d": 0.510996879274972 }, { "timestamp": 1764115199999, "trailing3d": 13.431426694025916, "trailing7d": 13.431426694025916, "trailing30d": 13.431426694025916 }, { "timestamp": 1764201599999, "trailing3d": 9.549996005731476, "trailing7d": 9.549996005731476, "trailing30d": 9.549996005731476 } ] ``` ### Response Fields | Field | Type | Description | | ------------- | ------ | --------------------------------------------- | | `timestamp` | number | End of day UTC (23:59:59.999) in milliseconds | | `trailing3d` | number | Average of daily APYs over the last 3 days | | `trailing7d` | number | Average of daily APYs over the last 7 days | | `trailing30d` | number | Average of daily APYs over the last 30 days | All APY values are in **percentage format** (e.g., 15.67 = 15.67% APY). ### Important Notes * Timestamps represent the **end of day UTC** (23:59:59.999) * If insufficient data exists for a trailing period, available data is used * If the requested range exceeds available data, all available data is returned ### Errors | Code | Description | | ---- | --------------------------------------------- | | 400 | Missing `symbol` parameter or invalid `range` | | 404 | xToken not found or no TVL data available | | 500 | Internal server error | ### Example Requests #### Default Request (30 days) ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/apy" ``` #### Last 7 Days ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/apy?range=7d" ``` #### Last 90 Days ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/apy?range=90d" ``` #### All Available Data ```bash curl "https://api.liminal.money/sdk/tokenized/xHYPE/apy?range=max" ``` # Users ### Get User Balances Retrieve all users holding a specific xToken with their aggregated balance data across multiple DeFi protocols. #### Endpoint ``` GET /sdk/tokenized/:symbol/users ``` #### Parameters **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------- | | `symbol` | string | Yes | The xToken symbol (e.g., "xHYPE") | **Query Parameters** | Parameter | Type | Default | Description | | ----------- | ------ | ------- | ------------------------------------------------ | | `offset` | number | 0 | Number of results to skip | | `limit` | number | 100 | Results per page (max: 5000) | | `timestamp` | number | - | Unix timestamp (seconds) for historical balances | #### Response ```json { "users": [ { "address": "0x1234567890abcdef1234567890abcdef12345678", "totalBalance": "1250.50", "vaultBalances": [ { "shares": "500.00", "chainId": 999 } ], "pendlePT": [ { "shares": "100.00", "chainId": 999, "marketAddress": "0x..." } ], "pendleYT": [ { "shares": "50.00", "chainId": 999, "marketAddress": "0x..." } ], "pendleLP": [ { "shares": "150.00", "chainId": 999, "marketAddress": "0x..." } ], "dexBalances": [ { "shares": "350.00", "chainId": 999, "poolAddress": "0x...", "tokenId": "123", "fee": 500, "tickLower": -887220, "tickUpper": 887220, "dexName": "HyperSwap", "poolName": "xHYPE/USDC 0.05%", "totalValueLockedUSD": "1250000.00" } ], "moneyMarketBalances": [ { "shares": "100.00", "chainId": 999, "pairAddress": "0x..." } ] } ], "offset": 0, "limit": 100, "totalUsers": 1500, "timestamp": 1699900000 } ``` > **Note**: The `timestamp` field is only present in the response when requested via query parameter. #### Response Fields **User Object** | Field | Type | Description | | --------------------- | ------ | ------------------------------------------- | | `address` | string | User's wallet address | | `totalBalance` | string | Sum of all balance sources (human-readable) | | `vaultBalances` | array | Direct xToken holdings per chain | | `pendlePT` | array | Pendle Principal Token positions | | `pendleYT` | array | Pendle Yield Token positions | | `pendleLP` | array | Pendle LP positions | | `dexBalances` | array | DEX LP positions containing xTokens | | `moneyMarketBalances` | array | Collateral deposited in lending markets | **Vault Balance Object** | Field | Type | Description | | --------- | ------ | --------------------- | | `shares` | string | xToken balance | | `chainId` | number | Chain ID of the vault | **Pendle Balance Objects (PT, YT, LP)** | Field | Type | Description | | --------------- | ------ | ------------------------------ | | `shares` | string | xToken equivalent amount | | `chainId` | number | Chain ID | | `marketAddress` | string | Pendle market contract address | **DEX Balance Object** | Field | Type | Description | | --------------------- | ------ | --------------------------------------- | | `shares` | string | xToken amount in the LP position | | `chainId` | number | Chain ID | | `poolAddress` | string | Pool contract address | | `tokenId` | string | NFT token ID of the LP position | | `fee` | number | Pool fee tier (e.g., 500 = 0.05%) | | `tickLower` | number | Lower tick boundary of the position | | `tickUpper` | number | Upper tick boundary of the position | | `dexName` | string | DEX name (e.g., "HyperSwap", "Uniswap") | | `poolName` | string | Human-readable pool name | | `totalValueLockedUSD` | string | Pool TVL in USD | **Money Markets Balance Object** | Field | Type | Description | | ------------- | ------ | ------------------------------------- | | `shares` | string | Collateral amount (xToken equivalent) | | `chainId` | number | Chain ID | | `pairAddress` | string | Lending pair contract address | #### Example Requests ```bash # Basic request curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?limit=50&offset=0" # Historical query curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?timestamp=1699900000" # Pagination curl "https://api.liminal.money/sdk/tokenized/xHYPE/users?limit=100&offset=100" ``` *** ### Get LST Holdings Retrieve each user's proportional share of the xToken LST (Liquid Staking Token) holdings based on their xToken balance relative to all users. #### Endpoint ``` GET /sdk/tokenized/:symbol/lst-holdings ``` #### Parameters **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------- | | `symbol` | string | Yes | The xToken symbol (e.g., "xHYPE") | **Query Parameters** | Parameter | Type | Default | Description | | ----------- | ------ | ------- | ------------------------------------------------ | | `offset` | number | 0 | Number of results to skip | | `limit` | number | 100 | Results per page (max: 5000) | | `timestamp` | number | - | Unix timestamp (seconds) for historical balances | #### Response ```json { "users": [ { "address": "0x1234567890abcdef1234567890abcdef12345678", "totalBalance": "1000.00", "shareOfVault": "5.000000%", "weightedLstHolding": "500.00" }, { "address": "0xabcdef1234567890abcdef1234567890abcdef12", "totalBalance": "500.00", "shareOfVault": "2.500000%", "weightedLstHolding": "250.00" } ], "offset": 0, "limit": 100, "totalUsers": 1500 } ``` #### Response Fields | Field | Type | Description | | -------------------- | ------ | ---------------------------------------------------------- | | `address` | string | User's wallet address | | `totalBalance` | string | User's total xToken balance (human-readable) | | `shareOfVault` | string | User's percentage share of total vault (e.g., "5.000000%") | | `weightedLstHolding` | string | User's proportional LST amount (human-readable) | #### Example Requests ```bash # Basic request curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings" # With pagination curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings?limit=50&offset=100" # Historical query curl "https://api.liminal.money/sdk/tokenized/xHYPE/lst-holdings?timestamp=1699900000" ``` *** ### Important Notes * All `shares` and `totalBalance` values are in **human-readable format** (divided by 1e18) * Results are **cached for 60 seconds** * DEX positions calculate the xToken amount based on current pool price and position range * Pendle positions are scaled to match actual SY (Standardized Yield) balance on-chain *** ### Errors | Code | Description | | ---- | -------------------------------------- | | 400 | Missing `symbol` parameter | | 404 | xToken not found or LST not configured | | 500 | Internal server error | # Security & Risk Considerations xTokens bring convenience and composability, but like any DeFi product they also involve risks. Here are the main aspects to keep in mind: * **Smart Contract Risk:** Tokenized strategies run on audited contracts that handle minting, burning, and accounting of xTokens. Audits have been conducted by reputable firms, including Pashov Audit Group and Spearbit. Reviews and ongoing monitoring strengthen security; however, no on-chain contract is completely risk-free. Audit reports are available [here](https://docs.liminal.money/more/audits). * **Oracle Risk:** Token underlying value relies on oracles to update NAV. These oracles are secured using institutional-grade custody with multi-sig protections and independent third-party guardians, making compromise extremely unlikely. xTokens also rely on Pyth’s price feeds, and the smart-contract oracle logic is covered by independent security audits. * **Custodial Risk:** Underlying assets (USDC, spot, perps) are secured with institutional-grade custody: multisig, strict controls, and institutional-grade custodians. * **Redemption Liquidity:** In normal conditions, redemptions are smooth. In extreme cases (e.g. large withdrawals or sudden market stress), redemptions may involve delays, fees, or temporary pauses to protect the strategy. Liminal also maintains liquidity buffers to handle Instant Redemptions. * **Market Risk (Residual):** xTokens are designed to be delta-neutral and aim to provide predictable performance that reflects the underlying strategy. For asset-based xTokens, funding rates are a key driver of performance. Performance can also benefit from additional yield sources on the spot side, such as LSTs. In extreme scenarios, such as prolonged negative funding or when costs exceed returns, NAV may temporarily decline. For lending-based xTokens such as xLEND, the lending rate is the key driver. Lending rates cannot turn negative by construction, but they can compress toward zero in low-demand environments, reducing yield without putting NAV at risk.xTokens are built for steady and representative growth, but performance is not guaranteed. * **Hyperliquid Dependency:** Strategies rely on Hyperliquid’s markets. Issues such as downtime or halted trading could temporarily prevent yield accrual or rebalancing. While unlikely, this dependency is inherent to both Tokenized and Customized products. Tokenized strategies inherit Liminal’s core safety features. They use low leverage with actively managed hedges to minimize risk. Positions are rebalanced proactively to prevent liquidations. The value of each strategy is transparent on-chain, with collateral and debt visible in real time. Every xToken is fully collateralized by underlying assets, ensuring stablecoin redemptions at NAV under normal conditions. **Summary:** xTokens introduce additional considerations, smart contracts, pooled execution, and oracle reliance, but they are built with strong safeguards. xTokens are dynamic assets whose value changes based on strategy performance, they are not pegged stablecoins. Always review the latest documentation for details on each xToken, including fees and parameters. # Introduction Liminal Customized is Liminal’s original, Hyperliquid-native product: an individualized, automated delta-neutral strategy where each user operates through a fully isolated account on Hyperliquid. Instead of pooling capital together, every user has their own setup, their own positions, and their own risk parameters, while Liminal’s execution engine automates hedging, rebalancing, and all ongoing adjustments required to maintain a delta-neutral carry strategy. Each Customized user runs a per-asset strategy (e.g., BTC, ETH, HYPE), combining spot exposure and perpetual hedging to capture funding while minimizing directional risk. Unlike pooled products, your positions never mix with others: your account environment is isolated at the infrastructure level, and your performance is entirely your own. Everything is transparently visible on Hyperliquid’s explorer, positions, balances, PnL, margin usage, and liquidation thresholds. Customized supports both regular custody and self-custody mode. In regular mode, Liminal fully automates execution, spot allocation, perp sizing, re-hedging, and more for a seamless, hands-off experience. In self-custody mode, users authorize Liminal to operate a subaccount of their own Hyperliquid account through the agent system. You retain ownership and custody at all times, while Liminal manages execution programmatically. Because each user’s environment is independent, Customized enables deep personalization. Users can choose assets, adjust leverage, switch strategy presets, or update parameters as their market preferences evolve, all while Liminal handles execution, monitoring, and risk management on their behalf. The system is designed to adapt to both passive users seeking simplicity and advanced users who want precision and control. In short, Liminal Customized turns Hyperliquid’s account and subaccount architecture into individualized, automated delta-neutral engines. It is built for users who value transparency, ownership, and optionality, without sacrificing automation, execution quality, or safety. # How Liminal Customized Works #### 1. **Overview** When you deposit USDC into Liminal Customized, the protocol automatically opens two matched positions with your funds: * A long position in the spot market for a given asset (e.g. buying $BTC or $HYPE with a portion of your stablecoins). * A short position of equal size in the perpetual futures market for that same asset. By going long and short on the same asset, Liminal creates a hedged pair that neutralizes price movements (delta ≈ 0). This means if the asset’s price moves, the gains/losses on one side are offset by losses/gains on the other, keeping your net position value stable. With price risk neutralized, the strategy then earns yield from: #### **2. Perpetual funding payments** On Hyperliquid, traders holding long perp positions periodically pay funding fees hourly to short traders when the perp price is above the spot price (and vice versa when below). As Liminal holds a short perp, it collects funding payments paid by long traders. These funding rates are driven by market demand for leverage. All yield is real yield, not reliant on any token emissions or inflation. There are no reward tokens, only returns generated from market mechanics. #### **3. Automation** The entire process, opening positions, rebalancing, risk management, is fully automated by Liminal’s engine. Key steps include: * **Deposit Execution:** The moment you deposit, Liminal executes the strategy: buying the spot asset and shorting the perp in the correct ratio, in real time. Your deposit is instantly deployed into the strategy. * **Yield Collection:** Funding fees from the perp are collected continuously and accrue to your balance. * **Risk Mitigation:** Liminal’s Liquidity Engine actively manages risk. It uses measured leverage and built-in user-level cap and buffers aiming to avoid liquidation events. If needed, it will reduce exposure or fully close positions in a controlled manner before a liquidation point is hit. These controls are designed to preserve capital and keep the strategy healthy. While no DeFi system is entirely risk-free, Liminal inherits Hyperliquid’s robust risk framework to keep strategies stable and capital protected * **Transparency:** Every action (trades, rebalances, fees) happens on-chain through Hyperliquid’s infrastructure and can be monitored. The Liminal app provides real-time tracking of your position’s performance and even an on-chain verification of strategy actions via a **Verify** button in **Your Activity** section. **Summary:** In Liminal Customized, you deposit stablecoins → Liminal opens a hedged spot/perp position → yield accrues from funding → you can withdraw your Liminal balance anytime. All of this occurs without you managing any trades. The benefit is consistent, market-neutral yield that doesn’t depend on token incentives. Enable Self-Custody anytime in a few clicks. # Key Features and Benefits * **Delta-Neutral Yield:** Earn yield without exposure to price swings. Liminal’s delta-neutral structure means your returns are not tied to crypto prices going up or down. This provides stability and consistency in returns, as long as funding conditions remain favorable. * **Real Yield from Market Activity:** Yield comes from actual market demand (funding rates), not from printing new tokens or inflation. Your profit is essentially a share of what leveraged traders are paying to maintain their positions on Hyperliquid. * **Fully Automated Execution:** Liminal manages strategy setup, trade execution, and rebalancing in real time, no expertise required. For regular users it’s fully set-and-forget, the platform’s backend reacts 24/7 to market changes in real time. Using our self-custody solution, you’ll need to equalize balances after each rebalance. * **Avoidance of Liquidations:** The strategy is engineered with measured leverage and safety buffers to avoid liquidation events. Rebalances aren’t continuous; the engine acts only when necessary to protect capital and net yield. If a position approaches a risk threshold, Liminal’s engine will first apply the least-cost adjustments (e.g., partial size reductions) and only escalate as needed, up to fully closing and reopening positions to reset risk. This strategic, low-frequency rebalancing minimizes execution costs and spread impact, ensuring the best capital efficiency. * **No Lock-ups, Withdraw Anytime:** There are no fixed lockup periods in Liminal Customized. You can withdraw your money at any moment (in full or partially) and the system will promptly unwind your positions. There are also no exit fees or penalties for withdrawing. * **Transparency and Verification:** Every Liminal strategy action (trades, rebalances, fees) occurs on HyperCore. Through the app’s interface, you can click **Verify** to view on-chain proofs of your positions and yields. Performance metrics are updated in real time, and complete execution data is accessible for users who want to audit it. This ensures full transparency and helps you confirm that the strategy operates exactly as intended. * **Built on Hyperliquid:** Liminal is only possible on Hyperliquid Layer-1, which provides deep liquidity and high-speed execution for both spot and perpetual markets. This means trades happen fast with minimal slippage, and the underlying markets can handle large volumes safely. Liminal leverages Hyperliquid’s HyperCore engine to place and adjust orders with on-chain speed rivaling centralized exchanges. * **Self-Custody Options:** For users who prefer to retain full control, Liminal supports self-custody via Hyperliquid’s Agent system. Even when Liminal manages keys on your behalf, it does so through secure enclaves and encrypted keys. With self-custody enabled, trades are executed directly from your own Hyperliquid account while still enjoying full automation. * **User-Friendly Interface:** The Customized UI gives you full control over your strategy with a clean, intuitive design. Track your real-time APY, earned funding, TVL, and balance at a glance, customize your allocations with simple sliders, and manage leverage per asset. View your holdings, monitor activity, and deposit or withdraw seamlessly, all in one place. Overall, Liminal Customized bridges the gap between powerful market-neutral strategies and everyday users. It delivers a hands-off, professional-grade yield strategy in a way that’s accessible and safe for anyone. # Regular vs Self-Custody For security-conscious users, DeFi institutions, or individuals who want to retain full control of their funds, Liminal offers a unique self-custody option. This mode allows you to run the same delta-neutral strategies directly from your own Hyperliquid account (sub-account). The benefit is that you retain full custody of your assets and gain more control, while Liminal’s engine still executes trades on your behalf via Hyperliquid's native agent system. ### **1. Key Features of Self-Custody Mode:** * **Self-Custody via Hyperliquid Agent:** Self-Custody users authorize Liminal as an “Agent” (trade-only; revocable anytime; typical validity \~6 months) on their Hyperliquid account. You give Liminal permission to execute trades on a specific sub-account of your Hyperliquid account, without granting any transfer or withdrawal rights. Liminal cannot move your funds out; it can only trade within the sub-account. You retain the ability to revoke this permission at any time [here](https://app.hyperliquid.xyz/API). * **Dedicated Sub-Accounts:** Liminal creates a separate sub-account under your Hyperliquid account. This isolates the strategy’s funds and positions from your other trading activities and from other strategies. Each sub-account has its own balances, margin, and risk isolated. This also means you can run multiple strategies or allocate to Liminal while keeping your main account separate. * **Eligibility:** Hyperliquid currently requires at least **$100k of executed trading volume** to create a subaccount. Additionally, if you already have funds deposited in **regular mode**, you’ll need to **fully withdraw them first** before switching to **Self-Custody Mode**. Once these conditions are met, you can activate Self-Custody directly from the Liminal interface by clicking on “Custody” at the top right. ### **2. How to Activate Self-Custody Mode:** In the Liminal app, open the top-right dropdown menu and click on “Custody”. The app will display the requirements and guide you through the activation process. 1. **Authorize Agent:** Liminal will ask you to authorize its trading agent to manage your strategy automatically in Self-Custody Mode. Click Authorize and sign the message in your wallet. *Note:* The trading agent authorization is valid for 6 months. Close to expiration date, you’ll receive a notification from Liminal asking you to sign a new agent. 2. **Create Sub-Account:** Through Liminal, create a dedicated Hyperliquid sub-account for your strategy. Enter a name to help you identify it (e.g. *“LiminalStrategy”*), then click Create Sub-Account. Liminal will automatically initialize this sub-account on Hyperliquid and link it to the trading agent authorized in Step 1. This sub-account will have its own balance and trading history, completely separated from your main Hyperliquid account and any other strategies. 3. **Link Telegram:** Connect your Telegram account to get real-time alerts about your strategy. If manual action is needed (e.g. rebalancing or equalizing balances), Liminal will notify you instantly, while your position stays delta-neutral throughout. To set up, click **Verify Telegram Account** in the app and send the code to the official Liminal Alerts Bot (@liminalalerts\_bot). 4. **Approve builder code:** The first time you switch to Self-Custody Mode, Hyperliquid will ask you to approve builder codes. This step simply enables Liminal to use Hyperliquid’s built-in mechanism for charging fees. It’s a quick, one-time approval, once you confirm, the setup is complete and your strategy immediately runs in Self-Custody Mode. ### **3. Important Differences in Self-Custody Mode:** * **Adjusting Balances During Rebalance** In regular mode, everything is handled automatically, Liminal closes and reopens positions, moves USDC where needed, and keeps your strategy delta-neutral without any intervention. In self-custody mode, as Liminal can only execute trades on your Hyperliquid sub-account (and cannot transfer USDC between spot and perp balances), you’ll be prompted to equalize your balances after a rebalancing. For example, if positions are temporarily closed to manage risk, reopening the strategy might require shifting a small amount of USDC between your spot and perp balances to restore a perfectly delta-neutral position. There’s no urgency; your position remains non-directional even if you don’t adjust immediately. However, the affected portion of your funds will temporarily sit in USDC and won’t generate yield until you confirm the adjustment. You’ll also receive a notification via the Liminal Telegram bot (@liminalalerts\_bot), guiding you step by step. * **Manual Actions: Do not interact manually with your Liminal sub-account** When using Self-Custody Mode, Liminal executes all strategy actions (deposits, withdrawals, rebalancing, and liquidation handling) via the Hyperliquid Agent on your dedicated sub-account. Any manual interaction with this sub-account, such as placing trades, transferring funds, or modifying positions directly, will break strategy execution and deactivate the Execution Engine. This means Liminal can no longer guarantee proper performance or maintain delta-neutral exposure. To avoid this: * Only use the Liminal app to manage your strategy * Never trade or move funds directly in the Hyperliquid sub-account If such activity is detected: * You’ll receive an instant notification via Telegram * A modal will appear in the app prompting you to reset the strategy via a deposit/withdraw cycle before continuing ### **4. Agent Expiration & Renewal** In Self-Custody Mode, Liminal leverages Hyperliquid’s agent system to execute strategies directly from the user’s sub-account. These agents have a limited validity period, typically 6 months, after which they automatically expire. **Once an agent has expired, Liminal can no longer trade on behalf of the institution until it is renewed.** To prevent disruptions, users receive a Telegram notification 30 days before their agent is set to expire. From that moment, they can renew their agent at any time within this window to avoid the risk of being left without an active agent. Renewal is simple: just return to the Liminal interface and follow the same steps used during the initial setup. These safeguards ensure capital protection, execution continuity, and optimal yield performance. Regular mode is designed for users who want a simple, hands-off solution. You can deposit, let the strategy run, and essentially set it and forget it, Liminal handles everything automatically in the background. Self-Custody mode, is tailored for more active or professional users who prefer to retain full custody of their funds and are comfortable keeping an eye on their positions. Self-custody users must handle rebalancing actions when prompted in order to protect positions, and every 6 months their Hyperliquid agent expires, requiring renewal through the Liminal interface to continue operating delta-neutral strategies. This mode is ideal for professional desks or active users who value custody and direct control over their execution. # Deposit, Withdraw and Migrate ### 1. How to deposit into Liminal Getting your funds into Liminal is straightforward. Currently, Liminal accepts USDC (and USDT0) deposits, which are converted into the strategy. The platform supports multiple deposit methods, so you can choose based on where your funds are: **Supported Deposit Channels:** * **Arbitrum (L2):** You can deposit USDC directly from any Ethereum wallet via the Arbitrum network. Liminal will automatically bridge those funds to Hyperliquid and deploy them into the strategy. * **Hyperliquid (Spot or Perpetual):** If you are a Hyperliquid user, you can deposit from your Hyperliquid balances. Liminal allows direct deposit from your Hyperliquid spot or perpetual balance. This on-chain transfer is immediate. * **deBridge (Ethereum, Base, BNB Chain, HyperEVM):** Liminal integrates cross-chain deposits using deBridge for users who have USDC/USDT0 on other chains. Your stablecoins will be bridged and automatically routed into Liminal’s Hyperliquid strategy on arrival. **Deposit Steps:** 1. **Connect Your Wallet:** Visit the Liminal web app and connect an EVM-compatible wallet (MetaMask, Rabby, etc.). 2. **Select Deposit Source:** Choose the network where your stablecoins are currently located. Self-Custody users’ deposits are limited to Hyperliquid Spot & Perps only. 3. **Enter Deposit Amount:** Specify how much stablecoins you want to deposit. The minimum deposit is 500 dollars, also maintain a little extra to cover any network gas fees if using Arbitrum or bridges. 4. **Confirm and Sign:** Submit the deposit through the interface. You’ll be prompted to sign a transaction. Confirm it in your wallet. Liminal will then handle moving the funds and deploying the delta-neutral position automatically. 5. **Deployment:** Once confirmed, your deposit will be processed. Liminal’s engine will immediately allocate the capital to open the spot and perp positions for your strategy. This typically completes within minutes. You can track the status of your deposit at the bottom of the dashboard under **“Your Activity”,** it will show as **Queued**, then **Executing**, and finally **Success** once fully deployed. Once completed, you’ll see your **Liminal Balance** (initial deposit value) on the UI, and the strategy begins accruing yield right away. 6. **Track Your Position:** After depositing, you can monitor your strategy’s performance in real time directly from the UI. You can view your balance, APY, and all key metrics at a glance. For full transparency, you can double-check everything in **Your Holdings** or by using the **Verify** button to see on-chain proofs of your positions and yields. Your position continues to be managed automatically from here. Once deposited, you’re all set, Liminal Customized is now working for you! ### 2. How to withdraw from Liminal You are free to withdraw your funds from Liminal at any time. **Withdrawals are designed to be fast and straightforward while minimizing slippage and market impact.** **Supported Withdrawal Channels:** * **Arbitrum:** Regular users can withdraw USDC to their EVM wallet on Arbitrum. *(Note: Currently, Self-Custody Mode users cannot withdraw directly to Arbitrum through Liminal, because their funds reside on Hyperliquid sub-accounts. This route is for regular mode only.)* * **Hyperliquid Spot:** You can withdraw directly into your Hyperliquid spot balance in USDC. This is convenient if you plan to keep using Hyperliquid or want to trade/transfer via Hyperliquid after exiting Liminal. **Withdrawal Steps:** 1. **Initiate Withdrawal:** In the Liminal app, click the “Withdraw” button next to your Liminal balance. 2. **Choose Destination:** Select Arbitrum or Hyperliquid Spot as the withdrawal route. 3. **Enter Amount:** Specify how much you want to withdraw. You can withdraw a partial amount or the entire balance. 4. **Confirm:** Once you submit, withdrawal requests initiate instantly and typically settle within minutes. 5. **Strategy Unwind:** Behind the scenes, Liminal’s engine will close your delta-neutral position corresponding to the amount withdrawn. This means it will sell the spot asset and close the perp short in the necessary amounts. 6. **Funds Received:** You will then receive the USDC. *No Fees or Lockup:* Liminal does not charge any withdrawal fee or impose delays. You get your full balance minus any final execution costs from unwinding. Do note that if the market is highly volatile or if your position was large relative to market liquidity, there might be minor slippage or spread cost when closing the position. Liminal’s engine tries to optimize this and usually the impact is minimal. Because there’s no lockup, some users might treat Liminal like a savings account, deposit when you have spare capital, withdraw when you need it. Just remember each deposit/withdraw has to execute trades, so frequent in/out activity may incur cumulative trading costs. It’s best to use Liminal for funds you intend to leave earning yield ideally over longer periods to maximize net returns.
### 3. How to migrate from Customized to xTokens Migration lets you move your Customized positions into xTokens in a few clicks, without withdrawing first. Your capital stays deployed throughout the process. **Migration Steps** 1. **Open the Migrate tab** in the Liminal app, next to Deposit and Withdraw. Your eligible Customized positions are listed with their current APY alongside the available xToken targets. 2. **Select your target xToken** for each position. Choose xHYPE or xBTC from the dropdown. The interface shows the expected xToken APY and estimated output size so you can compare before confirming. 3. **Complete the migration.** In Regular Mode, execution is fully automatic. In Self-Custody Mode, a guided modal walks you through three sequential steps: transferring your perpetual balance to spot on your Hyperliquid subaccount, depositing into the xToken vault, and processing the final settlement. Each step requires a signature in your wallet. 4. **Strategy unwind.** Liminal closes your Customized position and routes the capital into the corresponding xToken vault. 5. **xTokens received.** Your xTokens land directly in your wallet on HyperEVM and start accruing yield immediately. **Note:** there is no reverse migration. To return to Customized after migrating, redeem your xTokens and open a new Customized deposit. # User Interface Liminal’s Customized now provides a **single unified experience** for managing your strategies. Our UI merges simplicity and advanced controls into one view, making it intuitive for beginners while offering powerful customization options for experienced users. From Liminal Customized UI, you can: * View all **key metrics** at a glance: your Liminal balance, APY, funding earned, TVL, and historical performance. * Monitor your **positions** in real time with up-to-the-second data directly from Hyperliquid. * Customize your **strategy parameters**, including leverage, asset selection, and allocations. * Access detailed analytics and transparency features, such as **on-chain verification** of trades and yields via the **Verify** button. ### 1. Monitoring Performance As you use Liminal Customized, you’ll notice several metrics on your dashboard that help you understand your strategy’s performance. The main ones are: #### **Your 30d APY (%):** Your 30-day APY represents the annualized funding yield generated by your strategy over the last 30 days. For each asset, the contribution is derived from the funding rate of the perpetual leg, adjusted for both the leverage applied and the asset’s allocation within the strategy. The 30-day APY is calculated as the weighted average of these contributions across all assets. A 10% performance fee is then deducted from this weighted average, meaning the displayed APY is already net of performance fees. An exception applies for USDe and thBILL allocations are exempt from performance fees. It is important to note that this metric does not include execution costs such as spreads, trading fees, or builder fees. Execution costs are highly dependent on prevailing market conditions and vary with factors such as volatility and the user’s specific entry price. Since these conditions cannot be anticipated before execution, the 30-day APY should be interpreted as a gross performance indicator of funding yield potential, rather than a final net return. #### Your Liminal Balance: **Your Liminal Balance:** Your Liminal balance shows the current total value of your strategy across both spot and perpetual positions. Short-term fluctuations can occur due to: * Spot/perp price spreads at entry, exit, or rebalance * Execution slippage * Temporary price volatility These variations are typically minor and tend to be offset over time as funding earned accumulates. This balance reflects your net value within Liminal, but it may briefly diverge from your initial deposit, especially around rebalances. #### Funding earned: Funding earned reflects the total funding received by your delta-neutral strategy, after Liminal’s 10% performance fee has been deducted. In short: Funding earned = Gross funding earned – 10% performance fee Execution costs are not deducted. This metric helps you evaluate the raw performance of your strategy. Your actual balance accounts for this value **minus** execution-related costs over time. ### **2. Leverage Customization** **Leverage** is a key tool to optimize capital efficiency on Liminal. It’s available to both **Self-Custody** and **Regular** users, allowing each to adjust exposure according to their risk and yield preferences. Leverage can improve capital efficiency and amplify returns within Liminal’s delta-neutral framework. However, higher leverage brings the position closer to its risk thresholds and makes it more sensitive to market fluctuations. This may result in more frequent rebalancing in order to preserve delta neutrality and keep the strategy aligned. Such additional adjustments generate higher execution costs, which can gradually erode the net yield of the strategy. Leverage therefore increases both the potential upside and the likelihood of higher costs, a balance that should be carefully considered by each user. Using leverage allows you to allocate less USDC to the perp leg and more to the spot leg, increasing the total position size while keeping the same deposit. **Example (illustrative only):** If the base strategy environment yields **\~10% APY**: * 1× leverage: 10% APY * 2× leverage: \~13.3% APY In the example above, the performance gain behaves as follows: * **Non-linear growth:** Returns increase with leverage, but not proportionally. * **Asymptotic cap (example-specific):** In this scenario, performance tends toward a theoretical maximum of 20%, even with higher leverage. *Leverage Risk/Reward:* Liminal’s engine manages higher-leverage configurations with the same core controls as standard setups, but tighter collateral buffers make the system more sensitive to price movements. This can lead to more frequent rebalances and execution costs, where the engine may partially reduce a position to restore safety margins or, in rare cases, fully close the position, always well before the true liquidation price to maximize user protection.\ \ **Leverage limits by asset** Liminal does not adjust leverage dynamically, but applies strict leverage caps based on asset volatility. Currents limits: * **BTC/ETH** → up to 2**×** * **Volatile assets like FARTCOIN, HYPE or PUMP** → no leverage allowed for now Leverage parameters may evolve over time, depending on market conditions, liquidity, and volatility of each supported asset. ### **3. Custom Strategy Parameters** Beyond leverage, Liminal Customized gives you the ability to choose which asset’s funding rate you want to capture. While strategies originally launched with $BTC as the default market, Liminal has since expanded to support multiple spot assets listed by Unit, and this list evolves with listings and liquidity conditions. New assets are gradually introduced as Unit lists them, but availability also depends on market depth and liquidity conditions. If an asset listed by Unit is too illiquid or volatile, it won’t immediately be enabled in Liminal, our engine only supports markets where execution is safe and scalable. Each supported asset operates as a separate strategy, but you can also combine several into a single multi-asset portfolio using the asset selector. This lets you diversify funding exposure and build more customized yield profiles. Importantly, each asset has its own safety parameters, including: * Asset-specific leverage caps based on volatility and liquidity * TVL and per user-caps to avoid saturating markets * Custom risk thresholds controlling partial or full position reductions These measures ensure that even as more markets are added, your strategy remains stable and secure. Because funding rates and liquidity vary by asset, each strategy has its own APY potential and risk profile. For example, one asset may offer higher funding yields but come with wider spreads or more frequent rebalancing. UI displays a per-asset breakdown of performance as well as your combined portfolio totals, giving you full transparency into how each allocation contributes to overall returns. To help users navigate these differences, Liminal provides an **Assets page** featuring a detailed scoring system for each market. This score factors in multiple parameters such as liquidity depth, volatility, funding stability, and historical efficiency, allowing you to quickly assess the relative safety and performance potential of every asset. Finally, while chasing higher APYs can be tempting, it’s important to understand the underlying asset’s liquidity, volatility profile, and the execution costs involved. Frequent switching between assets can increase these costs and impact performance. Liminal is designed to help you capture funding efficiently while keeping systemic risk controlled, but informed allocation choices remain key to optimizing your results. # Security & Risk Considerations Liminal Customized is designed with a strong focus on security, capital protection, and risk management. By maintaining fully delta-neutral positions, the strategy eliminates directional market exposure, your yield does not depend on whether prices go up or down. However, since Liminal operates on advanced on-chain trading infrastructure, certain operational, liquidity, and funding-related risks remain. This section explains how custody works, outlines the key risk factors, and details the safeguards in place to protect your capital and ensure strategy continuity. **Custody and Security Measures** In Regular Mode, your funds are held in an Externally Owned Account (EOA) generated specifically for you: * Each user has a dedicated, segregated EOA * All signature operations are executed within an off-internet enclave, and private keys are encrypted at rest using AES-256 to ensure maximum security * Withdrawals can only be initiated by you via the Liminal app and can only go to your linked withdrawal address **Self-Custody Mode** In Self-Custody Mode, your funds remain entirely under your control within a Hyperliquid sub-account: * Liminal is authorized as an agent with trade-only permissions, it cannot transfer or withdraw your funds * You can revoke this authorization at any time directly from Hyperliquid’s website via the API page * This mode gives you full custody but requires slightly more active monitoring, as you may occasionally need to take small actions (e.g., adjusting balances after a rebalance). However, Liminal continuously monitors your positions and implements safeguards to help prevent unwanted liquidations. ### **Risks** Liminal Customized is designed to minimize risk while providing real, sustainable, market-neutral yield. However, since strategies run on advanced on-chain infrastructure, certain risks remain. This section outlines the primary risks and explains how Liminal Customized manages or mitigates them. **1. Market Risk Is Minimized, Not Eliminated** Delta-neutral positioning eliminates exposure to price direction, but short-term fluctuations in your balance can still occur due to: * Sudden volatility temporarily impacting the spot/perp balance * Wider spreads during rebalances or rapid price moves Liminal’s engine automatically rebalances positions when needed and uses conservative leverage to maintain wide safety buffers. **2. Negative Funding Rates** Liminal Customized captures yield from perpetual funding payments on Hyperliquid. These rates are dynamic and can occasionally turn negative: * Negative periods may temporarily reduce returns * Over the long term, most major assets have historically remained net positive Liminal charges a performance fee only on positive funding PnL. If there’s no yield, there are no fees. If an asset consistently delivers poor funding, you can switch strategies or choose another market. **3. Hyperliquid Infrastructure Risk** Liminal Customized operates entirely on Hyperliquid’s infrastructure: * HyperCore for real-time execution across spot and perpetual markets * Native liquidity and price feeds provided directly by Hyperliquid If Hyperliquid experiences downtime or maintenance, Liminal strategies may be temporarily paused including position updates, rebalancing, or withdrawals. Your funds remain safe in your dedicated EOA or Hyperliquid sub-account, and execution resumes automatically when systems are back online. **4. Stablecoin Risk (USDC)** Liminal Customized operates on HyperCore, which is USDC-native. All strategies ultimately settle in USDC, which carries: * Issuer risk (Circle) * Possible depegging during extreme events While USDC is widely trusted, no stablecoin is fully risk-free. **5. Liquidity Constraints** Liminal processes deposits and withdrawals in real time, but during high-volatility or low-liquidity conditions: * Withdrawals may be slightly delayed to unwind positions safely * Large exits may be processed in stages to minimize slippage Your funds always remain accessible, but execution timing may be optimized to protect capital. **6. Auto-Deleveraging (ADL) Risk** Auto-Deleveraging (ADL) mechanisms exist across all major perpetual futures exchanges, not just Hyperliquid. They act as a last-resort safeguard to prevent systemic bad debt when normal liquidation processes fail under extreme volatility. On Hyperliquid, liquidations first occur directly through the order book, where the system attempts to close positions progressively based on available market depth. If remaining positions cannot be absorbed, the Hyperliquid Liquidity Provider (HLP) intervenes as a backstop liquidator to stabilize the market. Only if the HLP itself becomes undercollateralized does the ADL mechanism trigger, force-closing positions from profitable counterparties to restore balance. Although such situations are extremely rare, they can lead to the early closure of certain positions, including Liminal’s perpetual hedges. This may temporarily affect realized PnL or yield consistency during periods of severe market stress. Liminal continuously monitors market conditions and volatility to assess and manage risks related to potential ADL events, but users should understand that ADL is an exchange-level safeguard fully managed by Hyperliquid and outside of Liminal’s control. While the likelihood of ADL can be minimized through prudent risk management, it can never be fully eliminated. **7. Self-Custody Operational Risks** When using **Self-Custody Mode**, a few additional considerations apply: * **Agent authorization:** Valid for 6 months. Before it expires, you’ll receive a notification. Simply return to the Liminal app, revoke the expired agent, and approve the new one. * **Adjusting balances:** The app may prompt you to adjust spot/perp balances manually. There’s no urgency, your exposure remains delta-neutral, but the affected funds won’t earn yield until you confirm. * **Do not manually trade:** Avoid placing trades or transferring funds directly in your Hyperliquid sub-account. Manual interaction will pause the strategy and may require a reset via a deposit/withdraw cycle. **8. Asset Volatility & Leverage Risk** Some strategies may involve highly volatile or low-cap assets. These can: * Trigger more frequent rebalancing * Increase execution costs due to sharp price swings * Reduce net yield over time despite attractive funding Additionally, even on more stable assets like $BTC, $ETH, or $SOL, using higher leverage narrows safety buffers and can increase the frequency of rebalances or liquidation risk. Liminal enforces strict leverage caps, position limits, and dynamic TVL controls to manage these risks, but users should carefully assess the risk/reward trade-off before allocating capital. **Final Note** Liminal Customized is designed to deliver sustainable, market-neutral yield while prioritizing capital protection. While risk is minimized, it cannot be entirely eliminated. Always assess your personal risk tolerance and only deposit funds you’re comfortable allocating. # Introduction Liminal Cash is an embedded yield layer for applications that hold idle USDC on behalf of their users. It is not a stablecoin, not a new synthetic dollar, and not a separate user-facing asset that needs to be traded or managed manually. Liminal Cash is infrastructure that allows apps with USDC balances to make that idle USDC productive by routing it into xLEND, while keeping each depositor’s position isolated in their own Cash Account. Many applications hold USDC temporarily before users trade, withdraw, bridge, or perform another action. During that idle period, the capital usually does nothing. Liminal Cash turns that idle balance into productive capital by putting it to work in xLEND, Liminal’s yield-bearing xToken strategy for lending yield. From the user’s perspective, the experience can remain simple: they deposit USDC into the application as usual, and the application can make that balance productive in the background. Behind the scenes, Liminal Cash creates or uses a dedicated smart-contract account for each depositor. That account holds the user’s xLEND position and can later redeem it back into USDC when the application or user flow requires liquidity again. Liminal Cash is designed for: * Apps with idle USDC balances * Wallets or front ends that want to offer passive yield on deposited USDC * Protocols that want to keep user balances productive without building their own yield infrastructure * Integrators that want per-user accounting instead of one large pooled treasury position The important distinction is that Liminal Cash does not transform USDC into a new stablecoin. It uses USDC as the input asset and xLEND as the underlying yield source. Each depositor has their own Cash Account, and that account represents the technical boundary between one user’s position and another user’s position. In short, Liminal Cash lets applications keep USDC useful while it is waiting to be used. # How Does It Work Liminal Cash sits between an application’s USDC deposit flow and xLEND. When a user deposits USDC through an integrated application, the application can route that idle capital into xLEND instead of leaving it inactive. The user does not need to manually interact with xLEND directly. The integration handles the flow, while the Liminal Cash contracts provide the per-user account structure and redemption logic. The core idea is simple: 1. A user deposits USDC into an application. 2. The application routes the productive portion of that USDC into xLEND. 3. A dedicated Cash Account is used for that user and that xLEND share token. 4. The Cash Account holds the user’s xLEND shares. 5. When liquidity is needed, the position can be redeemed back into USDC. 6. Redeemed USDC can be routed back to the user’s HyperCore destination. Each Cash Account is deterministic. This means the account address can be predicted before it is deployed. The factory derives the account from the user address and the xLEND share token, so the same user and same share token always map to the same Cash Account. This gives integrators a clean accounting model. Instead of all users being merged into one app-owned balance, each depositor has a distinct on-chain account that holds their own xLEND shares. ### Cash Accounts A Cash Account is a minimal smart-contract account deployed by the Liminal Cash Factory. Its role is to hold xLEND shares for one depositor and allow approved redemption flows to be executed. The account records: * The factory that deployed it * The user it belongs to * The xLEND share token it holds This structure matters because it avoids treating the application’s treasury as the custody layer for all user funds. The user’s productive balance is represented by shares held in a user-specific account. ### Keeper Execution Liminal Cash uses a keeper to execute operational actions such as redemption. The keeper is not designed to custody user funds. Its role is to trigger approved flows through the Cash Account. For example, when USDC needs to be returned, the keeper can call the redemption function, but the redeemed USDC is routed through the configured flow rather than being paid to the keeper. This makes the keeper an execution actor, not the owner of the user’s position. ### xLEND as the Yield Source The yield source behind Liminal Cash is xLEND. When idle USDC is put to work, the position is represented through xLEND shares. As xLEND accrues yield, the value of the user’s position can increase according to the performance of the underlying strategy. Liminal Cash does not create the yield itself. It gives applications a clean way to embed xLEND into their own USDC deposit experience. # Minting and Bridging In Liminal Cash, “minting” does not mean minting a new stablecoin. It refers to the process of using deposited USDC to enter the underlying xLEND position and receive xLEND shares. Those shares are then associated with the user’s Cash Account. The user-facing experience can be simple, but the technical flow has two sides: * Minting xLEND shares when idle USDC is made productive * Redeeming and routing USDC back when the user or application needs liquidity ### Minting Flow When a user deposits USDC into an integrated application, the application can decide to route that USDC into xLEND. A typical flow looks like this: 1. The user deposits USDC into the application. 2. The application identifies the user’s Cash Account for xLEND. 3. If the Cash Account does not exist yet, it can be deployed deterministically. 4. The USDC is supplied into the xLEND minting flow. 5. xLEND shares are received and held by the user’s Cash Account. 6. The application can display the user’s productive USDC balance in its own interface. The important point is that the user’s position is not represented by a new Liminal Cash token. It is represented by xLEND shares held in that user’s dedicated Cash Account. ### Redeeming Flow When USDC is needed again, the xLEND position can be redeemed. Liminal Cash supports redemption flows through approved redemption pipes. These pipes are controlled at the factory level, which means Cash Accounts cannot redeem through arbitrary contracts. There are two main redemption patterns: * Instant redemption * Standard redemption ### Instant Redemption Instant redemption is used when liquidity is available immediately. In this flow, the Cash Account redeems xLEND shares through an approved redemption pipe. The redeemed asset is USDC. Once the USDC is received, the Cash Account routes it toward the configured HyperCore recipient through the CoreDepositWallet flow. This is useful when the application needs to quickly make the user’s USDC available again. ### Standard Redemption Standard redemption is used when the position needs to be unwound through a queued or delayed process. In this flow, the Cash Account submits a redemption request. The account records the pending redemption state, including the redemption pipe, the recipient, and the USDC balance at the time of the request. Once the redemption is fulfilled and USDC has arrived back in the Cash Account, the keeper can sweep the fulfilled USDC to the intended HyperCore recipient. This prevents overlapping pending redemptions for the same Cash Account and gives the system a clearer accounting model for delayed withdrawals. ### Bridging and HyperCore Routing For Liminal Cash, bridging does not mean bridging a transferable Liminal Cash token across chains. The main bridge-like action is the routing of redeemed USDC between HyperEVM and HyperCore. After redemption, USDC can be deposited into HyperCore using Circle’s CoreDepositWallet integration. The Cash Account approves the CoreDepositWallet only for the exact USDC amount being routed, calls the deposit flow, and then resets the approval. This keeps the routing narrow and avoids leaving open-ended token approvals. From the user or integrator perspective, the result is that productive USDC can be returned to the user’s HyperCore destination when needed. # Security and Risk Considerations Liminal Cash is designed to make idle USDC productive while keeping user positions separated through dedicated Cash Accounts. However, it still depends on smart contracts, keeper execution, xLEND, and the underlying redemption infrastructure. Integrators should understand the main security properties and risks before using it. ### Per-User Account Isolation Each depositor has their own Cash Account. The account is deployed deterministically from the user address and the xLEND share token. This means a user’s xLEND shares are held in a dedicated smart-contract account rather than being merged into one application-wide treasury balance. This is the main reason Liminal Cash can support a self-custodial account model. The productive position sits in a user-specific on-chain account, not in an opaque off-chain ledger or a pooled app wallet. ### Non-Custodial Execution Model The Liminal Cash keeper triggers approved actions, but it is not meant to custody redeemed USDC. When a redemption is executed, the Cash Account receives the redeemed USDC and routes it through the configured HyperCore deposit flow. The keeper pays gas and coordinates execution, but the flow is designed so the keeper does not receive the user’s assets. That said, the keeper is still an important operational component. Liminal Cash should be described as self-custodial through its account architecture, with keeper-based execution for redemptions. ### Approved Assets and Redemption Pipes The factory controls which share tokens and redemption pipes are approved. A Cash Account cannot freely redeem through any contract. It checks with the factory before using a share token or redemption pipe. This reduces integration risk by narrowing the set of contracts that can interact with user positions. The factory can approve or revoke: * Supported share tokens such as xLEND * Redemption pipes * The keeper address * USDC configuration * CoreDepositWallet configuration ### Pause Controls The system includes pause controls. If an issue is detected, authorized pausable admins can pause the factory. When paused, Cash Account redemption actions are blocked. This gives Liminal and integrators an emergency response mechanism in case of unexpected behavior, integration issues, or external risk. ### Smart Contract Risk Liminal Cash relies on smart contracts for account deployment, share custody, redemption requests, and USDC routing. As with any on-chain system, there is smart contract risk. Bugs in the Cash Account, factory, redemption pipes, xLEND contracts, token contracts, or external dependencies could affect user funds or delay withdrawals. Audits, testing, limited approvals, and monitoring reduce this risk, but they do not eliminate it completely. ### xLEND Risk Liminal Cash uses xLEND as its underlying yield source. This means Liminal Cash inherits the risks of xLEND, including strategy risk, smart contract risk, liquidity risk, oracle/accounting risk, and any risks connected to the underlying lending markets or assets used by xLEND. Liminal Cash does not guarantee yield. The productive balance depends on xLEND’s performance and redemption conditions. ### Redemption Liquidity Risk Redemptions depend on available liquidity and the behavior of the underlying xLEND redemption process. Instant redemption may only be available when sufficient liquidity exists. Standard redemption may require waiting for the underlying position to unwind or settle. During periods of market stress, high withdrawal demand, or infrastructure issues, redemptions may take longer than expected. Integrators should make this clear in their user interface. ### HyperCore and External Infrastructure Risk Liminal Cash can route redeemed USDC to HyperCore through the configured CoreDepositWallet flow. This introduces dependency on external infrastructure, including HyperEVM, HyperCore, USDC contracts, Circle-related deposit infrastructure, and any chain-level systems involved in the route. If one of these systems is delayed, paused, congested, or unavailable, users may experience delayed access to redeemed USDC. ### Admin and Configuration Risk The factory has privileged roles for configuration. Admins can update key system parameters such as approved tokens, approved redemption pipes and keeper address. These controls are necessary for maintaining and securing the system. # Brand kit {% file src="/files/3xka2adu7XC0Xih2Hwtm" %} {% file src="/files/gKy8dgAxbJwAZzpqm8Dz" %} {% file src="/files/Uh2wEG3CC9AeGdv8pMMb" %} {% file src="/files/XitBkASze8evsuFLZXxw" %} {% file src="/files/4bNAqxdnp0EhWH9k2UdA" %} {% file src="/files/AAo4E5LQUSk3q3UmkjYo" %} {% file src="/files/H5zRTUmMlT9WFxaa7Zxd" %} {% file src="/files/etRbtAH0GLH7tyPbrftH" %} {% file src="/files/H1qRhcAVCOFTXp7VtMKE" %} {% file src="/files/e33uB9uKdQvk179BeHp2" %} {% file src="/files/bESMzHPh7wRwpLwC0EM0" %} # Audits Independent security audits of the xTokens smart contracts powering Liminal’s tokenized products. {% file src="/files/CsRvrPqnWtITKNvnjHzF" %} Security audit conducted by Spearbit {% endfile %} {% file src="/files/cFHfCIKmCGGMyZ6OpCvJ" %} Security audit conducted by **Pashov** {% endfile %} *All reports are publicly verifiable and available for download.* # Support ## How to contact support > **TL;DR** – All support is handled in our Discord.\ > 👉 [Join the Liminal Discord](https://discord.com/invite/liminalmoney) → **#✅・verify** (verification) → **#🎫・open-a-ticket** (create ticket). ### Why we use Discord tickets * **Privacy.** Each ticket creates a **dedicated private channel** accessible only by you and authorized Liminal team members. * **Real-time chat.** Screenshots, TX-hashes, and quick follow-ups are easier in Discord than over email. * **Single source of truth.** All protocol and community updates already happen in the server, so you never miss context. ### Step-by-step: join, verify, open a ticket * **Join** our Discord * Go to **#✅・verify** and complete verification * Navigate to **#🎫・open-a-ticket** * Click **“🔖 Open Ticket”** * **Select the category** that best matches your request: * 💸 **Deposit / Withdrawal** — issues related to deposits or withdrawals * ⚙️ **Technical Support** — app or display errors * 💬 **General Inquiry** — questions not covered elsewhere * 📣 **Feedback** — share thoughts or feature requests * Describe your issue in detail — include screenshots, transaction hashes, or any relevant context. ### Beware of Scams Liminal team members will **never** DM you first or ask for your private keys, passwords, or seed phrases.\ If someone contacts you outside of an official **Discord ticket**, it’s **not** a verified support channel.\ All legitimate communication with the team happens **only through private tickets** created in the Discord. ### When should I contact support? | Category | Typical examples | | ------------------------------- | -------------------------------------------------------------- | | **Technical / UI bugs** | Dashboard not loading, stats out of sync etc. | | **Deposits & withdrawals** | Pending/failed transfers, bridge errors, incorrect amounts | | **Strategy performance** | Yield calculations, APR discrepancies, unexpected PnL swings | | **Account & access** | Referral issues, wallet issues | | **Self-Custody mode** | Agent authorisation, sub-account setup, self-custody questions | | **Security concerns** | Suspicious on-chain activity | | **Feedback & feature requests** | UX improvements, new strategy ideas, integrations | | **Anything else** | If it doesn’t fit a box, just open a ticket | # Fees Liminal operates with a **simple, transparent fee model**. Fees apply only to performance, execution, and cross-chain interactions. **In summary:** * **Customized:** 10% performance fees on gross funding & 1bp builder fee. * **Tokenized xTokens:** 10% performance fee on profits and 1% management fee. * **Tokenized limUSD:** 10% performance fees on profits at the limUSD level, in addition to the underlying xTokens’ fees. **Customized product: Performance & Builder Fees** * **Performance Fee:** 10% on gross funding profits, charged only when your strategy is profitable after execution costs (trading fees, spreads, etc.). * **Builder Fee:** 1 basis point per transaction, covering operational overhead. **Deposit & Withdrawal Fees** Deposits and withdrawals for Liminal Customized (on Hyperliquid and Arbitrum) are free of protocol fees. Cross-chain deposits and withdrawals via deBridge, from Ethereum, Base, HyperEVM, or BNB Chain, incur a fixed 0.04% deBridge fee and a 0.02% Liminal fee. **Trading & Execution Costs on Hyperliquid** All execution (funding optimization, rebalancing, etc.) for Liminal Customized strategies is handled automatically by Liminal’s engine. All strategies run on Hyperliquid and follow its native fee structure: * Based on 14-day trading volume and tier. * Taker fees typically range from **0.045%** (base) to **0.024%** (high-volume). * Maker rebates apply for large maker volumes. * These fees are paid directly to **Hyperliquid**, not to Liminal. # Referral Earn a performance-based commission while helping grow the Liminal ecosystem. Refer new users and receive up to 30% of the fees they generate, paid in USDC. Important: For now, the referral program only applies to our Customized product. Tokenized strategies are not included at this time. **1. Tier Structure** | **Tier** | **Your Liminal Balance (USDC)** | **Revenue Share** | | --------------- | ------------------------------- | ----------------- | | 🪵 **Wood** | $0 – $999 | **5 %** | | 🟤 **Bronze** | $1,000 – $9,999 | **10 %** | | ⚪️ **Silver** | $10,000 – $49,999 | **15 %** | | 🟡 **Gold** | $50,000 – $99,999 | **18 %** | | 🪩 **Platinum** | $100,000 – $499,999 | **22 %** | | 💎 **Diamond** | $500,000 – $999,999 | **26 %** | | ⚡ **Hyper** | ≥ $1,000,000 or ≥ 1 Hypurr NFT | **30 %** *(max)* | *The percentage applied to a commission is the tier you hold at the exact moment your referral incurs an eligible fee.* Important: Your **tier level** is determined **only** by the total balance deposited in **Liminal Customized strategies**. Deposits in **Tokenized strategies** are **not included** when calculating tiers or unlocking higher revenue shares. **2. Eligible Fees** Only fees **charged through builder codes by Liminal** qualify for revenue sharing: * **10 % performance fee** (or 5% if you hold a Hypurr NFT) * **1 bp builder fee** Network charges, bridge costs and third-party trading fees are excluded. Important: Referral commissions are earned **only** on fees from **Customized strategies**. Tokenized strategies currently do **not** generate referral rewards. *Note: Liminal does not charge performance fees when funding is negative. Fees resume only once cumulative positive funding has offset prior negative periods, ensuring users are charged exclusively on net positive performance.* *Performance fees are only applied if your overall portfolio is in profit, after deducting all execution-related costs, including Hyperliquid trading fees, builder fees, spread, and slippage.* **3. Accrual and Settlement** * **Daily accrual:** estimated earnings refresh every 24 hours based on referred users’ qualifying fees. * **Weekly settlement:** a claimable USDC balance is calculated once each week. Select **Claim** to transfer the amount to your primary wallet. * **Claim conditions:** the claimable pool unlocks when it reaches 10 USDC. Each claim transaction carries a flat 1 USDC fee (clearing-house constraint imposed by Hyperliquid). **4. How to Participate** 1. Open **liminal.money/referrals** or choose *Referrals* in the menu. 2. Create your unique referral code, then copy your custom link. 3. Share it on social platforms, in private messages or embed it in content. 4. Track sign-ups, balances and earnings in your referral dashboard. Activation condition: to create a referral link and start earning, you must already hold an active Liminal Customized balance (any tier, even Wood). Deposit first, then generate your code. **5. Illustrative Earnings** | **Scenario** | **Your tier at fee time** | **Eligible fees paid** | **Your share** | | -------------------------------------------------------------------------------- | ------------------------- | ---------------------- | --------------- | | Jeff refers one friend who pays 100 USDC in performance fees | Wood (5 %) | 100 USDC | **5 USDC** | | Ben reaches Bronze; five referred users together pay 1 000 USDC in eligible fees | Bronze (10 %) | 1 000 USDC | **100 USDC** | | Clara is Diamond; her network pays 50 000 USDC over the week | Diamond (30 %) | 50 000 USDC | **15 000 USDC** | **6. Legacy Invitations (Pre-Epoch 1)** All users who joined Liminal before *Epoch 1* registered via an invitation code. The creator of that code is automatically recorded as their affiliate. No eligible fees were charged before *Epoch 1*; therefore, no commissions could accrue earlier. From the first block of *Epoch 1* onward, every performance or builder fee paid by those referred users is tracked daily and earmarked for the affiliate, even if the affiliate has not yet created a unique referral code. To unlock and claim the accumulated commissions, the affiliate must create their unique referral code in **liminal.money/referrals**. Once the referral code exists, the full amount accrued since the beginning of *Epoch 1* becomes claimable, subject to the 10 USDC pool threshold and the 1 USDC claim fee (Hyperliquid constraint). **7. Exclusive Benefit for Hypurr NFT Holders** Holders of a Hypurr NFT automatically qualify for the highest tier of the referral program, granting them 30% revenue sharing as soon as they have made a deposit on Liminal. No additional action is required, simply holding a Hypurr NFT is enough to unlock this benefit. **8. Frequently Asked Questions** **How do I refer someone to Liminal?** Create your personal referral code on liminal.money/referrals after making a deposit. Share the code directly or distribute a unique link of the form liminal.money/join/YOURCODE. Each time a referred user pays an eligible fee, you receive the percentage associated with your current tier. Commissions accrue in real time and become claimable weekly in USDC. **How do I use a referral code?** Simply click on any referral link. This action permanently links your account to the inviter. Liminal does not currently offer a fee discount to the referred user; instead, the inviter receives a commission on Liminal’s performance and builder fees. If you later wish to earn commissions yourself, you must first create your own code on the referrals page. **Does the referral program work for Tokenized strategies?** Not yet. At this time, referral rewards apply only to deposits in Customized strategies. If support is added for Tokenized strategies in the future, we’ll announce it. **When does my tier change?** The moment your aggregate balance crosses a threshold. Subsequent fees use the new percentage; earlier commissions remain unchanged. **Do Tokenized deposits count toward my referral tier?** **No.** Your tier level and revenue share are calculated **only** based on your **Liminal Customized balance**. Deposits into Tokenized strategies do **not** increase your tier or affect your referral earnings. **How often can I claim earnings?** The claimable pool refreshes weekly. Claim as soon as the balance reaches 10 USDC