@hfunlabs/hypurr-connect 0.1.1 → 0.1.3

package/README.md

@@ -1,16 +1,18 @@
 # @hfunlabs/hypurr-connect
 
-React authentication and wallet connectivity library for the [Hyperliquid](https://hyperliquid.xyz) decentralized exchange via the [Hypurr](https://hypurr.fun) gRPC backend. Provides two authentication paths — **Telegram OAuth** and **EOA wallet** (MetaMask / browser wallet) — with a unified `ExchangeClient` API for placing orders, managing positions, and executing any L1 action.
+React authentication and wallet connectivity library for the [Hyperliquid](https://hyperliquid.xyz) decentralized exchange via the [Hypurr](https://hypurr.fun) gRPC backend. Provides two authentication paths — **Telegram OAuth** and **EOA wallet** (MetaMask / browser wallet) — with a unified `ExchangeClient` API for placing orders, managing positions, and executing both L1 and user-signed actions.
 
 ## Features
 
-- **Dual auth flows** — Telegram OAuth (server-side signing) and EOA wallet (client-side agent key signing)
-- **Unified exchange client** — Same `ExchangeClient` interface regardless of auth method
+- **Dual auth flows** — Telegram OAuth (server-side signing) and EOA wallet (client-side signing)
+- **Unified exchange client** — Same `ExchangeClient` interface regardless of auth method; handles both L1 actions (orders, cancels, leverage) and user-signed actions (transfers, withdrawals, staking)
+- **Dual wallet routing** — EOA exchange client automatically routes L1 actions through the agent key (silent) and user-signed actions through the master wallet (wallet popup)
+- **Auto agent provisioning** — Agent keys are created on-the-fly the first time an L1 action is executed; no manual `approveAgent` step required when a signer is provided
+- **Multi-wallet management** — Switch between wallets, create/delete wallets, manage wallet packs and labels (Telegram users)
 - **gRPC transport** — Custom transport that routes exchange actions through the Hypurr backend for Telegram users
-- **Agent key management** — Automatic generation, on-chain approval, and localStorage persistence of agent keys for EOA wallets
+- **Agent key management** — Named agent keys (`"hypurr-connect"`) with on-chain approval, `extraAgents` validation, expiry-aware caching, and automatic dead-agent recovery
 - **Session persistence** — Auth state survives page reloads via localStorage
 - **Responsive login modal** — Centered modal on desktop, bottom drawer on mobile with framer-motion animations
-- **USDC balance tracking** — Built-in clearinghouse balance fetching with manual refresh
 
 ## Installation
 
@@ -46,6 +48,7 @@ const config = {
   telegram: {
     botUsername: "YourBot",
     botId: "123456789",
+    useWidget: true,
   },
 };
 
@@ -64,7 +67,7 @@ function App() {
 import { useHypurrConnect } from "@hfunlabs/hypurr-connect";
 
 function TradingPanel() {
-  const { user, isLoggedIn, exchange, usdcBalance, openLoginModal, logout } =
+  const { user, isLoggedIn, exchange, openLoginModal, logout } =
     useHypurrConnect();
 
   if (!isLoggedIn) {
@@ -74,7 +77,6 @@ function TradingPanel() {
   return (
     <div>
       <p>Welcome, {user.displayName}</p>
-      <p>Balance: {usdcBalance} USDC</p>
       <button onClick={logout}>Disconnect</button>
     </div>
   );
@@ -112,14 +114,17 @@ function AppShell() {
 interface HypurrConnectConfig {
   grpcTimeout?: number; // Request timeout in ms (default: 15000)
   isTestnet?: boolean; // Use testnet endpoints (default: false)
-  telegram?: {
-    botUsername: string; // Telegram bot username for the login widget
-    botId: string; // Telegram bot ID for the OAuth URL
+  telegram: {
+    botUsername: string; // Telegram bot username (required for the widget)
+    botId?: string; // Telegram bot ID (required for the popup OAuth flow)
+    useWidget: boolean; // true = inline Telegram Login Widget, false = popup OAuth
   };
 }
 ```
 
-The `telegram` block is only required if you want to support Telegram login.
+When `useWidget` is `true`, the login modal renders Telegram's official [Login Widget](https://core.telegram.org/widgets/login) inline — no popup window is opened. This avoids popup-blocker issues and shows users the familiar Telegram button directly inside the modal. The widget requires `botUsername` and that your domain is linked to the bot via `/setdomain` in [@BotFather](https://t.me/botfather).
+
+When `useWidget` is `false` (or omitted), the popup OAuth flow is used, which requires `botId`.
 
 ### Dependencies
 
@@ -129,44 +134,183 @@ This package depends on [`hypurr-grpc`](https://gitlab.com/hypurr/hypurr-grpc) (
 
 ### Telegram Login
 
-1. User clicks "Telegram" in the `LoginModal`
-2. A popup opens to `oauth.telegram.org` with the configured bot
-3. User authorizes; Telegram posts auth data back via `postMessage`
+Two modes are available, controlled by `config.telegram.useWidget`:
+
+**Widget mode** (`useWidget: true`) — recommended:
+
+1. The `LoginModal` renders Telegram's official [Login Widget](https://core.telegram.org/widgets/login) inline
+2. User clicks the widget button and authorizes with Telegram
+3. The widget calls the `onAuth` callback with the user's auth data
 4. The provider calls the Hypurr gRPC backend (`telegramUser`) to fetch the user's wallet address and ID
 5. An `ExchangeClient` is created with `GrpcExchangeTransport` — all exchange actions are signed **server-side** by the Hypurr backend
 6. Session is persisted in localStorage (`hypurr-connect-tg-user`)
 
+**Popup mode** (`useWidget: false`):
+
+1. User clicks "Telegram" in the `LoginModal`
+2. A popup opens to `oauth.telegram.org` with the configured bot
+3. User authorizes; Telegram posts auth data back via `postMessage`
+4. Steps 4–6 are identical to widget mode
+
 ### EOA Wallet Login
 
+When a signer is provided via `connectEoa`, the exchange client works immediately — no manual agent approval step is needed:
+
 1. User clicks "Wallet" in the `LoginModal`; the `onConnectWallet` callback fires
-2. Your app connects the wallet (e.g., via wagmi) and calls `loginEoa(address)`
-3. The user must approve an agent key before trading:
-   - Call `approveAgent(signTypedDataAsync)` with the wallet's signing function
-   - A random agent key pair is generated locally
-   - The wallet signs an EIP-712 `ApproveAgent` message
-   - The approval is submitted to Hyperliquid
-   - The agent key is persisted in localStorage (`hypurr-connect-agent:{address}`)
-4. An `ExchangeClient` is created with `HttpTransport` + `PrivateKeySigner` — all exchange actions are signed **client-side** with the agent key
+2. Your app connects the wallet (e.g., via wagmi) and calls `connectEoa(address, signer)` with an `EoaSigner` — this sets the user immediately and restores a cached agent from localStorage if one is still valid
+3. The `exchange` client is ready to use right away:
+   - **User-signed actions** (transfers, withdrawals, staking) are routed directly to the master wallet — the wallet popup appears for the user to approve
+   - **L1 actions** (orders, cancels, leverage) use the agent key. If no agent exists yet, one is **auto-provisioned** on the first L1 call — this triggers a single wallet popup for the `approveAgent` signature, then the original action proceeds
+   - Named agent keys (`"hypurr-connect"`) are cached in localStorage with their `validUntil` timestamp and revalidated against Hyperliquid's `extraAgents` endpoint
+4. If an exchange action fails because the agent was pruned or expired, the SDK automatically clears the dead agent and surfaces the error via `error`
+
+Use the `createEoaSigner` helper to adapt wagmi's `signTypedDataAsync` to the `EoaSigner` interface. Pass a ref to avoid stale closure issues with React hooks:
+
+```tsx
+import { useHypurrConnect, createEoaSigner } from "@hfunlabs/hypurr-connect";
+import { useSignTypedData, useChainId, useAccountEffect } from "wagmi";
+
+function ConnectWallet() {
+  const { connectEoa, logout, exchange } = useHypurrConnect();
+  const { signTypedDataAsync } = useSignTypedData();
+  const chainId = useChainId();
+
+  // Keep a ref so the signer always calls the latest signTypedDataAsync
+  const signerRef = useRef(signTypedDataAsync);
+  signerRef.current = signTypedDataAsync;
+
+  useAccountEffect({
+    onConnect({ address }) {
+      connectEoa(address, createEoaSigner(signerRef, chainId));
+    },
+    onDisconnect() {
+      logout();
+    },
+  });
+
+  // exchange is ready — L1 and user-signed actions both work
+  if (exchange) {
+    // L1 action — agent signs silently (auto-provisioned if needed)
+    await exchange.order({ orders: [/* ... */], grouping: "na" });
+
+    // User-signed action — wallet popup appears
+    await exchange.usdSend({ destination: "0x...", amount: "100" });
+  }
+}
+```
+
+If you prefer explicit control over agent approval (or don't need user-signed actions), you can omit the signer and call `approveAgent` manually:
+
+```tsx
+connectEoa(address); // no signer — only L1 actions after manual approval
+await approveAgent(signTypedDataAsync, chainId);
+```
 
 ### Using the Exchange Client
 
-Once authenticated (and agent approved for EOA), the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. Use it for any L1 action:
+Once authenticated, the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. For EOA users with a signer, it handles **both** L1 and user-signed actions transparently:
 
 ```tsx
-const { exchange, agentReady } = useHypurrConnect();
+const { exchange } = useHypurrConnect();
 
-// Place an order (works identically for Telegram and EOA users)
 if (exchange) {
-  const result = await exchange.placeOrder({
-    asset: 0,
-    isBuy: true,
-    limitPx: "50000",
-    sz: "0.001",
-    orderType: { limit: { tif: "Gtc" } },
+  // L1 actions — signed by the agent key (no wallet popup)
+  await exchange.order({
+    orders: [
+      {
+        a: 0,
+        b: true,
+        p: "50000",
+        s: "0.001",
+        t: { limit: { tif: "Gtc" } },
+      },
+    ],
+    grouping: "na",
+  });
+
+  await exchange.cancelOrder({ asset: 0, oid: 12345 });
+
+  // User-signed actions — signed by the master wallet (wallet popup)
+  await exchange.usdSend({ destination: "0x...", amount: "100" });
+  await exchange.withdraw({ destination: "0x...", amount: "50" });
+  await exchange.spotSend({
+    destination: "0x...",
+    token: "PURR:0x...",
+    amount: "10",
   });
 }
 ```
 
+The routing is automatic — no need to call different methods or switch signers.
+
+### Multi-Wallet Management (Telegram)
+
+Telegram users can have multiple wallets. The library exposes the full wallet list and lets you switch the active wallet — the `exchange` client and `user` automatically update.
+
+```tsx
+const {
+  wallets,
+  selectedWalletId,
+  selectWallet,
+  createWallet,
+  deleteWallet,
+  refreshWallets,
+} = useHypurrConnect();
+
+// List wallets
+wallets.map((w) => (
+  <button
+    key={w.id}
+    onClick={() => selectWallet(w.id)}
+    style={{ fontWeight: w.id === selectedWalletId ? "bold" : "normal" }}
+  >
+    {w.name || w.ethereumAddress}
+  </button>
+));
+
+// Create a new wallet
+const newWallet = await createWallet("Trading");
+
+// Delete a wallet (auto-selects another if the deleted one was active)
+await deleteWallet(walletId);
+```
+
+#### Wallet Packs & Labels
+
+Organize watched wallets into named packs with labels:
+
+```tsx
+const {
+  packs,
+  createWalletPack,
+  addPackLabel,
+  modifyPackLabel,
+  removePackLabel,
+} = useHypurrConnect();
+
+// Create a pack
+const packId = await createWalletPack("Whales");
+
+// Add a labeled wallet to the pack
+await addPackLabel({
+  walletAddress: "0x...",
+  walletLabel: "Big trader",
+  packId,
+});
+
+// Rename a label
+await modifyPackLabel({
+  walletLabelOld: "Big trader",
+  walletLabelNew: "Whale #1",
+  packId,
+});
+
+// Remove a label from the pack
+await removePackLabel({ walletLabel: "Whale #1", packId });
+```
+
+All wallet management functions automatically refresh the wallet list from the server after mutations.
+
 ## API Reference
 
 ### Components
@@ -179,7 +323,7 @@ if (exchange) {
 </HypurrConnectProvider>
 ```
 
-Context provider that manages all auth state, gRPC clients, exchange clients, and balance tracking. Must wrap any component that uses `useHypurrConnect`.
+Context provider that manages all auth state, gRPC clients, and exchange clients. Must wrap any component that uses `useHypurrConnect`.
 
 #### `LoginModal`
 
@@ -200,31 +344,38 @@ Returns the full auth and exchange state. Throws if used outside `HypurrConnectP
 
 ### `HypurrConnectState`
 
-| Property             | Type                                                     | Description                                    |
-| -------------------- | -------------------------------------------------------- | ---------------------------------------------- |
-| `user`               | `HypurrUser \| null`                                     | Current authenticated user                     |
-| `isLoggedIn`         | `boolean`                                                | Whether a user is authenticated                |
-| `isLoading`          | `boolean`                                                | Whether auth is in progress                    |
-| `error`              | `string \| null`                                         | Last auth error message                        |
-| `authMethod`         | `AuthMethod`                                             | `"telegram"`, `"eoa"`, or `null`               |
-| `exchange`           | `ExchangeClient \| null`                                 | Hyperliquid exchange client for L1 actions     |
-| `usdcBalance`        | `string \| null`                                         | User's USDC balance from the clearinghouse     |
-| `usdcBalanceLoading` | `boolean`                                                | Whether balance is being fetched               |
-| `refreshBalance`     | `() => void`                                             | Manually re-fetch USDC balance                 |
-| `loginModalOpen`     | `boolean`                                                | Whether the login modal is visible             |
-| `openLoginModal`     | `() => void`                                             | Show the login modal                           |
-| `closeLoginModal`    | `() => void`                                             | Hide the login modal                           |
-| `loginTelegram`      | `(data: TelegramLoginData) => void`                      | Authenticate with Telegram OAuth data          |
-| `loginEoa`           | `(address: \`0x\${string}\`) => void`                    | Authenticate with an EOA wallet address        |
-| `logout`             | `() => void`                                             | Clear all auth state and localStorage          |
-| `agent`              | `StoredAgent \| null`                                    | Current agent key (EOA flow only)              |
-| `agentReady`         | `boolean`                                                | Whether the agent key is approved and ready    |
-| `approveAgent`       | `(signTypedDataAsync: SignTypedDataFn) => Promise<void>` | Generate and approve a new agent key           |
-| `clearAgent`         | `() => void`                                             | Remove the agent key from state and storage    |
-| `botId`              | `string`                                                 | Telegram bot ID from config                    |
-| `authDataMap`        | `Record<string, string>`                                 | Raw Telegram auth data as key-value pairs      |
-| `telegramClient`     | `TelegramClient`                                         | Low-level gRPC client for the Telegram service |
-| `staticClient`       | `StaticClient`                                           | Low-level gRPC client for the Static service   |
+| Property           | Type                                                                      | Description                                                      |
+| ------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `user`             | `HypurrUser \| null`                                                      | Current authenticated user (reflects selected wallet)            |
+| `isLoggedIn`       | `boolean`                                                                 | Whether a user is authenticated                                  |
+| `isLoading`        | `boolean`                                                                 | Whether auth is in progress                                      |
+| `error`            | `string \| null`                                                          | Last auth or dead-agent error message                            |
+| `authMethod`       | `AuthMethod`                                                              | `"telegram"`, `"eoa"`, or `null`                                 |
+| `exchange`         | `ExchangeClient \| null`                                                  | Hyperliquid exchange client (L1 + user-signed actions for EOA)   |
+| `wallets`          | `HyperliquidWallet[]`                                                     | All wallets for the Telegram user (empty for EOA)                |
+| `selectedWalletId` | `number`                                                                  | ID of the currently active wallet                                |
+| `selectWallet`     | `(walletId: number) => void`                                              | Switch the active wallet                                         |
+| `createWallet`     | `(name: string) => Promise<HyperliquidWallet>`                            | Create a new wallet (Telegram only)                              |
+| `deleteWallet`     | `(walletId: number) => Promise<void>`                                     | Delete a wallet (Telegram only)                                  |
+| `refreshWallets`   | `() => void`                                                              | Re-fetch wallets and packs from the server                       |
+| `packs`            | `TelegramChatWalletPack[]`                                                | Wallet packs for the Telegram user                               |
+| `createWalletPack` | `(name: string) => Promise<number>`                                       | Create a wallet pack; returns the new pack ID                    |
+| `addPackLabel`     | `(params) => Promise<void>`                                               | Add a labeled wallet to a pack                                   |
+| `modifyPackLabel`  | `(params) => Promise<void>`                                               | Rename a label within a pack                                     |
+| `removePackLabel`  | `(params) => Promise<void>`                                               | Remove a label from a pack                                       |
+| `loginModalOpen`   | `boolean`                                                                 | Whether the login modal is visible                               |
+| `openLoginModal`   | `() => void`                                                              | Show the login modal                                             |
+| `closeLoginModal`  | `() => void`                                                              | Hide the login modal                                             |
+| `connectEoa`       | `(address: \`0x\${string}\`, signer?: EoaSigner) => void`                 | Connect EOA wallet (sync); pass signer to enable user-signed actions and auto-provisioning |
+| `approveAgent`     | `(signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>` | Approve a named agent key (async, triggers wallet prompt)        |
+| `logout`           | `() => void`                                                              | Clear all auth state and localStorage                            |
+| `agent`            | `StoredAgent \| null`                                                     | Current agent key (EOA flow only)                                |
+| `agentReady`       | `boolean`                                                                 | Whether the exchange client can sign (true for TG, or EOA+agent) |
+| `clearAgent`       | `() => void`                                                              | Remove the agent key from state and storage                      |
+| `botId`            | `string`                                                                  | Telegram bot ID from config                                      |
+| `authDataMap`      | `Record<string, string>`                                                  | Raw Telegram auth data as key-value pairs                        |
+| `telegramClient`   | `TelegramClient`                                                          | Low-level gRPC client for the Telegram service                   |
+| `staticClient`     | `StaticClient`                                                            | Low-level gRPC client for the Static service                     |
 
 ### Types
 
@@ -268,9 +419,62 @@ interface StoredAgent {
   privateKey: `0x${string}`;
   address: `0x${string}`;
   approvedAt: number; // Timestamp when approved on-chain
+  validUntil: number; // Epoch ms from extraAgents; agent is invalid after this
 }
 ```
 
+#### `HyperliquidWallet`
+
+Re-exported from `hypurr-grpc`:
+
+```typescript
+interface HyperliquidWallet {
+  id: number;
+  name: string;
+  ethereumAddress: string;
+  isAgent: boolean;
+  isReadOnly: boolean;
+  // ... plus balances, movements, sessions
+}
+```
+
+#### `TelegramChatWalletPack`
+
+Re-exported from `hypurr-grpc`:
+
+```typescript
+interface TelegramChatWalletPack {
+  id: number;
+  telegramChatId: number;
+  name: string;
+}
+```
+
+#### `EoaSigner`
+
+Encapsulates the master wallet's EIP-712 signing function and chain ID. Pass to `connectEoa` to enable user-signed actions and auto agent provisioning.
+
+```typescript
+interface EoaSigner {
+  signTypedData: SignTypedDataFn;
+  chainId: number;
+}
+```
+
+#### `createEoaSigner(signTypedData, chainId): EoaSigner`
+
+Helper to create an `EoaSigner` from wagmi's `signTypedDataAsync` (or any compatible function). Accepts either a direct function or a `{ current: Function }` ref to avoid stale closures with React hooks:
+
+```typescript
+// With a ref (recommended for React — always calls the latest function)
+const signerRef = useRef(signTypedDataAsync);
+signerRef.current = signTypedDataAsync;
+const signer = createEoaSigner(signerRef, chainId);
+
+// With a direct function (fine for stable references)
+const signer = createEoaSigner(signTypedDataAsync, chainId);
+```
+
 #### `SignTypedDataFn`
 
 ```typescript
@@ -334,28 +538,39 @@ Both use `GrpcWebFetchTransport` with the configured `baseUrl`, `timeout`, and `
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                  HypurrConnectProvider                   │
-│                                                         │
-│  ┌───────────────┐          ┌────────────────────────┐  │
-│  │ Telegram Auth │──gRPC──▶ │  GrpcExchangeTransport │  │
-│  │  (server-     │          │  ┌──────────────────┐   │  │
-│  │   signed)     │          │  │ telegramClient    │   │  │
-│  └───────────────┘          │  │ .hyperliquidCore  │   │  │
-│                              │  │  Action()         │   │  │
-│  ┌───────────────┐          │  └──────────────────┘   │  │
-│  │   EOA Auth    │──HTTP──▶ │  HttpTransport          │  │
-│  │  (agent key   │          │  + PrivateKeySigner     │  │
-│  │   signed)     │          └────────────────────────┘  │
-│  └───────────────┘                    │                  │
-│                                       ▼                  │
-│                              ┌──────────────┐           │
-│                              │ExchangeClient│           │
-│                              └──────────────┘           │
-│                                       │                  │
-│                                       ▼                  │
-│                              Hyperliquid L1              │
-└─────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                      HypurrConnectProvider                        │
+│                                                                  │
+│  ┌──────────────────┐       ┌──────────────────────────────┐     │
+│  │  Telegram Auth    │─gRPC─▶│  GrpcExchangeTransport        │     │
+│  │  (server-signed)  │       │  telegramClient                │     │
+│  └──────────────────┘       │    .hyperliquidCoreAction()    │     │
+│                              └──────────────────────────────┘     │
+│                                                                  │
+│  ┌──────────────────┐       ┌──────────────────────────────┐     │
+│  │    EOA Auth       │─HTTP─▶│  HttpTransport + Dual Wallet   │     │
+│  │  (client-signed)  │       │                                │     │
+│  └──────────────────┘       │  signTypedData(params) ─┐      │     │
+│                              │                         │      │     │
+│                              │  domain = "Exchange"    │      │     │
+│                              │    └─▶ Agent Key        │      │     │
+│                              │        (auto-provision  │      │     │
+│                              │         if needed)      │      │     │
+│                              │                         │      │     │
+│                              │  domain = "Hyperliquid  │      │     │
+│                              │   SignTransaction"      │      │     │
+│                              │    └─▶ Master Wallet    │      │     │
+│                              │        (wallet popup)   │      │     │
+│                              └──────────────────────────────┘     │
+│                                          │                        │
+│                                          ▼                        │
+│                                 ┌──────────────┐                 │
+│                                 │ExchangeClient│                 │
+│                                 └──────────────┘                 │
+│                                          │                        │
+│                                          ▼                        │
+│                                  Hyperliquid L1                   │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ## License

package/dist/index.d.ts

@@ -3,13 +3,18 @@ import { ReactNode } from 'react';
 import { ExchangeClient, IRequestTransport } from '@hfunlabs/hyperliquid';
 import { StaticClient } from 'hypurr-grpc/ts/hypurr/static/static_service.client';
 import { TelegramClient } from 'hypurr-grpc/ts/hypurr/telegram/telegram_service.client';
+import { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
+export { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
+import { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
+export { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
 
 interface HypurrConnectConfig {
     grpcTimeout?: number;
     isTestnet?: boolean;
-    telegram?: {
+    telegram: {
         botUsername: string;
-        botId: string;
+        botId?: string;
+        useWidget: boolean;
     };
 }
 interface TelegramLoginData {
@@ -29,11 +34,15 @@ interface HypurrUser {
     photoUrl?: string;
     authMethod: AuthMethod;
     telegramId?: string;
+    hfunScore?: number;
+    reputationScore?: number;
 }
 interface StoredAgent {
     privateKey: `0x${string}`;
     address: `0x${string}`;
     approvedAt: number;
+    /** Epoch ms from the `extraAgents` response; agent is invalid after this time. */
+    validUntil: number;
 }
 type SignTypedDataFn = (params: {
     domain: Record<string, unknown>;
@@ -44,6 +53,37 @@ type SignTypedDataFn = (params: {
     primaryType: string;
     message: Record<string, unknown>;
 }) => Promise<`0x${string}`>;
+/** Wallet signer provided at EOA connect time for user-signed actions. */
+interface EoaSigner {
+    signTypedData: SignTypedDataFn;
+    chainId: number;
+}
+/**
+ * Create an {@link EoaSigner} from any EIP-712 signing function.
+ *
+ * Accepts either a direct function or a `{ current }` ref object so the
+ * signer always calls through to the latest function (avoids stale closures
+ * with React hooks like wagmi's `useSignTypedData`).
+ *
+ * @example wagmi v2 — ref pattern (recommended)
+ * ```ts
+ * const { signTypedDataAsync } = useSignTypedData();
+ * const chainId = useChainId();
+ * const signerRef = useRef(signTypedDataAsync);
+ * signerRef.current = signTypedDataAsync; // stays fresh every render
+ *
+ * // call once — the ref keeps it up to date
+ * connectEoa(address, createEoaSigner(signerRef, chainId));
+ * ```
+ *
+ * @example direct function (e.g. from viem WalletClient)
+ * ```ts
+ * connectEoa(address, createEoaSigner(client.signTypedData, chainId));
+ * ```
+ */
+declare function createEoaSigner(signTypedDataAsync: ((args: Record<string, unknown>) => Promise<`0x${string}`>) | {
+    current: (args: Record<string, unknown>) => Promise<`0x${string}`>;
+}, chainId: number): EoaSigner;
 interface HypurrConnectState {
     user: HypurrUser | null;
     isLoggedIn: boolean;
@@ -51,18 +91,36 @@ interface HypurrConnectState {
     error: string | null;
     authMethod: AuthMethod;
     exchange: ExchangeClient<any> | null;
-    usdcBalance: string | null;
-    usdcBalanceLoading: boolean;
-    refreshBalance: () => void;
+    wallets: HyperliquidWallet[];
+    selectedWalletId: number;
+    selectWallet: (walletId: number) => void;
+    createWallet: (name: string) => Promise<HyperliquidWallet>;
+    deleteWallet: (walletId: number) => Promise<void>;
+    refreshWallets: () => void;
+    packs: TelegramChatWalletPack[];
+    createWalletPack: (name: string) => Promise<number>;
+    addPackLabel: (params: {
+        walletAddress: string;
+        walletLabel: string;
+        packId: number;
+    }) => Promise<void>;
+    modifyPackLabel: (params: {
+        walletLabelOld: string;
+        walletLabelNew: string;
+        packId: number;
+    }) => Promise<void>;
+    removePackLabel: (params: {
+        walletLabel: string;
+        packId: number;
+    }) => Promise<void>;
     loginModalOpen: boolean;
     openLoginModal: () => void;
     closeLoginModal: () => void;
-    loginTelegram: (data: TelegramLoginData) => void;
-    loginEoa: (address: `0x${string}`) => void;
+    connectEoa: (address: `0x${string}`, signer?: EoaSigner) => void;
+    approveAgent: (signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>;
     logout: () => void;
     agent: StoredAgent | null;
     agentReady: boolean;
-    approveAgent: (signTypedDataAsync: SignTypedDataFn) => Promise<void>;
     clearAgent: () => void;
     botId: string;
     authDataMap: Record<string, string>;
@@ -82,6 +140,16 @@ interface LoginModalProps {
 }
 declare function LoginModal({ onConnectWallet, walletIcon }: LoginModalProps): react_jsx_runtime.JSX.Element;
 
+interface TelegramLoginWidgetProps {
+    botUsername: string;
+    onAuth: (data: TelegramLoginData) => void;
+    buttonSize?: "large" | "medium" | "small";
+    cornerRadius?: number;
+    showUserPhoto?: boolean;
+    requestAccess?: boolean;
+}
+declare function TelegramLoginWidget({ botUsername, onAuth, buttonSize, cornerRadius, showUserPhoto, requestAccess, }: TelegramLoginWidgetProps): react_jsx_runtime.JSX.Element;
+
 interface GrpcExchangeTransportConfig {
     isTestnet?: boolean;
     telegramClient: TelegramClient;
@@ -110,4 +178,4 @@ declare class GrpcExchangeTransport implements IRequestTransport {
 declare function createTelegramClient(config: HypurrConnectConfig): TelegramClient;
 declare function createStaticClient(config: HypurrConnectConfig): StaticClient;
 
-export { type AuthMethod, GrpcExchangeTransport, type GrpcExchangeTransportConfig, type HypurrConnectConfig, HypurrConnectProvider, type HypurrConnectState, type HypurrUser, LoginModal, type LoginModalProps, type SignTypedDataFn, type StoredAgent, type TelegramLoginData, createStaticClient, createTelegramClient, useHypurrConnect };
+export { type AuthMethod, type EoaSigner, GrpcExchangeTransport, type GrpcExchangeTransportConfig, type HypurrConnectConfig, HypurrConnectProvider, type HypurrConnectState, type HypurrUser, LoginModal, type LoginModalProps, type SignTypedDataFn, type StoredAgent, type TelegramLoginData, TelegramLoginWidget, type TelegramLoginWidgetProps, createEoaSigner, createStaticClient, createTelegramClient, useHypurrConnect };