@sodax/dapp-kit 2.0.0-rc.11 → 2.0.0-rc.12

package/README.md

@@ -10,7 +10,7 @@ High-level React hooks library for dApp developers. Wraps `@sodax/sdk` with Reac
 - **Staking** — `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, approval hooks, info/config/ratio queries
 - **DEX** — `useDexDeposit`, `useDexWithdraw`, `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards`, pool/position queries, param builders
 - **Migration** — `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, `useMigrationApprove`, `useMigrationAllowance`
-- **Bitcoin (Radfi)** — `useRadfiAuth`, `useRadfiSession`, `useTradingWallet`, `useTradingWalletBalance`, `useBitcoinBalance`, `useFundTradingWallet`, `useRadfiWithdraw`, `useExpiredUtxos`, `useRenewUtxos`
+- **Bitcoin (Bound Exchange)** — `useRadfiAuth`, `useRadfiSession`, `useTradingWallet`, `useTradingWalletBalance`, `useBitcoinBalance`, `useFundTradingWallet`, `useRadfiWithdraw`, `useExpiredUtxos`, `useRenewUtxos`
 - **Partner** — `useFetchAssetsBalances`, `useGetAutoSwapPreferences`, `useIsTokenApproved`, `useApproveToken`, `useSetSwapPreference`, `useFeeClaimSwap`
 - **Recovery** — `useHubAssetBalances`, `useWithdrawHubAsset`
 - **Backend Queries** — Intent tracking, orderbook, money market position queries
@@ -213,13 +213,13 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 - [`useMigrationApprove()`](src/hooks/migrate/useMigrationApprove.ts) — Approve token spending before migration
 - [`useMigrationAllowance()`](src/hooks/migrate/useMigrationAllowance.ts) — Check if approval is needed
 
-### Bitcoin (Radfi) Hooks
+### Bitcoin (Bound Exchange) Hooks
 
-- [`useRadfiSession()`](src/hooks/bitcoin/useRadfiSession.ts) — Manage Radfi session (login, auto-refresh)
-- [`useRadfiAuth()`](src/hooks/bitcoin/useRadfiAuth.ts) — Authenticate with Radfi via BIP322 signing
+- [`useRadfiSession()`](src/hooks/bitcoin/useRadfiSession.ts) — Manage Bound Exchange session (login, auto-refresh)
+- [`useRadfiAuth()`](src/hooks/bitcoin/useRadfiAuth.ts) — Authenticate with Bound Exchange via BIP322 signing
 - [`useTradingWallet()`](src/hooks/bitcoin/useTradingWallet.ts) — Get trading wallet address from persisted session
 - [`useBitcoinBalance()`](src/hooks/bitcoin/useBitcoinBalance.ts) — BTC balance for any address
-- [`useTradingWalletBalance()`](src/hooks/bitcoin/useTradingWalletBalance.ts) — Trading wallet balance from Radfi API
+- [`useTradingWalletBalance()`](src/hooks/bitcoin/useTradingWalletBalance.ts) — Trading wallet balance from Bound Exchange API
 - [`useFundTradingWallet()`](src/hooks/bitcoin/useFundTradingWallet.ts) — Fund trading wallet from personal wallet
 - [`useRadfiWithdraw()`](src/hooks/bitcoin/useRadfiWithdraw.ts) — Withdraw from trading wallet
 - [`useExpiredUtxos()`](src/hooks/bitcoin/useExpiredUtxos.ts) — Fetch expired UTXOs (polls every 60s)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { UseMutationOptions, UseQueryOptions, UseMutationResult, MutateOptions, UseQueryResult, QueryClientConfig, QueryClient } from '@tanstack/react-query';
-import { Result, Sodax, SpokeChainKey, GetEstimateGasReturnType, EstimateGasParams, IStellarWalletProvider, StellarChainKey, IXServiceBase, XToken, EvmHubProvider, IBitcoinWalletProvider, RadfiWalletBalance, RadfiUtxo, MoneyMarketBorrowActionParams, TxHashPair, MoneyMarketRepayActionParams, MoneyMarketSupplyActionParams, MoneyMarketWithdrawActionParams, UserReserveData, AggregatedReserveData, BaseCurrencyInfo, ReservesDataHumanized, Address as Address$1, MoneyMarketParams, MoneyMarketApproveActionParams, TxReturnType, Erc20Token, ChainKey, ReserveDataHumanized, FormatReserveUSDResponse, FormatUserSummaryResponse, SolverIntentQuoteResponse, SolverErrorResponse, SolverIntentQuoteRequest, SwapActionParams, SwapResponse, SolverIntentStatusResponse, Hex, CreateIntentParams, CreateLimitOrderParams, GetWalletProviderType, Intent, LimitOrderActionParams, IntentResponse, UserIntentsResponse, SubmitSwapTxResponse, SubmitSwapTxRequest, RequestOverrideConfig, SubmitSwapTxStatusResponse, OrderbookResponse, MoneyMarketPosition, MoneyMarketAsset, MoneyMarketAssetBorrowers, MoneyMarketAssetSuppliers, MoneyMarketBorrowers, BridgeParams, CreateBridgeIntentParams, BridgeLimit, StakeAction, StakeParams, UnstakeAction, ClaimAction, CancelUnstakeAction, StakingInfo, UnstakingInfo, UnstakeRequestWithPenalty, StakingConfig, InstantUnstakeAction, UnstakeParams, InstantUnstakeParams, PartnerFeeClaimAssetBalance, AutoSwapPreferences, FeeTokenApproveParams, FeeTokenApproveAction, HubChainKey, SetSwapPreferenceAction, PartnerFeeClaimSwapAction, IntentAutoSwapResult, HubAssetBalance, WithdrawHubAssetAction, IcxMigrateAction, IcxRevertMigrationAction, UnifiedBnUSDMigrateAction, BalnMigrateAction, MigrationAction, IcxMigrateParams, IcxCreateRevertMigrationParams, UnifiedBnUSDMigrateParams, BalnMigrateParams, PoolKey, PoolData, ClPositionInfo, AssetDepositAction, AssetWithdrawAction, CreateAssetDepositParams, ClSupplyParams, ClIncreaseLiquidityParams, ClLiquidityDecreaseLiquidityAction, ClDecreaseLiquidityParams, CreateAssetWithdrawParams, PoolSpokeAssets, DestinationParamsType, ClLiquidityClaimRewardsAction, DeepPartial, SodaxConfig } from '@sodax/sdk';
+import { Result, Sodax, SpokeChainKey, GetEstimateGasReturnType, EstimateGasParams, IStellarWalletProvider, StellarChainKey, INearWalletProvider, GetWalletProviderType, IXServiceBase, XToken, EvmHubProvider, IBitcoinWalletProvider, RadfiWalletBalance, RadfiUtxo, MoneyMarketBorrowActionParams, TxHashPair, MoneyMarketRepayActionParams, MoneyMarketSupplyActionParams, MoneyMarketWithdrawActionParams, UserReserveData, AggregatedReserveData, BaseCurrencyInfo, ReservesDataHumanized, Address as Address$1, MoneyMarketParams, MoneyMarketApproveActionParams, TxReturnType, Erc20Token, ChainKey, ReserveDataHumanized, FormatReserveUSDResponse, FormatUserSummaryResponse, SolverIntentQuoteResponse, SolverErrorResponse, SolverIntentQuoteRequest, SwapActionParams, SwapResponse, SolverIntentStatusResponse, Hex, CreateIntentParams, CreateLimitOrderParams, Intent, LimitOrderActionParams, IntentResponse, UserIntentsResponse, SubmitSwapTxResponse, SubmitSwapTxRequest, RequestOverrideConfig, SubmitSwapTxStatusResponse, OrderbookResponse, MoneyMarketPosition, MoneyMarketAsset, MoneyMarketAssetBorrowers, MoneyMarketAssetSuppliers, MoneyMarketBorrowers, BridgeParams, CreateBridgeIntentParams, BridgeLimit, StakeAction, StakeParams, UnstakeAction, ClaimAction, CancelUnstakeAction, StakingInfo, UnstakingInfo, UnstakeRequestWithPenalty, StakingConfig, InstantUnstakeAction, UnstakeParams, InstantUnstakeParams, PartnerFeeClaimAssetBalance, AutoSwapPreferences, FeeTokenApproveParams, FeeTokenApproveAction, HubChainKey, SetSwapPreferenceAction, PartnerFeeClaimSwapAction, IntentAutoSwapResult, HubAssetBalance, WithdrawHubAssetAction, IcxMigrateAction, IcxRevertMigrationAction, UnifiedBnUSDMigrateAction, BalnMigrateAction, MigrationAction, IcxMigrateParams, IcxCreateRevertMigrationParams, UnifiedBnUSDMigrateParams, BalnMigrateParams, PoolKey, PoolData, ClPositionInfo, AssetDepositAction, AssetWithdrawAction, CreateAssetDepositParams, ClSupplyParams, ClIncreaseLiquidityParams, ClLiquidityDecreaseLiquidityAction, ClDecreaseLiquidityParams, CreateAssetWithdrawParams, PoolSpokeAssets, DestinationParamsType, ClLiquidityClaimRewardsAction, SodaxOptions } from '@sodax/sdk';
 export * from '@sodax/sdk';
 import { Address } from 'viem';
 import { ReactNode, ReactElement } from 'react';
@@ -151,6 +151,72 @@ declare function useRequestTrustline(token: string | undefined): {
     data: string | null;
 };
 
+type UseNearStorageCheckParams = ReadHookParams<boolean, {
+    token: string | undefined;
+    accountId: string | undefined;
+    chainId: SpokeChainKey | undefined;
+}>;
+/**
+ * Whether `accountId` is NEP-141 storage-registered for `token` on NEAR — the receive-side
+ * prerequisite for any leg that delivers a token to the user on NEAR (swap output on NEAR, bridge
+ * into NEAR, money-market borrow/withdraw to NEAR). NEAR's analogue of a Stellar trustline.
+ *
+ * Returns `true` (no gate) when `chainId` is not NEAR, mirroring how the Stellar trustline check
+ * short-circuits off-chain. Native NEAR is not a NEP-141 token, so the SDK reports it as registered.
+ *
+ * Pair with {@link useRegisterNearStorage} to perform the one-time `storage_deposit` when this
+ * resolves to `false`.
+ */
+declare function useNearStorageCheck({ params, queryOptions, }?: UseNearStorageCheckParams): UseQueryResult<boolean, Error>;
+
+type UseRegisterNearStorageVars = {
+    token: string;
+    accountId: string;
+    walletProvider: INearWalletProvider;
+    /** Storage bond override; defaults to the SDK's `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR). */
+    deposit?: bigint;
+};
+/**
+ * Submit a NEP-141 `storage_deposit` so `accountId` can receive `token` on NEAR. NEAR's analogue of
+ * requesting a Stellar trustline; pair with {@link useNearStorageCheck} and call this when the check
+ * resolves to `false`. The recipient's NEAR wallet signs the registration tx.
+ *
+ * Pure mutation: pass `{ token, accountId, walletProvider }` to `mutate(...)`. The hook itself only
+ * takes the structural `mutationOptions` slot. `registerStorage` throws natively (no `Result<T>`),
+ * so this hook is registered as `nativeThrow` in the mutation contract. On success it invalidates
+ * the matching {@link useNearStorageCheck} query.
+ */
+declare function useRegisterNearStorage({ mutationOptions, }?: MutationHookParams<string, UseRegisterNearStorageVars>): SafeUseMutationResult<string, Error, UseRegisterNearStorageVars>;
+
+interface UseNearStorageGateParams {
+    /** Destination chain the token is delivered on. */
+    dstChainKey: SpokeChainKey;
+    /** Destination token address the recipient must be registered for. */
+    token: string | undefined;
+    /** Recipient NEAR account id. */
+    accountId: string | undefined;
+    /** Destination wallet provider; only consumed when it is the NEAR provider. */
+    walletProvider: GetWalletProviderType<SpokeChainKey> | undefined;
+}
+interface NearStorageGate {
+    /** Destination is NEAR. */
+    isNear: boolean;
+    /** Destination is NEAR and the recipient is not yet storage-registered for `token`. */
+    needsRegistration: boolean;
+    /** The downstream action must stay disabled while the gate is unresolved or unmet. */
+    blocksAction: boolean;
+    /** The registration-status query is actively fetching. */
+    isChecking: boolean;
+    /** A `storage_deposit` tx is in flight. */
+    isRegistering: boolean;
+    /** Submit the `storage_deposit`; resolves to the SDK `Result` or `undefined` if inputs are missing. */
+    registerStorage: () => Promise<Result<string> | undefined>;
+}
+/**
+ * NEP-141 storage-registration gate for flows that deliver a token to a user on NEAR.
+ */
+declare function useNearStorageGate({ dstChainKey, token, accountId, walletProvider, }: UseNearStorageGateParams): NearStorageGate;
+
 type UseGetUserHubWalletAddressParams = ReadHookParams<Address, {
     spokeChainId?: SpokeChainKey;
     spokeAddress?: string;
@@ -228,7 +294,7 @@ declare function saveRadfiSession(address: string, session: RadfiSession): void;
 declare function loadRadfiSession(address: string): RadfiSession | null;
 declare function clearRadfiSession(address: string): void;
 /**
- * React hook for authenticating with Radfi via BIP322-signed message. Pure mutation: pass
+ * React hook for authenticating with Bound Exchange via BIP322-signed message. Pure mutation: pass
  * `{ walletProvider }` to `mutate({...})`. The hook itself takes no arguments other than the
  * structural `mutationOptions` slot.
  */
@@ -248,7 +314,7 @@ type UseFundTradingWalletVars = {
     walletProvider: IBitcoinWalletProvider;
 };
 /**
- * React hook for funding the user's Radfi trading wallet from their personal Bitcoin wallet.
+ * React hook for funding the user's Bound Exchange trading wallet from their personal Bitcoin wallet.
  * Pure mutation: pass `{ amount, walletProvider }` to `mutate({...})`. Returns the broadcast tx
  * id on success.
  */
@@ -271,7 +337,7 @@ type UseTradingWalletReturn = {
     tradingAddress: string | undefined;
 };
 /**
- * Returns the Radfi trading wallet address from the persisted session.
+ * Returns the Bound Exchange trading wallet address from the persisted session.
  * Trading wallet is created automatically during authentication — no API call needed.
  */
 declare function useTradingWallet(walletAddress: string | undefined): UseTradingWalletReturn;
@@ -293,7 +359,7 @@ type UseRenewUtxosVars = {
     walletProvider: IBitcoinWalletProvider;
 };
 /**
- * React hook for renewing expired UTXOs in the user's Radfi trading wallet. Pure mutation: pass
+ * React hook for renewing expired UTXOs in the user's Bound Exchange trading wallet. Pure mutation: pass
  * `{ txIdVouts, walletProvider }` to `mutate({...})`.
  */
 declare function useRenewUtxos({ mutationOptions, }?: MutationHookParams<string, UseRenewUtxosVars>): SafeUseMutationResult<string, Error, UseRenewUtxosVars>;
@@ -309,7 +375,7 @@ type WithdrawResult = {
     fee: number;
 };
 /**
- * React hook for withdrawing BTC from the user's Radfi trading wallet back to their personal
+ * React hook for withdrawing BTC from the user's Bound Exchange trading wallet back to their personal
  * Bitcoin wallet. Pure mutation: pass all inputs (including the wallet provider) to
  * `mutate({...})`.
  */
@@ -1489,7 +1555,7 @@ interface SodaxProviderProps {
      * <SodaxProvider config={config}>...</SodaxProvider>
      * ```
      */
-    config?: DeepPartial<SodaxConfig>;
+    config?: SodaxOptions;
 }
 /** Root provider for `@sodax/dapp-kit`. Must be paired with `QueryClientProvider`. */
 declare const SodaxProvider: ({ children, config }: SodaxProviderProps) => ReactElement;
@@ -1554,4 +1620,30 @@ type CreateSodaxQueryClientOptions = {
  */
 declare function createSodaxQueryClient({ onMutationError, config, }?: CreateSodaxQueryClientOptions): QueryClient;
 
-export { type ATokenData, type BackendPaginationParams, type CreateSodaxQueryClientOptions, type DecreaseLiquidityParamsCore, type DepositParamsCore, type MutationHookOptions, type MutationHookParams, type RadfiSession, type ReadHookParams, type ReadQueryOptions, type ReserveUsdFormat, type SafeUseMutationResult, SodaxProvider, type UseATokenParams, type UseATokensBalancesParams, type UseApproveTokenVars, type UseBitcoinBalanceParams, type UseBorrowVars, type UseBridgeAllowanceParams, type UseBridgeApproveVars, type UseBridgeVars, type UseClaimRewardsVars, type UseCreateDecreaseLiquidityParamsProps, type UseCreateDepositParamsProps, type UseCreateLimitOrderVars, type UseCreateSupplyLiquidityParamsProps, type UseCreateSupplyLiquidityParamsResult, type UseCreateWithdrawParamsProps, type UseDecreaseLiquidityVars, type UseDeriveUserWalletAddressParams, type UseDexAllowanceParams, type UseDexApproveVars, type UseDexDepositVars, type UseDexWithdrawVars, type UseExpiredUtxosParams, type UseFeeClaimSwapVars, type UseFetchAssetsBalancesParams, type UseFundTradingWalletVars, type UseGetAutoSwapPreferencesParams, type UseGetBridgeableAmountParams, type UseGetBridgeableTokensParams, type UseGetUserHubWalletAddressParams, type UseHubAssetBalancesParams, type UseIsTokenApprovedParams, type UseLiquidityAmountsResult, type UseMMAllowanceParams, type UseMMApproveVars, type UseMigrateBalnVars, type UseMigrateIcxToSodaVars, type UseMigratebnUSDVars, type UseMigrationAllowanceInputs, type UseMigrationAllowanceParams, type UseMigrationApproveVars, type UsePoolBalancesParams, type UsePoolBalancesResponse, type UsePoolDataParams, type UsePoolsParams, type UsePositionInfoParams, type UsePositionInfoResponse, type UseQuoteParams, type UseRadfiAuthVars, type UseRadfiSessionReturn, type UseRadfiWithdrawVars, type UseRenewUtxosVars, type UseRepayVars, type UseReservesDataParams, type UseReservesHumanizedParams, type UseReservesListParams, type UseReservesUsdFormatParams, type UseRevertMigrateSodaToIcxVars, type UseSetSwapPreferenceVars, type UseSetSwapPreferenceVarsHub, type UseStatusParams, type UseStellarTrustlineCheckParams, type UseSupplyLiquidityVars, type UseSupplyVars, type UseSwapAllowanceParams, type UseSwapApproveVars, type UseSwapVars, type UseTradingWalletBalanceParams, type UseUserFormattedSummaryParams, type UseUserReservesDataParams, type UseWithdrawHubAssetVars, type UseWithdrawVars, type UseXBalancesParams, type WithdrawParamsCore, type XBalancesInputs, clearRadfiSession, createDecreaseLiquidityParamsProps, createDepositParamsProps, createSodaxQueryClient, createSupplyLiquidityParamsProps, createWithdrawParamsProps, getXBalancesQueryOptions, loadRadfiSession, saveRadfiSession, toResult, unwrapResult, useAToken, useATokensBalances, useApproveToken, useBackendAllMoneyMarketAssets, useBackendAllMoneyMarketBorrowers, useBackendIntentByHash, useBackendIntentByTxHash, useBackendMoneyMarketAsset, useBackendMoneyMarketAssetBorrowers, useBackendMoneyMarketAssetSuppliers, useBackendMoneyMarketPosition, useBackendOrderbook, useBackendSubmitSwapTx, useBackendSubmitSwapTxStatus, useBackendUserIntents, useBitcoinBalance, useBorrow, useBridge, useBridgeAllowance, useBridgeApprove, useCancelLimitOrder, useCancelSwap, useCancelUnstake, useClaim, useClaimRewards, useConvertedAssets, useCreateDecreaseLiquidityParams, useCreateDepositParams, useCreateLimitOrder, useCreateSupplyLiquidityParams, useCreateWithdrawParams, useDecreaseLiquidity, useDeriveUserWalletAddress, useDexAllowance, useDexApprove, useDexDeposit, useDexWithdraw, useEstimateGas, useExpiredUtxos, useFeeClaimSwap, useFetchAssetsBalances, useFundTradingWallet, useGetAutoSwapPreferences, useGetBridgeableAmount, useGetBridgeableTokens, useGetUserHubWalletAddress, useHubAssetBalances, useHubProvider, useInstantUnstake, useInstantUnstakeAllowance, useInstantUnstakeApprove, useInstantUnstakeRatio, useIsTokenApproved, useLiquidityAmounts, useMMAllowance, useMMApprove, useMigrateBaln, useMigrateIcxToSoda, useMigratebnUSD, useMigrationAllowance, useMigrationApprove, usePoolBalances, usePoolData, usePools, usePositionInfo, useQuote, useRadfiAuth, useRadfiSession, useRadfiWithdraw, useRenewUtxos, useRepay, useRequestTrustline, useReservesData, useReservesHumanized, useReservesList, useReservesUsdFormat, useRevertMigrateSodaToIcx, useSafeMutation, useSetSwapPreference, useSodaxContext, useStake, useStakeAllowance, useStakeApprove, useStakeRatio, useStakingConfig, useStakingInfo, useStatus, useStellarTrustlineCheck, useSupply, useSupplyLiquidity, useSwap, useSwapAllowance, useSwapApprove, useTradingWallet, useTradingWalletBalance, useUnstake, useUnstakeAllowance, useUnstakeApprove, useUnstakingInfo, useUnstakingInfoWithPenalty, useUserFormattedSummary, useUserReservesData, useWithdraw, useWithdrawHubAsset, useXBalances };
+/** The subset of a `useNearStorageCheck` result the gate reads. A full `UseQueryResult<boolean>` satisfies it. */
+type NearStorageCheckResult = Pick<UseQueryResult<boolean>, 'isLoading' | 'data'>;
+/** UI gate state for NEP-141 storage registration on NEAR. */
+interface NearStorageGateState {
+    /** Destination is NEAR — the only chain with a NEP-141 storage-registration prerequisite. */
+    isNear: boolean;
+    /** Show the "register storage" action: the check resolved and the recipient is not registered. */
+    needsRegistration: boolean;
+    /**
+     * Keep the downstream action (swap/bridge/borrow/withdraw) disabled: the NEAR gate is unresolved
+     * (still checking) or unmet (needs registration).
+     */
+    blocksAction: boolean;
+}
+/**
+ * Derives the NEP-141 storage-registration UI gate state for a flow that delivers a token to a user
+ * on NEAR — NEAR's analogue of the Stellar trustline gate. Unwrapped (no hook): pass the destination
+ * `chainKey` and the `useNearStorageCheck` result; the util owns the `=== NEAR` test and reads
+ * `isLoading` (NOT `isPending`, which stays `true` for a disabled query and would block forever).
+ *
+ * `blocksAction` deliberately also covers the in-flight check window so the action can't be
+ * triggered before registration status is known; `needsRegistration` only flips once the check has
+ * resolved (so the "register" button isn't shown speculatively while still checking).
+ */
+declare function resolveNearStorageGate(chainKey: SpokeChainKey, check: NearStorageCheckResult): NearStorageGateState;
+
+export { type ATokenData, type BackendPaginationParams, type CreateSodaxQueryClientOptions, type DecreaseLiquidityParamsCore, type DepositParamsCore, type MutationHookOptions, type MutationHookParams, type NearStorageCheckResult, type NearStorageGateState, type RadfiSession, type ReadHookParams, type ReadQueryOptions, type ReserveUsdFormat, type SafeUseMutationResult, SodaxProvider, type UseATokenParams, type UseATokensBalancesParams, type UseApproveTokenVars, type UseBitcoinBalanceParams, type UseBorrowVars, type UseBridgeAllowanceParams, type UseBridgeApproveVars, type UseBridgeVars, type UseClaimRewardsVars, type UseCreateDecreaseLiquidityParamsProps, type UseCreateDepositParamsProps, type UseCreateLimitOrderVars, type UseCreateSupplyLiquidityParamsProps, type UseCreateSupplyLiquidityParamsResult, type UseCreateWithdrawParamsProps, type UseDecreaseLiquidityVars, type UseDeriveUserWalletAddressParams, type UseDexAllowanceParams, type UseDexApproveVars, type UseDexDepositVars, type UseDexWithdrawVars, type UseExpiredUtxosParams, type UseFeeClaimSwapVars, type UseFetchAssetsBalancesParams, type UseFundTradingWalletVars, type UseGetAutoSwapPreferencesParams, type UseGetBridgeableAmountParams, type UseGetBridgeableTokensParams, type UseGetUserHubWalletAddressParams, type UseHubAssetBalancesParams, type UseIsTokenApprovedParams, type UseLiquidityAmountsResult, type UseMMAllowanceParams, type UseMMApproveVars, type UseMigrateBalnVars, type UseMigrateIcxToSodaVars, type UseMigratebnUSDVars, type UseMigrationAllowanceInputs, type UseMigrationAllowanceParams, type UseMigrationApproveVars, type UseNearStorageCheckParams, type UsePoolBalancesParams, type UsePoolBalancesResponse, type UsePoolDataParams, type UsePoolsParams, type UsePositionInfoParams, type UsePositionInfoResponse, type UseQuoteParams, type UseRadfiAuthVars, type UseRadfiSessionReturn, type UseRadfiWithdrawVars, type UseRegisterNearStorageVars, type UseRenewUtxosVars, type UseRepayVars, type UseReservesDataParams, type UseReservesHumanizedParams, type UseReservesListParams, type UseReservesUsdFormatParams, type UseRevertMigrateSodaToIcxVars, type UseSetSwapPreferenceVars, type UseSetSwapPreferenceVarsHub, type UseStatusParams, type UseStellarTrustlineCheckParams, type UseSupplyLiquidityVars, type UseSupplyVars, type UseSwapAllowanceParams, type UseSwapApproveVars, type UseSwapVars, type UseTradingWalletBalanceParams, type UseUserFormattedSummaryParams, type UseUserReservesDataParams, type UseWithdrawHubAssetVars, type UseWithdrawVars, type UseXBalancesParams, type WithdrawParamsCore, type XBalancesInputs, clearRadfiSession, createDecreaseLiquidityParamsProps, createDepositParamsProps, createSodaxQueryClient, createSupplyLiquidityParamsProps, createWithdrawParamsProps, getXBalancesQueryOptions, loadRadfiSession, resolveNearStorageGate, saveRadfiSession, toResult, unwrapResult, useAToken, useATokensBalances, useApproveToken, useBackendAllMoneyMarketAssets, useBackendAllMoneyMarketBorrowers, useBackendIntentByHash, useBackendIntentByTxHash, useBackendMoneyMarketAsset, useBackendMoneyMarketAssetBorrowers, useBackendMoneyMarketAssetSuppliers, useBackendMoneyMarketPosition, useBackendOrderbook, useBackendSubmitSwapTx, useBackendSubmitSwapTxStatus, useBackendUserIntents, useBitcoinBalance, useBorrow, useBridge, useBridgeAllowance, useBridgeApprove, useCancelLimitOrder, useCancelSwap, useCancelUnstake, useClaim, useClaimRewards, useConvertedAssets, useCreateDecreaseLiquidityParams, useCreateDepositParams, useCreateLimitOrder, useCreateSupplyLiquidityParams, useCreateWithdrawParams, useDecreaseLiquidity, useDeriveUserWalletAddress, useDexAllowance, useDexApprove, useDexDeposit, useDexWithdraw, useEstimateGas, useExpiredUtxos, useFeeClaimSwap, useFetchAssetsBalances, useFundTradingWallet, useGetAutoSwapPreferences, useGetBridgeableAmount, useGetBridgeableTokens, useGetUserHubWalletAddress, useHubAssetBalances, useHubProvider, useInstantUnstake, useInstantUnstakeAllowance, useInstantUnstakeApprove, useInstantUnstakeRatio, useIsTokenApproved, useLiquidityAmounts, useMMAllowance, useMMApprove, useMigrateBaln, useMigrateIcxToSoda, useMigratebnUSD, useMigrationAllowance, useMigrationApprove, useNearStorageCheck, useNearStorageGate, usePoolBalances, usePoolData, usePools, usePositionInfo, useQuote, useRadfiAuth, useRadfiSession, useRadfiWithdraw, useRegisterNearStorage, useRenewUtxos, useRepay, useRequestTrustline, useReservesData, useReservesHumanized, useReservesList, useReservesUsdFormat, useRevertMigrateSodaToIcx, useSafeMutation, useSetSwapPreference, useSodaxContext, useStake, useStakeAllowance, useStakeApprove, useStakeRatio, useStakingConfig, useStakingInfo, useStatus, useStellarTrustlineCheck, useSupply, useSupplyLiquidity, useSwap, useSwapAllowance, useSwapApprove, useTradingWallet, useTradingWalletBalance, useUnstake, useUnstakeAllowance, useUnstakeApprove, useUnstakingInfo, useUnstakingInfoWithPenalty, useUserFormattedSummary, useUserReservesData, useWithdraw, useWithdrawHubAsset, useXBalances };

package/dist/index.mjs

@@ -140,59 +140,76 @@ function useRequestTrustline(token) {
   );
   return { requestTrustline, isLoading, isRequested, error, data };
 }
-function useGetUserHubWalletAddress({
+function useNearStorageCheck({
   params,
   queryOptions
 } = {}) {
   const { sodax } = useSodaxContext();
-  const spokeChainId = params?.spokeChainId;
-  const spokeAddress = params?.spokeAddress;
+  const token = params?.token;
+  const accountId = params?.accountId;
+  const chainId = params?.chainId;
   return useQuery({
-    queryKey: ["shared", "userHubWalletAddress", spokeChainId, spokeAddress],
+    queryKey: ["shared", "nearStorageCheck", chainId, token, accountId],
     queryFn: async () => {
-      if (!spokeChainId || !spokeAddress) {
-        throw new Error("Spoke chain id and address are required");
-      }
-      return await sodax.hubProvider.getUserHubWalletAddress(spokeAddress, spokeChainId);
+      if (chainId !== ChainKeys.NEAR_MAINNET) return true;
+      if (!token || !accountId) return false;
+      return sodax.spoke.near.isStorageRegistered(token, accountId);
     },
-    enabled: !!spokeChainId && !!spokeAddress,
-    refetchInterval: false,
+    enabled: !!token && !!accountId,
     ...queryOptions
   });
 }
-var REFETCH_INTERVAL_MS = 5e3;
-function getXBalancesQueryOptions({ xService, xChainId, xTokens, address }) {
-  return {
-    // Pair symbol + address: readable in devtools, unique on-chain (symbol alone
-    // can collide — e.g. scam tokens copying legitimate ticker).
-    queryKey: ["shared", "xBalances", xChainId, xTokens.map((x) => [x.symbol, x.address]), address],
-    queryFn: async () => {
-      if (!xService) return {};
-      return xService.getBalances(address, xTokens);
-    },
-    enabled: !!xService && !!address && xTokens.length > 0,
-    refetchInterval: REFETCH_INTERVAL_MS
-  };
-}
-function useXBalances({
-  params,
-  queryOptions
+function useRegisterNearStorage({
+  mutationOptions
 } = {}) {
-  return useQuery({
-    ...getXBalancesQueryOptions({
-      xService: params?.xService,
-      xChainId: params?.xChainId,
-      xTokens: params?.xTokens ?? [],
-      address: params?.address
-    }),
-    ...queryOptions
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+  return useSafeMutation({
+    mutationKey: ["shared", "registerNearStorage"],
+    ...mutationOptions,
+    mutationFn: async ({ token, accountId, walletProvider, deposit }) => sodax.spoke.near.registerStorage({ token, accountId, walletProvider, deposit, raw: false }),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ["shared", "nearStorageCheck", ChainKeys.NEAR_MAINNET, vars.token, vars.accountId]
+      });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    }
   });
 }
+function resolveNearStorageGate(chainKey, check) {
+  const isNear = chainKey === ChainKeys.NEAR_MAINNET;
+  const isChecking = check.isLoading;
+  const isRegistered = check.data;
+  return {
+    isNear,
+    needsRegistration: isNear && !isChecking && isRegistered === false,
+    blocksAction: isNear && (isChecking || isRegistered === false)
+  };
+}
 
-// src/hooks/provider/useHubProvider.ts
-function useHubProvider() {
-  const { sodax } = useSodaxContext();
-  return sodax.hubProvider;
+// src/hooks/shared/useNearStorageGate.ts
+function useNearStorageGate({
+  dstChainKey,
+  token,
+  accountId,
+  walletProvider
+}) {
+  const nearWalletProvider = walletProvider?.chainType === "NEAR" ? walletProvider : void 0;
+  const storageCheck = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+  const { mutateAsyncSafe: register, isPending: isRegistering } = useRegisterNearStorage();
+  const { isNear, needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, storageCheck);
+  const registerStorage = async () => {
+    if (!nearWalletProvider || !token || !accountId) return void 0;
+    return register({ token, accountId, walletProvider: nearWalletProvider });
+  };
+  return {
+    isNear,
+    needsRegistration,
+    blocksAction,
+    isChecking: storageCheck.isLoading,
+    isRegistering,
+    registerStorage
+  };
 }
 var SESSION_KEY = (address) => `radfi_session_${address}`;
 function saveRadfiSession(address, session) {
@@ -254,7 +271,7 @@ function useRadfiAuth({
             clearRadfiSession(walletAddress);
           }
           throw new Error(
-            "This wallet is already registered with Radfi from another session. Please clear your browser storage for this site and try again, or wait for the previous session to expire."
+            "This wallet is already registered with Bound Exchange from another session. Please clear your browser storage for this site and try again, or wait for the previous session to expire."
           );
         }
         throw err;
@@ -262,6 +279,71 @@ function useRadfiAuth({
     }
   });
 }
+
+// src/hooks/bitcoin/resolveBtcReadAddress.ts
+function resolveBtcReadAddress(chainKey, address) {
+  if (chainKey !== ChainKeys.BITCOIN_MAINNET) return address;
+  return loadRadfiSession(address)?.tradingAddress ?? address;
+}
+
+// src/hooks/shared/useGetUserHubWalletAddress.ts
+function useGetUserHubWalletAddress({
+  params,
+  queryOptions
+} = {}) {
+  const { sodax } = useSodaxContext();
+  const spokeChainId = params?.spokeChainId;
+  const spokeAddress = params?.spokeAddress;
+  return useQuery({
+    queryKey: ["shared", "userHubWalletAddress", spokeChainId, spokeAddress],
+    queryFn: async () => {
+      if (!spokeChainId || !spokeAddress) {
+        throw new Error("Spoke chain id and address are required");
+      }
+      return await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainId, spokeAddress),
+        spokeChainId
+      );
+    },
+    enabled: !!spokeChainId && !!spokeAddress,
+    refetchInterval: false,
+    ...queryOptions
+  });
+}
+var REFETCH_INTERVAL_MS = 5e3;
+function getXBalancesQueryOptions({ xService, xChainId, xTokens, address }) {
+  return {
+    // Pair symbol + address: readable in devtools, unique on-chain (symbol alone
+    // can collide — e.g. scam tokens copying legitimate ticker).
+    queryKey: ["shared", "xBalances", xChainId, xTokens.map((x) => [x.symbol, x.address]), address],
+    queryFn: async () => {
+      if (!xService) return {};
+      return xService.getBalances(address, xTokens);
+    },
+    enabled: !!xService && !!address && xTokens.length > 0,
+    refetchInterval: REFETCH_INTERVAL_MS
+  };
+}
+function useXBalances({
+  params,
+  queryOptions
+} = {}) {
+  return useQuery({
+    ...getXBalancesQueryOptions({
+      xService: params?.xService,
+      xChainId: params?.xChainId,
+      xTokens: params?.xTokens ?? [],
+      address: params?.address
+    }),
+    ...queryOptions
+  });
+}
+
+// src/hooks/provider/useHubProvider.ts
+function useHubProvider() {
+  const { sodax } = useSodaxContext();
+  return sodax.hubProvider;
+}
 var REFRESH_INTERVAL = 5 * 60 * 1e3;
 function useRadfiSession(walletProvider) {
   const { sodax } = useSodaxContext();
@@ -432,7 +514,7 @@ function useRenewUtxos({
       const session = loadRadfiSession(userAddress);
       const accessToken = session?.accessToken || radfi.accessToken;
       if (!accessToken) {
-        throw new Error("Radfi authentication required. Please login first.");
+        throw new Error("Bound Exchange authentication required. Please login first.");
       }
       const buildResult = await radfi.buildRenewUtxoTransaction({ userAddress, txIdVouts }, accessToken);
       const signedTx = await walletProvider.signTransaction(buildResult.base64Psbt, false);
@@ -460,7 +542,7 @@ function useRadfiWithdraw({
       const session = loadRadfiSession(userAddress);
       const accessToken = session?.accessToken || radfi.accessToken;
       if (!accessToken) {
-        throw new Error("Radfi authentication required. Please login first.");
+        throw new Error("Bound Exchange authentication required. Please login first.");
       }
       const buildResult = await radfi.withdrawToUser({ userAddress, amount, tokenId, withdrawTo }, accessToken);
       const signedTx = await walletProvider.signTransaction(buildResult.base64Psbt, false);
@@ -581,7 +663,10 @@ function useUserReservesData({
       if (!spokeChainKey || !userAddress) {
         throw new Error("spokeChainKey and userAddress are required");
       }
-      return sodax.moneyMarket.data.getUserReservesData(spokeChainKey, userAddress);
+      return sodax.moneyMarket.data.getUserReservesData(
+        spokeChainKey,
+        resolveBtcReadAddress(spokeChainKey, userAddress)
+      );
     },
     enabled: !!spokeChainKey && !!userAddress,
     refetchInterval: 5e3,
@@ -707,7 +792,10 @@ function useATokensBalances({
           throw new Error(`Invalid aToken address: ${aToken}`);
         }
       }
-      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(userAddress, spokeChainKey);
+      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainKey, userAddress),
+        spokeChainKey
+      );
       return sodax.moneyMarket.data.getATokensBalances(aTokens, hubWalletAddress);
     },
     enabled: aTokens.length > 0 && !!spokeChainKey && !!userAddress,
@@ -742,7 +830,10 @@ function useUserFormattedSummary({
       }
       const [reserves, userReserves] = await Promise.all([
         sodax.moneyMarket.data.getReservesHumanized(),
-        sodax.moneyMarket.data.getUserReservesHumanized(spokeChainKey, userAddress)
+        sodax.moneyMarket.data.getUserReservesHumanized(
+          spokeChainKey,
+          resolveBtcReadAddress(spokeChainKey, userAddress)
+        )
       ]);
       const formattedReserves = sodax.moneyMarket.data.formatReservesUSD(
         sodax.moneyMarket.data.buildReserveDataWithPrice(reserves)
@@ -2513,4 +2604,4 @@ function createSodaxQueryClient({
   });
 }
 
-export { SodaxProvider, clearRadfiSession, createDecreaseLiquidityParamsProps, createDepositParamsProps, createSodaxQueryClient, createSupplyLiquidityParamsProps, createWithdrawParamsProps, getXBalancesQueryOptions, loadRadfiSession, saveRadfiSession, toResult, unwrapResult, useAToken, useATokensBalances, useApproveToken, useBackendAllMoneyMarketAssets, useBackendAllMoneyMarketBorrowers, useBackendIntentByHash, useBackendIntentByTxHash, useBackendMoneyMarketAsset, useBackendMoneyMarketAssetBorrowers, useBackendMoneyMarketAssetSuppliers, useBackendMoneyMarketPosition, useBackendOrderbook, useBackendSubmitSwapTx, useBackendSubmitSwapTxStatus, useBackendUserIntents, useBitcoinBalance, useBorrow, useBridge, useBridgeAllowance, useBridgeApprove, useCancelLimitOrder, useCancelSwap, useCancelUnstake, useClaim, useClaimRewards, useConvertedAssets, useCreateDecreaseLiquidityParams, useCreateDepositParams, useCreateLimitOrder, useCreateSupplyLiquidityParams, useCreateWithdrawParams, useDecreaseLiquidity, useDeriveUserWalletAddress, useDexAllowance, useDexApprove, useDexDeposit, useDexWithdraw, useEstimateGas, useExpiredUtxos, useFeeClaimSwap, useFetchAssetsBalances, useFundTradingWallet, useGetAutoSwapPreferences, useGetBridgeableAmount, useGetBridgeableTokens, useGetUserHubWalletAddress, useHubAssetBalances, useHubProvider, useInstantUnstake, useInstantUnstakeAllowance, useInstantUnstakeApprove, useInstantUnstakeRatio, useIsTokenApproved, useLiquidityAmounts, useMMAllowance, useMMApprove, useMigrateBaln, useMigrateIcxToSoda, useMigratebnUSD, useMigrationAllowance, useMigrationApprove, usePoolBalances, usePoolData, usePools, usePositionInfo, useQuote, useRadfiAuth, useRadfiSession, useRadfiWithdraw, useRenewUtxos, useRepay, useRequestTrustline, useReservesData, useReservesHumanized, useReservesList, useReservesUsdFormat, useRevertMigrateSodaToIcx, useSafeMutation, useSetSwapPreference, useSodaxContext, useStake, useStakeAllowance, useStakeApprove, useStakeRatio, useStakingConfig, useStakingInfo, useStatus, useStellarTrustlineCheck, useSupply, useSupplyLiquidity, useSwap, useSwapAllowance, useSwapApprove, useTradingWallet, useTradingWalletBalance, useUnstake, useUnstakeAllowance, useUnstakeApprove, useUnstakingInfo, useUnstakingInfoWithPenalty, useUserFormattedSummary, useUserReservesData, useWithdraw, useWithdrawHubAsset, useXBalances };
+export { SodaxProvider, clearRadfiSession, createDecreaseLiquidityParamsProps, createDepositParamsProps, createSodaxQueryClient, createSupplyLiquidityParamsProps, createWithdrawParamsProps, getXBalancesQueryOptions, loadRadfiSession, resolveNearStorageGate, saveRadfiSession, toResult, unwrapResult, useAToken, useATokensBalances, useApproveToken, useBackendAllMoneyMarketAssets, useBackendAllMoneyMarketBorrowers, useBackendIntentByHash, useBackendIntentByTxHash, useBackendMoneyMarketAsset, useBackendMoneyMarketAssetBorrowers, useBackendMoneyMarketAssetSuppliers, useBackendMoneyMarketPosition, useBackendOrderbook, useBackendSubmitSwapTx, useBackendSubmitSwapTxStatus, useBackendUserIntents, useBitcoinBalance, useBorrow, useBridge, useBridgeAllowance, useBridgeApprove, useCancelLimitOrder, useCancelSwap, useCancelUnstake, useClaim, useClaimRewards, useConvertedAssets, useCreateDecreaseLiquidityParams, useCreateDepositParams, useCreateLimitOrder, useCreateSupplyLiquidityParams, useCreateWithdrawParams, useDecreaseLiquidity, useDeriveUserWalletAddress, useDexAllowance, useDexApprove, useDexDeposit, useDexWithdraw, useEstimateGas, useExpiredUtxos, useFeeClaimSwap, useFetchAssetsBalances, useFundTradingWallet, useGetAutoSwapPreferences, useGetBridgeableAmount, useGetBridgeableTokens, useGetUserHubWalletAddress, useHubAssetBalances, useHubProvider, useInstantUnstake, useInstantUnstakeAllowance, useInstantUnstakeApprove, useInstantUnstakeRatio, useIsTokenApproved, useLiquidityAmounts, useMMAllowance, useMMApprove, useMigrateBaln, useMigrateIcxToSoda, useMigratebnUSD, useMigrationAllowance, useMigrationApprove, useNearStorageCheck, useNearStorageGate, usePoolBalances, usePoolData, usePools, usePositionInfo, useQuote, useRadfiAuth, useRadfiSession, useRadfiWithdraw, useRegisterNearStorage, useRenewUtxos, useRepay, useRequestTrustline, useReservesData, useReservesHumanized, useReservesList, useReservesUsdFormat, useRevertMigrateSodaToIcx, useSafeMutation, useSetSwapPreference, useSodaxContext, useStake, useStakeAllowance, useStakeApprove, useStakeRatio, useStakingConfig, useStakingInfo, useStatus, useStellarTrustlineCheck, useSupply, useSupplyLiquidity, useSwap, useSwapAllowance, useSwapApprove, useTradingWallet, useTradingWalletBalance, useUnstake, useUnstakeAllowance, useUnstakeApprove, useUnstakingInfo, useUnstakingInfoWithPenalty, useUserFormattedSummary, useUserReservesData, useWithdraw, useWithdrawHubAsset, useXBalances };

package/package.json

@@ -5,7 +5,7 @@
     "access": "public"
   },
   "license": "MIT",
-  "version": "2.0.0-rc.11",
+  "version": "2.0.0-rc.12",
   "description": "React hooks for building dApps on the SODAX cross-chain DeFi platform",
   "keywords": [
     "sodax",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "viem": "2.29.2",
-    "@sodax/sdk": "2.0.0-rc.11"
+    "@sodax/sdk": "2.0.0-rc.12"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.17.4",

package/src/hooks/_mutationContract.test.ts

@@ -7,7 +7,7 @@ const HOOKS_DIR = resolve(fileURLToPath(import.meta.url), '..');
 
 /**
  * Manifest of every mutation hook. `nativeThrow: true` marks hooks whose underlying SDK methods
- * throw natively (Radfi APIs) and so don't need `unwrapResult`.
+ * throw natively (Bound Exchange APIs) and so don't need `unwrapResult`.
  *
  * To add a new mutation hook, add its path here. The friction is intentional — it forces explicit
  * registration so the contract is enforced from day one.
@@ -41,6 +41,7 @@ const HOOKS: Array<{ path: string; nativeThrow?: true }> = [
   { path: 'partner/useSetSwapPreference.ts' },
   { path: 'recovery/useWithdrawHubAsset.ts' },
   { path: 'shared/useEstimateGas.ts' },
+  { path: 'shared/useRegisterNearStorage.ts', nativeThrow: true },
   { path: 'staking/useCancelUnstake.ts' },
   { path: 'staking/useClaim.ts' },
   { path: 'staking/useInstantUnstake.ts' },

package/src/hooks/bitcoin/resolveBtcReadAddress.test.ts

@@ -0,0 +1,54 @@
+import { ChainKeys } from '@sodax/sdk';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { RadfiSession } from './useRadfiAuth.js';
+import { loadRadfiSession } from './useRadfiAuth.js';
+import { resolveBtcReadAddress } from './resolveBtcReadAddress.js';
+
+// resolveBtcReadAddress reads the Bound Exchange session via loadRadfiSession (localStorage-backed).
+// The dapp-kit test env is `node` (no localStorage), so mock the session lookup to drive each branch.
+vi.mock('./useRadfiAuth.js', () => ({
+  loadRadfiSession: vi.fn(),
+}));
+
+const mockLoadRadfiSession = vi.mocked(loadRadfiSession);
+
+const PERSONAL_ADDRESS = 'bc1qpersonal00000000000000000000000000000';
+const TRADING_ADDRESS = 'bc1qtrading000000000000000000000000000000';
+
+const session = (tradingAddress: string): RadfiSession => ({
+  accessToken: 'access',
+  refreshToken: 'refresh',
+  tradingAddress,
+  publicKey: 'pub',
+});
+
+describe('resolveBtcReadAddress', () => {
+  beforeEach(() => {
+    mockLoadRadfiSession.mockReset();
+  });
+
+  it('passes the address through unchanged for non-Bitcoin chains (no session lookup)', () => {
+    const result = resolveBtcReadAddress(ChainKeys.ARBITRUM_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(PERSONAL_ADDRESS);
+    expect(mockLoadRadfiSession).not.toHaveBeenCalled();
+  });
+
+  it('returns the trading address from the local session for Bitcoin', () => {
+    mockLoadRadfiSession.mockReturnValue(session(TRADING_ADDRESS));
+
+    const result = resolveBtcReadAddress(ChainKeys.BITCOIN_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(TRADING_ADDRESS);
+    // The session is keyed by the personal address.
+    expect(mockLoadRadfiSession).toHaveBeenCalledWith(PERSONAL_ADDRESS);
+  });
+
+  it('falls back to the personal address for Bitcoin when there is no session', () => {
+    mockLoadRadfiSession.mockReturnValue(null);
+
+    const result = resolveBtcReadAddress(ChainKeys.BITCOIN_MAINNET, PERSONAL_ADDRESS);
+
+    expect(result).toBe(PERSONAL_ADDRESS);
+  });
+});

package/src/hooks/bitcoin/resolveBtcReadAddress.ts

@@ -0,0 +1,21 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import { loadRadfiSession } from './useRadfiAuth.js';
+
+/**
+ * Resolve a spoke address for READ queries (positions, balances, hub-wallet display).
+ *
+ * Bitcoin positions live under the Bound Exchange trading-wallet-derived hub wallet, so for Bitcoin we
+ * resolve to the trading address from the locally-persisted Bound Exchange session. This is intentionally
+ * a LOCAL lookup (no network call): a transient Bound Exchange API outage can never make a real position
+ * read as empty, and reads never throw "Trading wallet not found". When there is no session, the
+ * user has no Bitcoin position to show, so the original (personal) address is returned — deriving
+ * an empty hub wallet, which is correct. Non-Bitcoin chains pass through unchanged.
+ *
+ * The WRITE path resolves the trading address authoritatively in the SDK
+ * (`getEffectiveWalletAddress`, called from the money-market create*Intent flows); reads
+ * deliberately use this lighter, fail-safe path.
+ */
+export function resolveBtcReadAddress(chainKey: SpokeChainKey, address: string): string {
+  if (chainKey !== ChainKeys.BITCOIN_MAINNET) return address;
+  return loadRadfiSession(address)?.tradingAddress ?? address;
+}

package/src/hooks/bitcoin/useFundTradingWallet.ts

@@ -11,7 +11,7 @@ export type UseFundTradingWalletVars = {
 };
 
 /**
- * React hook for funding the user's Radfi trading wallet from their personal Bitcoin wallet.
+ * React hook for funding the user's Bound Exchange trading wallet from their personal Bitcoin wallet.
  * Pure mutation: pass `{ amount, walletProvider }` to `mutate({...})`. Returns the broadcast tx
  * id on success.
  */

package/src/hooks/bitcoin/useRadfiAuth.ts

@@ -45,7 +45,7 @@ export function clearRadfiSession(address: string): void {
 }
 
 /**
- * React hook for authenticating with Radfi via BIP322-signed message. Pure mutation: pass
+ * React hook for authenticating with Bound Exchange via BIP322-signed message. Pure mutation: pass
  * `{ walletProvider }` to `mutate({...})`. The hook itself takes no arguments other than the
  * structural `mutationOptions` slot.
  */
@@ -95,7 +95,7 @@ export function useRadfiAuth({
           }
 
           throw new Error(
-            'This wallet is already registered with Radfi from another session. ' +
+            'This wallet is already registered with Bound Exchange from another session. ' +
               'Please clear your browser storage for this site and try again, ' +
               'or wait for the previous session to expire.',
           );

package/src/hooks/bitcoin/useRadfiWithdraw.ts

@@ -19,7 +19,7 @@ type WithdrawResult = {
 };
 
 /**
- * React hook for withdrawing BTC from the user's Radfi trading wallet back to their personal
+ * React hook for withdrawing BTC from the user's Bound Exchange trading wallet back to their personal
  * Bitcoin wallet. Pure mutation: pass all inputs (including the wallet provider) to
  * `mutate({...})`.
  */
@@ -44,7 +44,7 @@ export function useRadfiWithdraw({
       const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
-        throw new Error('Radfi authentication required. Please login first.');
+        throw new Error('Bound Exchange authentication required. Please login first.');
       }
 
       const buildResult = await radfi.withdrawToUser({ userAddress, amount, tokenId, withdrawTo }, accessToken);

package/src/hooks/bitcoin/useRenewUtxos.ts

@@ -12,7 +12,7 @@ export type UseRenewUtxosVars = {
 };
 
 /**
- * React hook for renewing expired UTXOs in the user's Radfi trading wallet. Pure mutation: pass
+ * React hook for renewing expired UTXOs in the user's Bound Exchange trading wallet. Pure mutation: pass
  * `{ txIdVouts, walletProvider }` to `mutate({...})`.
  */
 export function useRenewUtxos({
@@ -32,7 +32,7 @@ export function useRenewUtxos({
       const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
-        throw new Error('Radfi authentication required. Please login first.');
+        throw new Error('Bound Exchange authentication required. Please login first.');
       }
 
       const buildResult = await radfi.buildRenewUtxoTransaction({ userAddress, txIdVouts }, accessToken);

package/src/hooks/bitcoin/useTradingWallet.ts

@@ -5,7 +5,7 @@ type UseTradingWalletReturn = {
 };
 
 /**
- * Returns the Radfi trading wallet address from the persisted session.
+ * Returns the Bound Exchange trading wallet address from the persisted session.
  * Trading wallet is created automatically during authentication — no API call needed.
  */
 export function useTradingWallet(walletAddress: string | undefined): UseTradingWalletReturn {

package/src/hooks/mm/useATokensBalances.ts

@@ -2,6 +2,7 @@ import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { type Address, isAddress } from 'viem';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseATokensBalancesParams = ReadHookParams<
@@ -42,7 +43,12 @@ export function useATokensBalances({
         }
       }
 
-      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(userAddress, spokeChainKey);
+      // Bitcoin positions live under the trading-wallet-derived hub wallet; resolve it locally
+      // (no network) so a Bound Exchange outage never reads a real position as empty.
+      const hubWalletAddress = await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainKey, userAddress),
+        spokeChainKey,
+      );
       return sodax.moneyMarket.data.getATokensBalances(aTokens, hubWalletAddress);
     },
     enabled: aTokens.length > 0 && !!spokeChainKey && !!userAddress,

package/src/hooks/mm/useUserFormattedSummary.ts

@@ -2,6 +2,7 @@ import type { FormatReserveUSDResponse, FormatUserSummaryResponse } from '@sodax
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseUserFormattedSummaryParams = ReadHookParams<
@@ -36,7 +37,10 @@ export function useUserFormattedSummary({
 
       const [reserves, userReserves] = await Promise.all([
         sodax.moneyMarket.data.getReservesHumanized(),
-        sodax.moneyMarket.data.getUserReservesHumanized(spokeChainKey, userAddress),
+        sodax.moneyMarket.data.getUserReservesHumanized(
+          spokeChainKey,
+          resolveBtcReadAddress(spokeChainKey, userAddress),
+        ),
       ]);
       const formattedReserves = sodax.moneyMarket.data.formatReservesUSD(
         sodax.moneyMarket.data.buildReserveDataWithPrice(reserves),

package/src/hooks/mm/useUserReservesData.ts

@@ -2,6 +2,7 @@ import type { UserReserveData } from '@sodax/sdk';
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { ReadHookParams } from '../shared/types.js';
 
 export type UseUserReservesDataParams = ReadHookParams<
@@ -30,7 +31,10 @@ export function useUserReservesData({
       if (!spokeChainKey || !userAddress) {
         throw new Error('spokeChainKey and userAddress are required');
       }
-      return sodax.moneyMarket.data.getUserReservesData(spokeChainKey, userAddress);
+      return sodax.moneyMarket.data.getUserReservesData(
+        spokeChainKey,
+        resolveBtcReadAddress(spokeChainKey, userAddress),
+      );
     },
     enabled: !!spokeChainKey && !!userAddress,
     refetchInterval: 5000,

package/src/hooks/shared/index.ts

@@ -6,5 +6,8 @@ export * from './useEstimateGas.js';
 export * from './useDeriveUserWalletAddress.js';
 export * from './useStellarTrustlineCheck.js';
 export * from './useRequestTrustline.js';
+export * from './useNearStorageCheck.js';
+export * from './useRegisterNearStorage.js';
+export * from './useNearStorageGate.js';
 export * from './useGetUserHubWalletAddress.js';
 export * from './useXBalances.js';

package/src/hooks/shared/useGetUserHubWalletAddress.ts

@@ -1,6 +1,7 @@
 import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from './useSodaxContext.js';
+import { resolveBtcReadAddress } from '../bitcoin/resolveBtcReadAddress.js';
 import type { Address } from 'viem';
 import type { ReadHookParams } from './types.js';
 
@@ -44,7 +45,10 @@ export function useGetUserHubWalletAddress({
       if (!spokeChainId || !spokeAddress) {
         throw new Error('Spoke chain id and address are required');
       }
-      return await sodax.hubProvider.getUserHubWalletAddress(spokeAddress, spokeChainId);
+      return await sodax.hubProvider.getUserHubWalletAddress(
+        resolveBtcReadAddress(spokeChainId, spokeAddress),
+        spokeChainId,
+      );
     },
     enabled: !!spokeChainId && !!spokeAddress,
     refetchInterval: false,

package/src/hooks/shared/useNearStorageCheck.ts

@@ -0,0 +1,45 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { ReadHookParams } from './types.js';
+
+export type UseNearStorageCheckParams = ReadHookParams<
+  boolean,
+  {
+    token: string | undefined;
+    accountId: string | undefined;
+    chainId: SpokeChainKey | undefined;
+  }
+>;
+
+/**
+ * Whether `accountId` is NEP-141 storage-registered for `token` on NEAR — the receive-side
+ * prerequisite for any leg that delivers a token to the user on NEAR (swap output on NEAR, bridge
+ * into NEAR, money-market borrow/withdraw to NEAR). NEAR's analogue of a Stellar trustline.
+ *
+ * Returns `true` (no gate) when `chainId` is not NEAR, mirroring how the Stellar trustline check
+ * short-circuits off-chain. Native NEAR is not a NEP-141 token, so the SDK reports it as registered.
+ *
+ * Pair with {@link useRegisterNearStorage} to perform the one-time `storage_deposit` when this
+ * resolves to `false`.
+ */
+export function useNearStorageCheck({
+  params,
+  queryOptions,
+}: UseNearStorageCheckParams = {}): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+  const token = params?.token;
+  const accountId = params?.accountId;
+  const chainId = params?.chainId;
+
+  return useQuery<boolean, Error>({
+    queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId],
+    queryFn: async () => {
+      if (chainId !== ChainKeys.NEAR_MAINNET) return true;
+      if (!token || !accountId) return false;
+      return sodax.spoke.near.isStorageRegistered(token, accountId);
+    },
+    enabled: !!token && !!accountId,
+    ...queryOptions,
+  });
+}

package/src/hooks/shared/useNearStorageGate.ts

@@ -0,0 +1,60 @@
+import type { GetWalletProviderType, INearWalletProvider, Result, SpokeChainKey } from '@sodax/sdk';
+import { resolveNearStorageGate } from '../../utils/nearStorageGate.js';
+import { useNearStorageCheck } from './useNearStorageCheck.js';
+import { useRegisterNearStorage } from './useRegisterNearStorage.js';
+
+interface UseNearStorageGateParams {
+  /** Destination chain the token is delivered on. */
+  dstChainKey: SpokeChainKey;
+  /** Destination token address the recipient must be registered for. */
+  token: string | undefined;
+  /** Recipient NEAR account id. */
+  accountId: string | undefined;
+  /** Destination wallet provider; only consumed when it is the NEAR provider. */
+  walletProvider: GetWalletProviderType<SpokeChainKey> | undefined;
+}
+
+interface NearStorageGate {
+  /** Destination is NEAR. */
+  isNear: boolean;
+  /** Destination is NEAR and the recipient is not yet storage-registered for `token`. */
+  needsRegistration: boolean;
+  /** The downstream action must stay disabled while the gate is unresolved or unmet. */
+  blocksAction: boolean;
+  /** The registration-status query is actively fetching. */
+  isChecking: boolean;
+  /** A `storage_deposit` tx is in flight. */
+  isRegistering: boolean;
+  /** Submit the `storage_deposit`; resolves to the SDK `Result` or `undefined` if inputs are missing. */
+  registerStorage: () => Promise<Result<string> | undefined>;
+}
+
+/**
+ * NEP-141 storage-registration gate for flows that deliver a token to a user on NEAR.
+ */
+export function useNearStorageGate({
+  dstChainKey,
+  token,
+  accountId,
+  walletProvider,
+}: UseNearStorageGateParams): NearStorageGate {
+  const nearWalletProvider = walletProvider?.chainType === 'NEAR' ? (walletProvider as INearWalletProvider) : undefined;
+
+  const storageCheck = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+  const { mutateAsyncSafe: register, isPending: isRegistering } = useRegisterNearStorage();
+  const { isNear, needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, storageCheck);
+
+  const registerStorage = async (): Promise<Result<string> | undefined> => {
+    if (!nearWalletProvider || !token || !accountId) return undefined;
+    return register({ token, accountId, walletProvider: nearWalletProvider });
+  };
+
+  return {
+    isNear,
+    needsRegistration,
+    blocksAction,
+    isChecking: storageCheck.isLoading,
+    isRegistering,
+    registerStorage,
+  };
+}

package/src/hooks/shared/useRegisterNearStorage.ts

@@ -0,0 +1,46 @@
+import { ChainKeys, type INearWalletProvider } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext.js';
+import type { MutationHookParams } from './types.js';
+import { useSafeMutation, type SafeUseMutationResult } from './useSafeMutation.js';
+
+export type UseRegisterNearStorageVars = {
+  token: string;
+  accountId: string;
+  walletProvider: INearWalletProvider;
+  /** Storage bond override; defaults to the SDK's `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR). */
+  deposit?: bigint;
+};
+
+/**
+ * Submit a NEP-141 `storage_deposit` so `accountId` can receive `token` on NEAR. NEAR's analogue of
+ * requesting a Stellar trustline; pair with {@link useNearStorageCheck} and call this when the check
+ * resolves to `false`. The recipient's NEAR wallet signs the registration tx.
+ *
+ * Pure mutation: pass `{ token, accountId, walletProvider }` to `mutate(...)`. The hook itself only
+ * takes the structural `mutationOptions` slot. `registerStorage` throws natively (no `Result<T>`),
+ * so this hook is registered as `nativeThrow` in the mutation contract. On success it invalidates
+ * the matching {@link useNearStorageCheck} query.
+ */
+export function useRegisterNearStorage({
+  mutationOptions,
+}: MutationHookParams<string, UseRegisterNearStorageVars> = {}): SafeUseMutationResult<
+  string,
+  Error,
+  UseRegisterNearStorageVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+  return useSafeMutation<string, Error, UseRegisterNearStorageVars>({
+    mutationKey: ['shared', 'registerNearStorage'],
+    ...mutationOptions,
+    mutationFn: async ({ token, accountId, walletProvider, deposit }) =>
+      sodax.spoke.near.registerStorage({ token, accountId, walletProvider, deposit, raw: false }),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({
+        queryKey: ['shared', 'nearStorageCheck', ChainKeys.NEAR_MAINNET, vars.token, vars.accountId],
+      });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/providers/SodaxProvider.tsx

@@ -1,7 +1,6 @@
 import { useMemo, type ReactNode, type ReactElement } from 'react';
-import { Sodax, type SodaxConfig } from '@sodax/sdk';
+import { Sodax, type SodaxOptions } from '@sodax/sdk';
 import { SodaxContext } from '@/contexts/index.js';
-import type { DeepPartial } from '@sodax/sdk';
 
 interface SodaxProviderProps {
   children: ReactNode;
@@ -17,7 +16,7 @@ interface SodaxProviderProps {
    * <SodaxProvider config={config}>...</SodaxProvider>
    * ```
    */
-  config?: DeepPartial<SodaxConfig>;
+  config?: SodaxOptions;
 }
 
 /** Root provider for `@sodax/dapp-kit`. Must be paired with `QueryClientProvider`. */

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from './dex-utils.js';
+export * from './nearStorageGate.js';

package/src/utils/nearStorageGate.test.ts

@@ -0,0 +1,46 @@
+import { ChainKeys } from '@sodax/sdk';
+import { describe, expect, it } from 'vitest';
+import { resolveNearStorageGate } from './nearStorageGate.js';
+
+describe('resolveNearStorageGate', () => {
+  it('destination not NEAR → never gates', () => {
+    expect(resolveNearStorageGate(ChainKeys.POLYGON_MAINNET, { isLoading: false, data: false })).toEqual({
+      isNear: false,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+
+  it('NEAR, check in flight → blocks action but does not yet prompt registration', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: true, data: undefined })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: true,
+    });
+  });
+
+  it('NEAR, check resolved, not registered → prompt registration and block action', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: false })).toEqual({
+      isNear: true,
+      needsRegistration: true,
+      blocksAction: true,
+    });
+  });
+
+  it('NEAR, check resolved, registered → no gate', () => {
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: true })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+
+  it('NEAR, query disabled (unresolved, not checking) → does not block', () => {
+    // isLoading is false for a disabled query; data stays undefined → action must not be blocked.
+    expect(resolveNearStorageGate(ChainKeys.NEAR_MAINNET, { isLoading: false, data: undefined })).toEqual({
+      isNear: true,
+      needsRegistration: false,
+      blocksAction: false,
+    });
+  });
+});

package/src/utils/nearStorageGate.ts

@@ -0,0 +1,39 @@
+import { ChainKeys, type SpokeChainKey } from '@sodax/sdk';
+import type { UseQueryResult } from '@tanstack/react-query';
+
+/** The subset of a `useNearStorageCheck` result the gate reads. A full `UseQueryResult<boolean>` satisfies it. */
+export type NearStorageCheckResult = Pick<UseQueryResult<boolean>, 'isLoading' | 'data'>;
+
+/** UI gate state for NEP-141 storage registration on NEAR. */
+export interface NearStorageGateState {
+  /** Destination is NEAR — the only chain with a NEP-141 storage-registration prerequisite. */
+  isNear: boolean;
+  /** Show the "register storage" action: the check resolved and the recipient is not registered. */
+  needsRegistration: boolean;
+  /**
+   * Keep the downstream action (swap/bridge/borrow/withdraw) disabled: the NEAR gate is unresolved
+   * (still checking) or unmet (needs registration).
+   */
+  blocksAction: boolean;
+}
+
+/**
+ * Derives the NEP-141 storage-registration UI gate state for a flow that delivers a token to a user
+ * on NEAR — NEAR's analogue of the Stellar trustline gate. Unwrapped (no hook): pass the destination
+ * `chainKey` and the `useNearStorageCheck` result; the util owns the `=== NEAR` test and reads
+ * `isLoading` (NOT `isPending`, which stays `true` for a disabled query and would block forever).
+ *
+ * `blocksAction` deliberately also covers the in-flight check window so the action can't be
+ * triggered before registration status is known; `needsRegistration` only flips once the check has
+ * resolved (so the "register" button isn't shown speculatively while still checking).
+ */
+export function resolveNearStorageGate(chainKey: SpokeChainKey, check: NearStorageCheckResult): NearStorageGateState {
+  const isNear = chainKey === ChainKeys.NEAR_MAINNET;
+  const isChecking = check.isLoading;
+  const isRegistered = check.data;
+  return {
+    isNear,
+    needsRegistration: isNear && !isChecking && isRegistered === false,
+    blocksAction: isNear && (isChecking || isRegistered === false),
+  };
+}