@liberfi.io/ui-perpetuals 0.2.1 → 0.2.3

package/dist/index.d.mts

@@ -12,7 +12,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.2.1";
+declare const _default: "0.2.3";
 
 /**
  * Trading pair symbol format
@@ -755,6 +755,244 @@ declare class HyperliquidApiError extends Error {
     constructor(message: string, statusCode: number, responseBody: string);
 }
 
+/**
+ * Hyperliquid Setup Adapter
+ *
+ * Hyperliquid account-state changes (approve builder fee, set referrer,
+ * update leverage) are EIP-712 signed actions sent to /exchange. Encoding
+ * the canonical action hash (msgpack + phantom agent + chain-id-aware
+ * domain) is non-trivial and there are several vetted client libraries
+ * already (@deeeed/hyperliquid, @nktkas/hyperliquid, @hyperliquid-rust-sdk
+ * via wasm, etc.).
+ *
+ * Rather than inlining that logic into this SDK — which would force a
+ * specific dependency on every consumer and bloat the bundle — this
+ * package defines a thin adapter contract. Consumers wire in whichever
+ * implementation they prefer; this SDK only knows the input/output shape
+ * and the idempotency story.
+ *
+ * Design principles:
+ *  - First principles: the SDK does not need to know how the action is
+ *    signed, only that the consumer can read state and perform each
+ *    setup step. Signing & encoding live with the wallet integration.
+ *  - Open-Closed: new setup steps (e.g. sub-account, vault) can be added
+ *    by extending the adapter interface — existing consumers don't break.
+ *  - Liskov: every method returns the same shape so the orchestrator
+ *    can treat all steps uniformly in its state machine.
+ */
+
+/**
+ * Snapshot of the user's relevant Hyperliquid account state.
+ *
+ * Returned by `getAccountState` and used by `useHyperliquidSetup` to
+ * decide which steps still need to run. All fields are optional because
+ * a fresh account may have none of them set.
+ */
+interface HyperliquidAccountState {
+    /**
+     * The builder address (typically the platform's relayer) and the
+     * approved fee in tenths-of-a-basis-point. If `null`, the builder has
+     * not been approved yet.
+     *
+     * Hyperliquid encodes builder fees as integers in 0.001%; e.g. `45`
+     * means 0.045% — a common Axiom-style default.
+     */
+    builderApproval: {
+        builder: string;
+        /** Tenths of a basis point (0.001%). */
+        maxFeeRate: number;
+    } | null;
+    /**
+     * The referrer code currently bound to this account, or `null` if the
+     * user has never set one. Hyperliquid only accepts a referrer once;
+     * subsequent calls must be skipped.
+     */
+    referrer: string | null;
+    /**
+     * Per-asset leverage configuration. Keyed by Hyperliquid asset name
+     * (e.g. `"BTC"`, `"ETH"`), value is the user's currently selected
+     * leverage. Empty when the user has not customised any asset.
+     */
+    leverage: Record<string, number>;
+}
+/**
+ * Parameters for `approveBuilderFee`. The maximum fee is expressed in
+ * tenths of a basis point to match Hyperliquid's wire format and avoid
+ * floating-point drift.
+ */
+interface ApproveBuilderFeeParams {
+    builder: string;
+    /** Tenths of a basis point (0.001%). 45 = 0.045% (Axiom default). */
+    maxFeeRate: number;
+}
+interface SetReferrerParams {
+    /** Hyperliquid referrer code (e.g. "AXIOM"). */
+    code: string;
+}
+interface UpdateLeverageParams {
+    /** Hyperliquid asset name without the suffix (e.g. "BTC", "ETH"). */
+    asset: string;
+    /** Whole-number leverage multiplier (e.g. 5 for 5x). */
+    leverage: number;
+    /**
+     * Whether to use cross-margin (true) or isolated margin (false).
+     * Defaults to cross to mirror Axiom's default UX.
+     */
+    isCross?: boolean;
+}
+/**
+ * Result returned by every adapter method. `txHash` is optional because
+ * Hyperliquid actions don't always surface a hash; the success of the
+ * action is what the orchestrator cares about.
+ */
+interface HyperliquidSetupActionResult {
+    /** Optional action receipt — surfaced to the UI when present. */
+    txHash?: string;
+    /**
+     * The new state captured immediately after the action — lets the hook
+     * skip re-fetching `getAccountState`. Optional; the hook will fall
+     * back to a refresh call when omitted.
+     */
+    state?: Partial<HyperliquidAccountState>;
+}
+/**
+ * Adapter contract. Implementations may live in a consumer app (Privy +
+ * @nktkas/hyperliquid, for example) or be supplied by a future
+ * `@liberfi.io/wallet-connector-*` package.
+ */
+interface IHyperliquidSetupAdapter {
+    /**
+     * Hyperliquid environment this adapter targets — the orchestrator
+     * uses it for diagnostic logging only.
+     */
+    readonly environment: HyperliquidEnvironment;
+    /**
+     * Read the user's current setup state. Used to decide which steps
+     * still need to run, so MUST reflect the latest on-chain truth (not a
+     * cache that may be stale after a setup attempt).
+     */
+    getAccountState(userAddress: string): Promise<HyperliquidAccountState>;
+    /** Sign + submit `approveBuilderFee` action; idempotent at the API. */
+    approveBuilderFee(params: ApproveBuilderFeeParams): Promise<HyperliquidSetupActionResult>;
+    /**
+     * Sign + submit `setReferrer` action.
+     *
+     * Hyperliquid rejects re-binding once a code is set, so the
+     * orchestrator gates this with `getAccountState().referrer == null`
+     * before calling. Adapters should still surface a clear error if the
+     * user retries after the gate.
+     */
+    setReferrer(params: SetReferrerParams): Promise<HyperliquidSetupActionResult>;
+    /** Sign + submit `updateLeverage` action; idempotent at the API. */
+    updateLeverage(params: UpdateLeverageParams): Promise<HyperliquidSetupActionResult>;
+}
+
+/**
+ * Shared REST transport for every LiberFi perpetuals-server client.
+ *
+ * Pulled out of `LiberFiPerpetualsClient` so the deposit client (and any
+ * future feature client) can reuse the same fetch-with-timeout, error
+ * mapping, and header merging logic without copy-paste.
+ *
+ * Design choices:
+ *
+ *   - The class is intentionally minimal: build URL → fire fetch →
+ *     decode JSON → throw a typed error on non-2xx. No retries, no
+ *     circuit breaker, no caching. That layering belongs to the caller
+ *     (e.g. TanStack Query handles retries/cache).
+ *
+ *   - Custom query parameters are passed per-request, not per-instance,
+ *     except for `defaultQuery` which the perpetuals client uses for the
+ *     `?provider=` selector.
+ *
+ *   - Headers merge in three layers (call > instance > built-in). This
+ *     lets a caller add a one-off `Authorization` for a single request
+ *     without leaking it into the rest of the session.
+ */
+/**
+ * Thrown when perpetuals-server returns a non-2xx HTTP status, when the
+ * request times out, or when the network call fails outright.
+ *
+ * `statusCode` is the HTTP status (or `0` for network errors / `408`
+ * for client-side timeouts). `responseBody` is the verbatim response
+ * text — useful for surfacing backend error codes to the user.
+ */
+declare class LiberFiApiError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+/** Configuration for {@link LiberFiHttpTransport}. */
+interface LiberFiHttpTransportConfig {
+    /**
+     * REST base URL, with NO trailing slash. The transport strips trailing
+     * slashes on construction so callers can pass either form.
+     */
+    baseUrl: string;
+    /** Per-request timeout in milliseconds. Defaults to 30 000 ms. */
+    timeout?: number;
+    /**
+     * Headers merged into every request. Per-request headers (passed to
+     * `request()`) win on key collision, then instance headers, then the
+     * built-in `Accept` / `Content-Type`.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Default query parameters appended to every request URL. Useful for
+     * cross-cutting selectors like `?provider=hyperliquid`. Per-request
+     * params override on key collision.
+     */
+    defaultQuery?: Record<string, string | undefined>;
+    /**
+     * Custom `fetch` implementation. Defaults to the global `fetch`.
+     * Useful in tests (drop in a jest mock) or in environments where a
+     * pre-configured fetch (e.g. with circuit breaker / proxy) is supplied
+     * by the host application.
+     */
+    fetchImpl?: typeof fetch;
+}
+/** HTTP method shape — keep narrow; deposit and trading both use these. */
+type LiberFiHttpMethod = "GET" | "POST";
+/** Per-request options accepted by {@link LiberFiHttpTransport.request}. */
+interface RequestOptions {
+    /** Path relative to `baseUrl` (must start with `/`). */
+    path: string;
+    /** Optional query string parameters. Undefined / empty values are skipped. */
+    query?: Record<string, string | undefined>;
+    /** JSON body for POST/PUT/etc. */
+    body?: unknown;
+    /** One-off headers — overrides the instance defaults. */
+    headers?: Record<string, string>;
+    /**
+     * Override the per-instance timeout for this single request.
+     * Use for fast-path reads or long-running submits.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Stateless HTTP transport shared by every LiberFi perpetuals-server
+ * client. Construct one per client (or one shared instance — the class
+ * is safe for concurrent use).
+ */
+declare class LiberFiHttpTransport {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly headers?;
+    private readonly defaultQuery?;
+    private readonly fetchImpl;
+    constructor(config: LiberFiHttpTransportConfig);
+    /** Read-only accessor used by the perpetuals client for WebSocket fallback. */
+    getBaseUrl(): string;
+    /** Build a fully-qualified URL with merged query string. */
+    buildUrl(path: string, query?: Record<string, string | undefined>): string;
+    /**
+     * Issue an HTTP request and decode the JSON response. Returns
+     * `undefined` (cast to T) for `204 No Content`. Throws
+     * {@link LiberFiApiError} on every non-2xx, timeout, or network error.
+     */
+    request<T>(method: LiberFiHttpMethod, opts: RequestOptions): Promise<T>;
+}
+
 /**
  * `signTypedData` is invoked once per place / cancel during the
  * `prepare → submit` flow. The hosting app injects this so the user's wallet
@@ -773,9 +1011,11 @@ interface LiberFiPerpetualsClientConfig {
      *   - Staging:      `https://api.liberfi.io/staging/perpetuals`
      *   - Production:   `https://api.liberfi.io/perpetuals`
      *
-     * The client appends `/v1/...` paths to this value.
+     * The client appends `/v1/...` paths to this value. Required UNLESS a
+     * pre-built {@link LiberFiHttpTransport} is supplied via `transport`,
+     * in which case the transport's baseUrl is used.
      */
-    baseUrl: string;
+    baseUrl?: string;
     /**
      * Optional WebSocket endpoint. Real-time data is NOT proxied by
      * perpetuals-server today — the WS subscription methods connect directly to
@@ -789,6 +1029,7 @@ interface LiberFiPerpetualsClientConfig {
     signTypedData?: SignTypedDataFn;
     /**
      * Per-request timeout in milliseconds. Defaults to 30 000 ms.
+     * Ignored when `transport` is provided (the transport carries its own).
      */
     timeout?: number;
     /**
@@ -799,15 +1040,16 @@ interface LiberFiPerpetualsClientConfig {
     provider?: string;
     /**
      * Optional extra request headers (auth tokens, tracing, etc.) merged into
-     * every fetch.
+     * every fetch. Ignored when `transport` is provided.
      */
     headers?: Record<string, string>;
-}
-/** Thrown when perpetuals-server returns a non-2xx HTTP status. */
-declare class LiberFiApiError extends Error {
-    readonly statusCode: number;
-    readonly responseBody: string;
-    constructor(message: string, statusCode: number, responseBody: string);
+    /**
+     * Inject a pre-built transport instead of letting the client construct
+     * one from `baseUrl` / `timeout` / `headers`. Required when sharing a
+     * single transport with the deposit client to halve the per-call
+     * configuration footprint in `PerpetualsProvider`.
+     */
+    transport?: LiberFiHttpTransport;
 }
 /**
  * REST + injected-signer implementation of {@link IPerpetualsClient} that talks
@@ -825,18 +1067,11 @@ declare class LiberFiApiError extends Error {
  *   exchange (`wsEndpoint`, default Hyperliquid mainnet).
  */
 declare class LiberFiPerpetualsClient implements IPerpetualsClient {
-    private readonly baseUrl;
+    private readonly transport;
     private readonly wsEndpoint;
-    private readonly timeout;
-    private readonly provider?;
-    private readonly headers?;
     private readonly signTypedData?;
     private wsManager;
     constructor(config: LiberFiPerpetualsClientConfig);
-    /** Build a fully-qualified URL with optional query string. */
-    private url;
-    /** Common fetch wrapper with timeout + structured error mapping. */
-    private request;
     getSupportedCoins(): Promise<string[]>;
     getMarket(symbol: string): Promise<MarketData | null>;
     getMarkets(symbols?: string[]): Promise<MarketData[]>;
@@ -857,37 +1092,346 @@ declare class LiberFiPerpetualsClient implements IPerpetualsClient {
     private requireWS;
 }
 
+/**
+ * Wire / domain types for the Solana → Hyperliquid USDC deposit flow.
+ *
+ * These deliberately mirror the perpetuals-server DTOs (see
+ * `internal/handler/deposit_handler.go`) so the SDK <-> backend contract
+ * stays in sync. When the backend adds a new field, add it here too —
+ * the compiler will then point at every place that needs to handle it.
+ *
+ * All amounts denominated in *smallest unit* (lamports for SOL, USDC's
+ * 6-decimal microUSDC for the destination side) are typed as `string` so
+ * we never accidentally lose precision on large values.
+ */
+/** Where the deposit was initiated from. Drives fee attribution server-side. */
+type DepositSource = "dex" | "prediction" | "launchpad" | "channel";
+/** Lifecycle states a deposit can be in. */
+type DepositStatus = "broadcasted" | "relay_waiting" | "relay_pending" | "settled" | "refunded" | "failed" | "stuck";
+/** True for status values that never transition further. */
+declare const TERMINAL_DEPOSIT_STATUSES: ReadonlySet<DepositStatus>;
+/** A single state transition in the status history. */
+interface DepositStatusTransition {
+    from: DepositStatus | "";
+    to: DepositStatus;
+    at: string;
+    source: "handler" | "status_pull" | "reconciliation" | string;
+    reason?: string;
+}
+/** Surfaced when the upstream produced an unrecoverable error. */
+interface DepositErrorInfo {
+    code: string;
+    message: string;
+    recoverable: boolean;
+}
+/** Exact-decimal breakdown returned by the quote endpoint. */
+interface DepositBreakdown {
+    /** Total lamports the user is paying in (gross). */
+    grossLamports: string;
+    /** Platform fee transferred to the LiberFi treasury (lamports). */
+    platformFeeLamports: string;
+    /** Net amount Relay bridges (= gross − platformFee), in lamports. */
+    relayDepositLamports: string;
+    /** SOL pubkey the platform fee is sent to. May be empty when fee = 0. */
+    treasuryAddress: string;
+    /** Expected destination output, in microUSDC (6-decimal). May be empty. */
+    expectedOutputUSDC?: string;
+    /** Origin chain id (Solana mainnet on Relay = 792703809). */
+    originChainId: number;
+    /** Destination chain id (Hyperliquid). */
+    destinationChainId: number;
+    /** Origin currency. SOL is encoded as the SystemProgram pseudo-pubkey. */
+    originCurrency: string;
+    /** Destination currency contract. */
+    destinationCurrency: string;
+    /** Relay-issued depository address — the program/wallet receiving SOL. */
+    depository?: string;
+    /** Relay request id; populated once Relay returns a quote. */
+    relayRequestId?: string;
+}
+/** Body of POST /v1/deposits/quote. */
+interface DepositQuoteRequest {
+    userSolanaAddress: string;
+    hyperliquidRecipient: string;
+    /** Smallest-unit amount the user is paying in. */
+    grossLamports: string;
+    /** Fee attribution source. Defaults to `dex` server-side when empty. */
+    source: DepositSource;
+}
+/** Response of POST /v1/deposits/quote. */
+interface DepositQuoteResponse {
+    /** Base64 SOL transaction the user signs in their wallet. */
+    serializedTxBase64: string;
+    /** Transaction size on the wire (used by client-side guards). */
+    sizeBytes: number;
+    /** True for v0 transactions (legacy = false). */
+    isVersioned: boolean;
+    breakdown: DepositBreakdown;
+    /** ISO 8601 timestamp the quote was issued at. */
+    issuedAt: string;
+    /** ISO 8601 timestamp the quote expires at. */
+    expiresAt: string;
+}
+/** Body of POST /v1/deposits/submit. */
+interface DepositSubmitRequest {
+    userSolanaAddress: string;
+    hyperliquidRecipient: string;
+    /** The signed transaction's hash, returned by the wallet on broadcast. */
+    solanaTxHash: string;
+    breakdown: DepositBreakdown;
+    /** Stable user identifier (LiberFi user id, NOT the wallet address). */
+    userId: string;
+    source: DepositSource;
+    /** Optional marketing campaign / referral code passed through to attribution. */
+    campaign?: string;
+    /** Mirror back the issuedAt from /quote so the server can guard freshness. */
+    quoteIssuedAt: string;
+}
+/** Response of POST /v1/deposits/submit. */
+interface DepositSubmitResponse {
+    intentId: string;
+    /** True the first time a unique solanaTxHash is seen; idempotent retries return false. */
+    created: boolean;
+}
+/** Response of GET /v1/deposits/{id}. */
+interface DepositStatusResponse {
+    intentId: string;
+    status: DepositStatus;
+    userSolanaAddress: string;
+    hyperliquidRecipient: string;
+    solanaTxHash: string;
+    relayRequestId?: string;
+    hyperliquidTxHash?: string;
+    breakdown: DepositBreakdown;
+    statusHistory: DepositStatusTransition[];
+    lastError?: DepositErrorInfo;
+    userId: string;
+    source: DepositSource;
+    campaign?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * REST client for the Solana → Hyperliquid deposit endpoints exposed by
+ * the perpetuals-server (`/v1/deposits/*`).
+ *
+ * Engineering principles:
+ *   - Single responsibility: this file knows about /v1/deposits and
+ *     nothing else. Quote orchestration, fee adapters, status
+ *     reconciliation, etc. live server-side.
+ *   - Modularity: the HTTP transport is injected (or built from a
+ *     baseUrl) so integration tests can drop in a fetch mock; production
+ *     code shares the same transport instance with `LiberFiPerpetualsClient`.
+ *   - First principles: three methods (quote / submit / status), no
+ *     hidden state, no caching. Polling is the caller's concern (the
+ *     hooks do it via TanStack Query).
+ */
+
+/**
+ * Options for constructing a `LiberFiPerpDepositClient`.
+ *
+ * Either provide a pre-built `transport` (preferred — share one with
+ * `LiberFiPerpetualsClient` so connection limits, headers and timeouts
+ * stay consistent) or pass the raw config and let the client build one.
+ */
+type LiberFiPerpDepositClientConfig = {
+    transport: LiberFiHttpTransport;
+} | LiberFiHttpTransportConfig;
+/** Public surface of the deposit client; matches the three handler endpoints. */
+interface IPerpDepositClient {
+    /** POST /v1/deposits/quote */
+    quote(req: DepositQuoteRequest): Promise<DepositQuoteResponse>;
+    /** POST /v1/deposits/submit */
+    submit(req: DepositSubmitRequest): Promise<DepositSubmitResponse>;
+    /** GET /v1/deposits/{id} */
+    status(intentId: string): Promise<DepositStatusResponse>;
+    /** POST /v1/deposits/{id}/refresh — bypasses any future cache TTL. */
+    refresh(intentId: string): Promise<DepositStatusResponse>;
+}
+/** Concrete implementation backed by `LiberFiHttpTransport`. */
+declare class LiberFiPerpDepositClient implements IPerpDepositClient {
+    private readonly transport;
+    constructor(config: LiberFiPerpDepositClientConfig);
+    /** Returns the base URL of the underlying transport (mostly for logs/diagnostics). */
+    getBaseUrl(): string;
+    quote(req: DepositQuoteRequest): Promise<DepositQuoteResponse>;
+    submit(req: DepositSubmitRequest): Promise<DepositSubmitResponse>;
+    status(intentId: string): Promise<DepositStatusResponse>;
+    refresh(intentId: string): Promise<DepositStatusResponse>;
+}
+
+/**
+ * Pure state machine for the deposit UI.
+ *
+ * The backend owns the *authoritative* lifecycle (broadcasted → relay_*
+ * → settled / refunded / failed / stuck). The frontend has a few extra
+ * states *before* we can call /submit (idle, quoting, ready_to_sign,
+ * signing, broadcasting). We model both halves here as a single FSM so
+ * presentational components can switch on a single tag.
+ *
+ * Engineering principles applied:
+ *   - First principles: a state is a *type*, transitions are pure
+ *     functions over (state, event) → state. No timers, no fetch, no
+ *     setState — those live in hooks.
+ *   - Single responsibility: this file knows nothing about HTTP, React,
+ *     or wallets. It is unit-testable in isolation.
+ *   - Extensibility: add a new event by extending DepositEvent + a case
+ *     in `reduceDepositState`. The compiler enforces exhaustiveness.
+ */
+
+/** UI-only state tags. Server-driven tags are a subset of DepositStatus. */
+type DepositPhase = "idle" | "quoting" | "ready_to_sign" | "signing" | "broadcasting" | "submitted" | "tracking" | "succeeded" | "refunded" | "failed" | "expired";
+/** Discriminated union representing the entire deposit flow at any moment. */
+type DepositState = {
+    phase: "idle";
+} | {
+    phase: "quoting";
+} | {
+    phase: "ready_to_sign";
+    quote: DepositQuoteResponse;
+    /** Epoch ms — caller pre-computes for stable comparisons. */
+    expiresAtMs: number;
+} | {
+    phase: "signing";
+    quote: DepositQuoteResponse;
+} | {
+    phase: "broadcasting";
+    quote: DepositQuoteResponse;
+} | {
+    phase: "submitted";
+    quote: DepositQuoteResponse;
+    intentId: string;
+    solanaTxHash: string;
+} | {
+    phase: "tracking";
+    intentId: string;
+    status: DepositStatusResponse;
+} | {
+    phase: "succeeded";
+    intentId: string;
+    status: DepositStatusResponse;
+} | {
+    phase: "refunded";
+    intentId: string;
+    status: DepositStatusResponse;
+} | {
+    phase: "failed";
+    error: DepositErrorInfo;
+    /** Populated when the failure happened post-submit. */
+    intentId?: string;
+    status?: DepositStatusResponse;
+} | {
+    phase: "expired";
+    quote: DepositQuoteResponse;
+};
+/** Events the FSM can react to. Driven by hooks/components. */
+type DepositEvent = {
+    type: "RESET";
+} | {
+    type: "QUOTE_REQUEST";
+} | {
+    type: "QUOTE_RECEIVED";
+    quote: DepositQuoteResponse;
+} | {
+    type: "QUOTE_FAILED";
+    error: DepositErrorInfo;
+} | {
+    type: "QUOTE_EXPIRED";
+} | {
+    type: "SIGN_START";
+} | {
+    type: "SIGN_FAILED";
+    error: DepositErrorInfo;
+} | {
+    type: "BROADCAST_START";
+} | {
+    type: "BROADCAST_FAILED";
+    error: DepositErrorInfo;
+} | {
+    type: "SUBMIT_OK";
+    intentId: string;
+    solanaTxHash: string;
+} | {
+    type: "SUBMIT_FAILED";
+    error: DepositErrorInfo;
+} | {
+    type: "STATUS_UPDATE";
+    status: DepositStatusResponse;
+};
+declare const initialDepositState: DepositState;
+/**
+ * Transition function. Pure, total — every (state, event) pair is
+ * handled. Unknown transitions are no-ops (return current state); we
+ * don't throw because hooks may fan out events optimistically (e.g. a
+ * stale STATUS_UPDATE arriving after RESET).
+ */
+declare function reduceDepositState(state: DepositState, event: DepositEvent): DepositState;
+/** True when the FSM has reached a terminal phase. */
+declare function isTerminal(state: DepositState): boolean;
+/** True when the UI should keep polling /status. */
+declare function isPolling(state: DepositState): boolean;
+/** Returns the current backend lifecycle status, if any. */
+declare function currentStatus(state: DepositState): DepositStatus | undefined;
+/** Returns the breakdown the UI should display, if any. */
+declare function currentBreakdown(state: DepositState): DepositBreakdown | undefined;
+/**
+ * Returns true when the phase is terminal *and* corresponds to one of
+ * the known DepositStatus terminal values. Useful for analytics fan-out
+ * (only emit the funnel-end event once per intent).
+ */
+declare function isTerminalLifecycle(status: DepositStatus | undefined): boolean;
+
 /**
  * Perpetuals context value type
  *
- * Provides access to the perpetuals trading client instance
+ * Provides access to the perpetuals trading client and (optionally) the
+ * deposit client. The deposit client is optional because not every
+ * surface that consumes this provider also needs the deposit flow — a
+ * portfolio view that only renders positions can omit it without
+ * pulling the deposit dependency along.
  */
 interface PerpetualsContextValue {
     /**
-     * Perpetuals client instance for trading operations
+     * Perpetuals client instance for trading operations.
      */
     client: IPerpetualsClient;
+    /**
+     * Deposit client instance for the Solana → Hyperliquid funding flow.
+     *
+     * Optional: surfaces that don't render the deposit UI can omit it.
+     * Hooks that need it (e.g. `usePerpDepositQuote`) will throw a clear
+     * error pointing at the missing prop.
+     */
+    depositClient?: IPerpDepositClient;
 }
 /**
  * Perpetuals Context
  *
- * React context for accessing perpetuals trading functionality throughout the app
+ * React context for accessing perpetuals trading + deposit functionality
+ * throughout the app.
  */
 declare const PerpetualsContext: react.Context<PerpetualsContextValue>;
 
 /**
- * Perpetuals provider props type
+ * Perpetuals provider props type.
+ *
+ * `client` is required; `depositClient` is optional and only needed by
+ * surfaces that render the cross-chain deposit flow.
  */
 type PerpetualsProviderProps = PropsWithChildren<PerpetualsContextValue>;
 /**
- * Perpetuals Provider Component
+ * Perpetuals Provider Component.
  *
- * Provides perpetuals trading client to all child components via React Context
+ * Wraps the perpetuals trading client and (optionally) the deposit
+ * client into a single context value. The value is memoised on the
+ * client identities so re-renders of the consumer app do not break
+ * referential equality for downstream `useContext` consumers.
  *
- * @param props Provider props containing client and children
+ * @param props Provider props containing client(s) and children
  * @returns Provider component wrapping children
  */
-declare function PerpetualsProvider({ client, children, }: PerpetualsProviderProps): react_jsx_runtime.JSX.Element;
+declare function PerpetualsProvider({ client, depositClient, children, }: PerpetualsProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook to access perpetuals client from context
@@ -1009,6 +1553,292 @@ interface UseUserDataSubscriptionResult<T> {
 }
 declare function useUserDataSubscription<T = UserDataType extends "orders" ? Order : UserDataType extends "positions" ? Position : TradeHistory>(params: UseUserDataSubscriptionParams): UseUserDataSubscriptionResult<T>;
 
+/**
+ * Hook to access the deposit client from `PerpetualsProvider`.
+ *
+ * Throws if the provider is missing OR if the host app forgot to pass
+ * `depositClient`. The thrown message tells the consumer exactly what
+ * to fix — preferring an explicit error to a silent runtime crash deep
+ * inside a useQuery hook.
+ *
+ * @returns The deposit client instance.
+ */
+declare function usePerpDepositClient(): IPerpDepositClient;
+
+/**
+ * Stable query key shape for the deposit quote.
+ *
+ * The amount is part of the key so re-quoting on amount change does not
+ * leak across users; the user/recipient pair is included so two users
+ * sharing the same browser session don't see each other's quotes in the
+ * cache.
+ */
+declare function perpDepositQuoteQueryKey(req?: DepositQuoteRequest | null): readonly unknown[];
+/** Pure fetcher — useful for SSR or for invoking outside React. */
+declare function fetchPerpDepositQuote(client: IPerpDepositClient, req: DepositQuoteRequest): Promise<DepositQuoteResponse>;
+interface UsePerpDepositQuoteOptions extends Omit<UseQueryOptions<DepositQuoteResponse, Error, DepositQuoteResponse, ReturnType<typeof perpDepositQuoteQueryKey>>, "queryKey" | "queryFn" | "enabled"> {
+    /**
+     * Override automatic gating. By default the query runs when `req` is
+     * fully populated. Pass `enabled: false` to defer firing while the
+     * user is still typing the amount.
+     */
+    enabled?: boolean;
+}
+/**
+ * Re-quotes on every parameter change, with TanStack Query handling
+ * dedupe / refetch / cancellation. Caller is responsible for surfacing
+ * `data.expiresAt` to the UI; the FSM will move to `expired` if the
+ * user lingers past the deadline.
+ *
+ * Engineering note: the hook deliberately does NOT auto-refresh on a
+ * timer. Re-quoting silently behind the user would erase the “Confirm”
+ * button mid-action; the form should re-call `refetch()` on its own
+ * cadence (e.g. when `expiresAt` is < 5 s from now).
+ */
+declare function usePerpDepositQuote(req: DepositQuoteRequest | null | undefined, options?: UsePerpDepositQuoteOptions): _tanstack_react_query.UseQueryResult<DepositQuoteResponse, Error>;
+
+/**
+ * Adapter the host app must provide. Lives on the consumer side so the
+ * SDK never has to know how a particular wallet (Phantom / Backpack /
+ * Privy / Solflare / …) signs and broadcasts a Solana transaction.
+ *
+ * Contract:
+ *   - Decode the `serializedTxBase64` produced by /quote.
+ *   - Have the user sign it (this is when the wallet UI shows up).
+ *   - Broadcast it. Return the resulting tx hash.
+ *   - Throw on user rejection or RPC failure.
+ *
+ * The SDK keeps things narrow: signature, broadcast, and "did the wallet
+ * succeed" are the only outputs we care about. Everything else (RPC
+ * endpoint, commitment, simulation pre-checks) is an implementation
+ * detail the host already owns.
+ */
+type SignAndBroadcastSolanaTx = (serializedTxBase64: string, ctx: {
+    isVersioned: boolean;
+    sizeBytes: number;
+}) => Promise<string>;
+/** Inputs every deposit attempt needs. */
+interface ExecuteDepositInput {
+    /** The quote previously returned by `/v1/deposits/quote`. */
+    quote: DepositQuoteResponse;
+    /** User-facing identifiers; must match what was sent to /quote. */
+    userSolanaAddress: string;
+    hyperliquidRecipient: string;
+    /** LiberFi user id (NOT the wallet). Stable for fee attribution. */
+    userId: string;
+    source: DepositSource;
+    /** Optional marketing / referral code. */
+    campaign?: string;
+}
+/** Hook return shape — exposes the full FSM and a single trigger. */
+interface UsePerpDepositExecuteResult {
+    state: DepositState;
+    /**
+     * Kick off the sign → broadcast → submit chain. Returns the eventual
+     * `intentId` on success, throws on failure (the FSM will already be
+     * in the `failed` phase with a descriptive `error`).
+     */
+    execute: (input: ExecuteDepositInput) => Promise<string>;
+    /** Force back to `idle`. Use when the user dismisses the modal. */
+    reset: () => void;
+    /** Manually push an event into the FSM (advanced). */
+    dispatch: (event: DepositEvent) => void;
+}
+/**
+ * Orchestrates the full deposit flow:
+ *
+ *   1. SIGN_START  → wallet signs (host adapter)
+ *   2. BROADCAST_START → wallet broadcasts (host adapter)
+ *   3. SUBMIT_OK   → POST /v1/deposits/submit (this hook)
+ *   4. STATUS_UPDATE  ← `usePerpDepositStatus` polls and forwards
+ *
+ * Each stage emits a typed event into the same reducer used by the
+ * presentational components. The hook itself never renders anything —
+ * components consume `state.phase` and react accordingly.
+ */
+declare function usePerpDepositExecute(signAndBroadcast: SignAndBroadcastSolanaTx): UsePerpDepositExecuteResult;
+
+declare function perpDepositStatusQueryKey(intentId?: string): readonly unknown[];
+declare function fetchPerpDepositStatus(client: IPerpDepositClient, intentId: string): Promise<DepositStatusResponse>;
+interface UsePerpDepositStatusOptions extends Omit<UseQueryOptions<DepositStatusResponse, Error, DepositStatusResponse, ReturnType<typeof perpDepositStatusQueryKey>>, "queryKey" | "queryFn" | "refetchInterval" | "enabled"> {
+    enabled?: boolean;
+    /**
+     * Polling interval in milliseconds while the deposit is non-terminal.
+     * Defaults to 3 000 ms — matches the backend's reconciliation cadence
+     * with a small safety margin.
+     */
+    pollIntervalMs?: number;
+}
+/**
+ * Polls /v1/deposits/{id} until the deposit reaches a terminal status,
+ * then stops the timer automatically. The component is responsible for
+ * forwarding `data` into the deposit FSM via STATUS_UPDATE events.
+ *
+ * Engineering principle (single responsibility): this hook owns the
+ * "when to ask the server" question; the FSM owns the "what does the
+ * answer mean" question. They communicate through plain typed values.
+ */
+declare function usePerpDepositStatus(intentId: string | undefined | null, options?: UsePerpDepositStatusOptions): _tanstack_react_query.UseQueryResult<DepositStatusResponse, Error>;
+
+/**
+ * Pure state machine for the Hyperliquid initialisation flow.
+ *
+ * Driven by `useReducer` — kept as a separate module so the transition
+ * logic is unit-testable without React. The states cover the full
+ * lifecycle:
+ *
+ *   idle
+ *     → loading              (caller pressed "init", reading current state)
+ *     → ready                (we know which steps remain)
+ *     → executing            (one step is in flight)
+ *     → done | error
+ *
+ * `error` is recoverable — `RETRY_STEP` returns the FSM to `executing`.
+ * `RESET` always rewinds to `idle` so the caller can re-check status.
+ */
+
+/** Identifier for each setup step — drives the UI checklist. */
+type SetupStepId = "approveBuilderFee" | "setReferrer" | "updateLeverage";
+/**
+ * A single step in the setup checklist. `params` carry exactly the
+ * information the adapter needs to perform the action — the FSM never
+ * inspects them; it only routes them to the adapter.
+ */
+type SetupStep = {
+    id: "approveBuilderFee";
+    params: ApproveBuilderFeeParams;
+} | {
+    id: "setReferrer";
+    params: SetReferrerParams;
+} | {
+    id: "updateLeverage";
+    params: UpdateLeverageParams;
+};
+/** Per-step status tracked across the checklist. */
+type StepStatus = "pending" | "skipped" | "running" | "done" | "error";
+interface StepRecord {
+    step: SetupStep;
+    status: StepStatus;
+    /** Last error message captured for the step. */
+    error?: string;
+    /** Optional tx hash returned by the adapter. */
+    txHash?: string;
+}
+type SetupPhase = "idle" | "loading" | "ready" | "executing" | "done" | "error";
+interface SetupState {
+    phase: SetupPhase;
+    /** Snapshot of the on-chain state captured during `loading`. */
+    accountState?: HyperliquidAccountState;
+    /** All steps requested by the caller, in order. */
+    steps: StepRecord[];
+    /** Index of the step currently executing (only valid in `executing`). */
+    currentIndex?: number;
+    /** Top-level error — typically from `getAccountState`. */
+    error?: string;
+}
+type SetupAction = {
+    type: "START_LOADING";
+} | {
+    type: "LOAD_SUCCESS";
+    accountState: HyperliquidAccountState;
+    steps: StepRecord[];
+} | {
+    type: "LOAD_ERROR";
+    error: string;
+} | {
+    type: "RUN_STEP";
+    index: number;
+} | {
+    type: "STEP_SUCCESS";
+    index: number;
+    txHash?: string;
+    accountState?: HyperliquidAccountState;
+} | {
+    type: "STEP_ERROR";
+    index: number;
+    error: string;
+} | {
+    type: "RESET";
+};
+declare const initialSetupState: SetupState;
+/**
+ * Determine the initial status of a step given the current on-chain
+ * state. `done` (sometimes called `skipped` to the user) means the
+ * action has already happened and we can elide it.
+ *
+ * Encapsulated as a pure function so the same logic is exercised by
+ * both the loader (when `LOAD_SUCCESS` constructs the checklist) and
+ * the adapter result handler (when an action reports a partial state
+ * update).
+ */
+declare function classifyStep(step: SetupStep, state: HyperliquidAccountState): StepStatus;
+declare function reduceSetupState(state: SetupState, action: SetupAction): SetupState;
+/**
+ * Find the next step that still needs to run. Returns `null` when the
+ * checklist is complete — the caller should treat the FSM as `done`.
+ */
+declare function nextRunnableStep(state: SetupState): number | null;
+
+/**
+ * Configuration for the Hyperliquid setup orchestrator.
+ *
+ * The hook is intentionally adapter-agnostic — it does not import any
+ * Hyperliquid signing code. The consumer wires in an adapter (typically
+ * built around their wallet integration) plus the list of steps they
+ * want to run.
+ */
+interface UseHyperliquidSetupOptions {
+    /** Adapter that knows how to read state and submit signed actions. */
+    adapter: IHyperliquidSetupAdapter;
+    /** EVM address of the user (required to read account state). */
+    userAddress: string | undefined;
+    /**
+     * The steps the consumer wants the user to complete. Order is
+     * preserved in the UI, and the orchestrator advances strictly in
+     * sequence so failures don't strand the user mid-checklist.
+     */
+    steps: SetupStep[];
+    /**
+     * If true, the hook performs an initial state read on mount /
+     * adapter change. Defaults to `true`.
+     */
+    autoLoad?: boolean;
+    /** Optional callback invoked once every step is `done` or `skipped`. */
+    onComplete?: (state: SetupState) => void;
+    /** Optional callback for diagnostic logging. */
+    onError?: (err: Error, context: {
+        stepId?: SetupStep["id"];
+    }) => void;
+}
+interface UseHyperliquidSetupResult {
+    state: SetupState;
+    /** Re-fetch the on-chain state. Idempotent — safe to call repeatedly. */
+    reload: () => Promise<void>;
+    /** Run the next pending / error step. No-op when the checklist is done. */
+    runNext: () => Promise<void>;
+    /** Run a specific step by index — used by per-row "Retry" buttons. */
+    runStep: (index: number) => Promise<void>;
+    /** Reset the FSM to `idle` (e.g. when the user closes the wizard). */
+    reset: () => void;
+}
+/**
+ * Orchestrates the Hyperliquid first-run setup checklist.
+ *
+ * Responsibilities:
+ *  - Read the user's account state via the adapter.
+ *  - Classify each requested step against that state, marking ones
+ *    already done as `skipped`.
+ *  - Advance through the remaining steps, calling the appropriate
+ *    adapter method and merging the returned partial state back.
+ *  - Surface errors per-step so the UI can show a precise retry CTA.
+ *
+ * Out of scope:
+ *  - Signing — adapter does it.
+ *  - Persistence — Hyperliquid is the source of truth; we re-read on
+ *    reload instead of caching across sessions.
+ */
+declare function useHyperliquidSetup(opts: UseHyperliquidSetupOptions): UseHyperliquidSetupResult;
+
 type CoinInfoWidgetProps = {
     symbol: string;
 };
@@ -1297,4 +2127,211 @@ declare function TradeHistoryUI({ trades, timeRange, onTimeRangeChange, currentP
 declare function TradeHistorySkeleton(): react_jsx_runtime.JSX.Element;
 declare function TradeHistoryEmpty(): react_jsx_runtime.JSX.Element;
 
-export { type Account, type CancelOrderParams, type CancelOrderResult, type Coin, CoinInfoNotFoundUI, CoinInfoSkeletonsUI, CoinInfoUI, type CoinInfoUIProps, CoinInfoWidget, type CoinInfoWidgetProps, type GetOpenOrdersParams, type GetOpenOrdersResult, type GetPositionsParams, type GetPositionsResult, type GetTradesParams, type GetTradesResult, HyperliquidApiError, type HyperliquidClientConfig, type HyperliquidEnvironment, HyperliquidPerpetualsClient, type IPerpetualsClient, type Kline, type KlineInterval, LiberFiApiError, LiberFiPerpetualsClient, type LiberFiPerpetualsClientConfig, type MarketData, type MarketDataType, OpenOrdersEmpty, OpenOrdersSkeleton, OpenOrdersUI, type OpenOrdersUIProps, OpenOrdersWidget, type OpenOrdersWidgetProps, type Order, type OrderBook, type OrderBookLevel, OrderBookUI, type OrderBookUIProps, OrderBookWidget, type OrderBookWidgetProps, type OrderSide, type OrderStatus, type OrderType, PerpetualsContext, type PerpetualsContextValue, PerpetualsProvider, type PerpetualsProviderProps, type PlaceOrderFormData, PlaceOrderFormUI, type PlaceOrderFormUIProps, PlaceOrderFormWidget, type PlaceOrderFormWidgetProps, type PlaceOrderParams, type PlaceOrderResult, type Position, PositionsEmpty, PositionsSkeleton, PositionsUI, type PositionsUIProps, PositionsWidget, type PositionsWidgetProps, type PriceLevel, SearchCoinsUI, type SearchCoinsUIProps, SearchCoinsWidget, type SearchCoinsWidgetProps, type SignTypedDataFn, type Symbol, type TimeRange, type Trade, type TradeHistory, TradeHistoryEmpty, TradeHistorySkeleton, TradeHistoryUI, type TradeHistoryUIProps, TradeHistoryWidget, type TradeHistoryWidgetProps, type TradeSide, TradesUI, type TradesUIProps, TradesWidget, type TradesWidgetProps, type TradingProvider, type UseCancelOrderMutationParams, type UseCandlesSubscriptionParams, type UseCandlesSubscriptionResult, type UseCoinInfoReturnType, type UseCreateOrderMutationParams, type UseKlinesQueryParams, type UseMarketDataSubscriptionParams, type UseMarketDataSubscriptionResult, type UseMarketQueryParams, type UseMarketsQueryParams, type UseOpenOrdersScriptParams, type UseOpenOrdersScriptResult, type UseOrderBookQueryParams, type UseOrderBookScriptParams, type UseOrderBookScriptResult, type UseOrdersQueryParams, type UsePlaceOrderFormScriptParams, type UsePlaceOrderFormScriptResult, type UsePositionsQueryParams, type UsePositionsScriptParams, type UsePositionsScriptResult, type UseRecentTradesQueryParams, type UseSearchCoinsScriptParams, type UseSearchCoinsScriptResult, type UseTradeHistoryScriptParams, type UseTradeHistoryScriptResult, type UseTradesQueryParams, type UseTradesScriptParams, type UseTradesScriptResult, type UseUserDataSubscriptionParams, type UseUserDataSubscriptionResult, type UserDataType, cancelOrder, coinsQueryKey, createOrder, fetchCoins, fetchKlines, fetchMarket, fetchMarkets, fetchOrderBook, fetchOrders, fetchPositions, fetchRecentTrades, fetchTrades, klinesQueryKey, marketQueryKey, marketsQueryKey, orderBookQueryKey, ordersQueryKey, positionsQueryKey, recentTradesQueryKey, tradesQueryKey, useCancelOrderMutation, useCandlesSubscription, useCoinInfo, useCoinsQuery, useCreateOrderMutation, useKlinesQuery, useMarketDataSubscription, useMarketQuery, useMarketsQuery, useOpenOrdersScript, useOrderBookQuery, useOrderBookScript, useOrdersQuery, usePerpetualsClient, usePlaceOrderFormScript, usePositionsQuery, usePositionsScript, useRecentTradesQuery, useSearchCoinsScript, useTradeHistoryScript, useTradesQuery, useTradesScript, useUserDataSubscription, _default as version };
+/**
+ * Highest-level deposit widget. Wires the three presentational
+ * components (form / confirm / status) to the deposit hooks +
+ * state machine.
+ *
+ * Engineering principles:
+ *   - Single responsibility: this file is the *only* place that knows
+ *     how the three components compose. Anything richer (e.g. embedded
+ *     FAQ panel, support links) belongs to the host application.
+ *   - Inversion of control: every side effect the host might want to
+ *     own (sign + broadcast, success / failure callbacks, explorer
+ *     URLs, balance fetch, address validation) is a prop. The widget
+ *     never imports a wallet adapter directly.
+ */
+interface DepositFlowWidgetProps {
+    /** Connected Solana wallet — used as `userSolanaAddress` in /quote. */
+    userSolanaAddress: string;
+    /** Stable LiberFi user id (for fee attribution). */
+    userId: string;
+    /** Where the deposit was initiated from. */
+    source: DepositSource;
+    /** Optional referral / campaign code propagated to the backend. */
+    campaign?: string;
+    /** Initial Hyperliquid recipient (e.g. derived from the user's EVM wallet). */
+    defaultRecipient?: string;
+    /**
+     * Wallet adapter — sign and broadcast a Solana transaction. The host
+     * app supplies its own wallet integration (Phantom, Privy, Backpack,
+     * …) and returns the resulting tx hash. See `SignAndBroadcastSolanaTx`.
+     */
+    signAndBroadcast: SignAndBroadcastSolanaTx;
+    /** Optional balance display (in SOL units, e.g. "12.345"). */
+    balanceSol?: string;
+    /** Click handler for "Max" — only rendered when `balanceSol` is set. */
+    onMaxClick?: () => void;
+    /** Validates the recipient string. Return undefined when valid. */
+    validateRecipient?: (value: string) => string | undefined;
+    /** Build a Solana explorer URL from a tx hash. */
+    buildSolanaExplorerUrl?: (txHash: string) => string;
+    /** Build a Hyperliquid explorer URL from a tx hash. */
+    buildHyperliquidExplorerUrl?: (txHash: string) => string;
+    /** Fired when a deposit reaches `settled`. */
+    onSettled?: (intentId: string) => void;
+    /** Fired when a deposit fails (after the wallet signed). */
+    onError?: (intentId: string | undefined, message: string) => void;
+    className?: string;
+}
+declare function DepositFlowWidget({ userSolanaAddress, userId, source, campaign, defaultRecipient, signAndBroadcast, balanceSol, onMaxClick, validateRecipient, buildSolanaExplorerUrl, buildHyperliquidExplorerUrl, onSettled, onError, className, }: DepositFlowWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational form for collecting the deposit amount + the
+ * Hyperliquid recipient address.
+ *
+ * No data fetching, no state — every input is controlled from above.
+ * Lets the host app decide when to show the wallet's connected SOL
+ * balance (or omit it entirely).
+ */
+interface DepositFormUIProps {
+    amount: string;
+    onAmountChange: (value: string) => void;
+    recipient: string;
+    onRecipientChange: (value: string) => void;
+    /** Optional: shown as the "Balance: …" hint above the amount input. */
+    balanceSol?: string;
+    /** Disables every interactive control (e.g. while quoting). */
+    disabled?: boolean;
+    /** Inline error to render under the amount input. */
+    amountError?: string;
+    /** Inline error to render under the recipient input. */
+    recipientError?: string;
+    /** Click handler for "Max" — only rendered when `balanceSol` is set. */
+    onMax?: () => void;
+    className?: string;
+}
+declare function DepositFormUI({ amount, onAmountChange, recipient, onRecipientChange, balanceSol, disabled, amountError, recipientError, onMax, className, }: DepositFormUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational confirm modal for the deposit flow.
+ *
+ * Owns no fetching or signing — it just renders the breakdown and
+ * fires `onConfirm` / `onCancel`. The expiry countdown ticks locally
+ * via setInterval and re-renders once a second; when it hits 0 the
+ * `onExpire` callback fires (the parent should refetch the quote).
+ */
+interface DepositConfirmUIProps {
+    isOpen: boolean;
+    /** Quote currently being shown to the user. Required when `isOpen`. */
+    quote: DepositQuoteResponse | undefined;
+    /** True while `/submit` (or wallet sign) is in flight. Disables the CTA. */
+    isExecuting?: boolean;
+    /** True when the displayed quote has already expired. */
+    isExpired?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+    /** Fires when the local countdown reaches zero. */
+    onExpire?: () => void;
+    /** Optional inline error to surface inside the modal. */
+    error?: string;
+}
+declare function DepositConfirmUI({ isOpen, quote, isExecuting, isExpired, onConfirm, onCancel, onExpire, error, }: DepositConfirmUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational status panel.
+ *
+ * Renders one of four visual states:
+ *  - in-progress (broadcasting / submitted / tracking)
+ *  - succeeded
+ *  - refunded
+ *  - failed
+ *
+ * Explorer URLs are caller-provided so the SDK never has to know which
+ * RPC / explorer the host wants (Solscan vs Solana Beach, etc.).
+ */
+interface DepositStatusUIProps {
+    isOpen: boolean;
+    /** The current FSM phase — drives the visual treatment. */
+    phase: DepositPhase;
+    /** Backend status record (may be unavailable on first frame). */
+    status?: DepositStatusResponse;
+    /** Optional Solana explorer URL (caller decides the network). */
+    solanaExplorerUrl?: string;
+    /** Optional Hyperliquid explorer URL. */
+    hyperliquidExplorerUrl?: string;
+    /** "Try again" handler — only rendered when `phase === "failed"`. */
+    onRetry?: () => void;
+    onClose: () => void;
+    /** Optional override for the human-readable message. */
+    errorMessage?: string;
+}
+declare function DepositStatusUI({ isOpen, phase, status, solanaExplorerUrl, hyperliquidExplorerUrl, onRetry, onClose, errorMessage, }: DepositStatusUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Tiny number-formatting helpers shared by the deposit UI.
+ *
+ * We use plain `bigint` arithmetic here — never `Number(...)` on a
+ * lamport / microUSDC value — so we never silently lose precision on
+ * deposits that exceed `Number.MAX_SAFE_INTEGER` lamports.
+ */
+/**
+ * Convert a lamport amount (string bigint) to a SOL-denominated string
+ * with `precision` decimals and trailing zeros stripped.
+ */
+declare function lamportsToSol(value: string, precision?: number): string;
+/** Convert microUSDC (6 decimals) to a USDC display string. */
+declare function microUsdcToUsdc(value: string | undefined, precision?: number): string;
+/** Convert a SOL-denominated decimal string to a lamport `string` (bigint). */
+declare function solToLamports(value: string): string;
+/** Returns whole-second countdown until `expiresAtMs`. Negative -> 0. */
+declare function secondsUntil(expiresAtMs: number, nowMs?: number): number;
+/** Truncate an address to `head…tail` for display. */
+declare function shortAddress(addr: string, head?: number, tail?: number): string;
+
+/**
+ * Pure presentational card for the Hyperliquid first-run setup flow.
+ *
+ * The component is fully driven by the FSM state from
+ * `useHyperliquidSetup` plus a couple of action callbacks, so consumers
+ * can wire it into either a modal, a sidebar panel, or an inline card
+ * without forking the markup.
+ */
+interface HyperliquidInitUIProps {
+    /** FSM snapshot rendered as the checklist. */
+    state: SetupState;
+    /** Trigger the next runnable step (sequential default). */
+    onContinue: () => void;
+    /** Retry a specific step (used by per-row error recovery). */
+    onRetryStep?: (index: number) => void;
+    /** Refresh the on-chain state — typically rendered when the load failed. */
+    onReload?: () => void;
+    /** Optional dismiss handler — show a "Skip for now" CTA when set. */
+    onDismiss?: () => void;
+    /** Optional className override for embedding inside other cards. */
+    className?: string;
+}
+declare function HyperliquidInitUI({ state, onContinue, onRetryStep, onReload, onDismiss, className, }: HyperliquidInitUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Highest-level Hyperliquid setup widget.
+ *
+ * Wraps `useHyperliquidSetup` with the presentational card so consumers
+ * can drop in a single component:
+ *
+ *   <HyperliquidInitWidget
+ *     adapter={mySetupAdapter}
+ *     userAddress={evmAddress}
+ *     steps={[ ... ]}
+ *     onComplete={() => navigate("/perp")}
+ *     onDismiss={() => closeModal()}
+ *   />
+ *
+ * The widget is a thin coordinator — all logic lives in the hook and
+ * all presentation lives in `HyperliquidInitUI`. This split keeps the
+ * UI testable in isolation (Storybook just hands it a `state` prop).
+ */
+interface HyperliquidInitWidgetProps extends Pick<UseHyperliquidSetupOptions, "adapter" | "userAddress" | "steps" | "autoLoad" | "onError"> {
+    /** Invoked once every step is `done` or `skipped`. */
+    onComplete?: (state: SetupState) => void;
+    /**
+     * Optional dismiss callback — when supplied the card renders a
+     * "Skip for now" / "Close" CTA so the user can leave the wizard.
+     */
+    onDismiss?: () => void;
+    /** Optional className passthrough to the rendered card. */
+    className?: string;
+}
+declare function HyperliquidInitWidget({ adapter, userAddress, steps, autoLoad, onComplete, onError, onDismiss, className, }: HyperliquidInitWidgetProps): react_jsx_runtime.JSX.Element;
+
+export { type Account, type ApproveBuilderFeeParams, type CancelOrderParams, type CancelOrderResult, type Coin, CoinInfoNotFoundUI, CoinInfoSkeletonsUI, CoinInfoUI, type CoinInfoUIProps, CoinInfoWidget, type CoinInfoWidgetProps, type DepositBreakdown, DepositConfirmUI, type DepositConfirmUIProps, type DepositErrorInfo, type DepositEvent, DepositFlowWidget, type DepositFlowWidgetProps, DepositFormUI, type DepositFormUIProps, type DepositPhase, type DepositQuoteRequest, type DepositQuoteResponse, type DepositSource, type DepositState, type DepositStatus, type DepositStatusResponse, type DepositStatusTransition, DepositStatusUI, type DepositStatusUIProps, type DepositSubmitRequest, type DepositSubmitResponse, type ExecuteDepositInput, type GetOpenOrdersParams, type GetOpenOrdersResult, type GetPositionsParams, type GetPositionsResult, type GetTradesParams, type GetTradesResult, type HyperliquidAccountState, HyperliquidApiError, type HyperliquidClientConfig, type HyperliquidEnvironment, HyperliquidInitUI, type HyperliquidInitUIProps, HyperliquidInitWidget, type HyperliquidInitWidgetProps, HyperliquidPerpetualsClient, type HyperliquidSetupActionResult, type IHyperliquidSetupAdapter, type IPerpDepositClient, type IPerpetualsClient, type Kline, type KlineInterval, LiberFiApiError, type LiberFiHttpMethod, type RequestOptions as LiberFiHttpRequestOptions, LiberFiHttpTransport, type LiberFiHttpTransportConfig, LiberFiPerpDepositClient, type LiberFiPerpDepositClientConfig, LiberFiPerpetualsClient, type LiberFiPerpetualsClientConfig, type MarketData, type MarketDataType, OpenOrdersEmpty, OpenOrdersSkeleton, OpenOrdersUI, type OpenOrdersUIProps, OpenOrdersWidget, type OpenOrdersWidgetProps, type Order, type OrderBook, type OrderBookLevel, OrderBookUI, type OrderBookUIProps, OrderBookWidget, type OrderBookWidgetProps, type OrderSide, type OrderStatus, type OrderType, PerpetualsContext, type PerpetualsContextValue, PerpetualsProvider, type PerpetualsProviderProps, type PlaceOrderFormData, PlaceOrderFormUI, type PlaceOrderFormUIProps, PlaceOrderFormWidget, type PlaceOrderFormWidgetProps, type PlaceOrderParams, type PlaceOrderResult, type Position, PositionsEmpty, PositionsSkeleton, PositionsUI, type PositionsUIProps, PositionsWidget, type PositionsWidgetProps, type PriceLevel, SearchCoinsUI, type SearchCoinsUIProps, SearchCoinsWidget, type SearchCoinsWidgetProps, type SetReferrerParams, type SetupAction, type SetupPhase, type SetupState, type SetupStep, type SetupStepId, type SignAndBroadcastSolanaTx, type SignTypedDataFn, type StepRecord, type StepStatus, type Symbol, TERMINAL_DEPOSIT_STATUSES, type TimeRange, type Trade, type TradeHistory, TradeHistoryEmpty, TradeHistorySkeleton, TradeHistoryUI, type TradeHistoryUIProps, TradeHistoryWidget, type TradeHistoryWidgetProps, type TradeSide, TradesUI, type TradesUIProps, TradesWidget, type TradesWidgetProps, type TradingProvider, type UpdateLeverageParams, type UseCancelOrderMutationParams, type UseCandlesSubscriptionParams, type UseCandlesSubscriptionResult, type UseCoinInfoReturnType, type UseCreateOrderMutationParams, type UseHyperliquidSetupOptions, type UseHyperliquidSetupResult, type UseKlinesQueryParams, type UseMarketDataSubscriptionParams, type UseMarketDataSubscriptionResult, type UseMarketQueryParams, type UseMarketsQueryParams, type UseOpenOrdersScriptParams, type UseOpenOrdersScriptResult, type UseOrderBookQueryParams, type UseOrderBookScriptParams, type UseOrderBookScriptResult, type UseOrdersQueryParams, type UsePerpDepositExecuteResult, type UsePerpDepositQuoteOptions, type UsePerpDepositStatusOptions, type UsePlaceOrderFormScriptParams, type UsePlaceOrderFormScriptResult, type UsePositionsQueryParams, type UsePositionsScriptParams, type UsePositionsScriptResult, type UseRecentTradesQueryParams, type UseSearchCoinsScriptParams, type UseSearchCoinsScriptResult, type UseTradeHistoryScriptParams, type UseTradeHistoryScriptResult, type UseTradesQueryParams, type UseTradesScriptParams, type UseTradesScriptResult, type UseUserDataSubscriptionParams, type UseUserDataSubscriptionResult, type UserDataType, cancelOrder, classifyStep, coinsQueryKey, createOrder, currentBreakdown as currentDepositBreakdown, currentStatus as currentDepositStatus, fetchCoins, fetchKlines, fetchMarket, fetchMarkets, fetchOrderBook, fetchOrders, fetchPerpDepositQuote, fetchPerpDepositStatus, fetchPositions, fetchRecentTrades, fetchTrades, initialDepositState, initialSetupState, isPolling as isDepositPolling, isTerminal as isDepositTerminal, isTerminalLifecycle as isTerminalDepositLifecycle, klinesQueryKey, lamportsToSol, marketQueryKey, marketsQueryKey, microUsdcToUsdc, nextRunnableStep, orderBookQueryKey, ordersQueryKey, perpDepositQuoteQueryKey, perpDepositStatusQueryKey, positionsQueryKey, recentTradesQueryKey, reduceDepositState, reduceSetupState, secondsUntil, shortAddress, solToLamports, tradesQueryKey, useCancelOrderMutation, useCandlesSubscription, useCoinInfo, useCoinsQuery, useCreateOrderMutation, useHyperliquidSetup, useKlinesQuery, useMarketDataSubscription, useMarketQuery, useMarketsQuery, useOpenOrdersScript, useOrderBookQuery, useOrderBookScript, useOrdersQuery, usePerpDepositClient, usePerpDepositExecute, usePerpDepositQuote, usePerpDepositStatus, usePerpetualsClient, usePlaceOrderFormScript, usePositionsQuery, usePositionsScript, useRecentTradesQuery, useSearchCoinsScript, useTradeHistoryScript, useTradesQuery, useTradesScript, useUserDataSubscription, _default as version };