@megaflow-labs/sdk 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,54 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.2] – 2026-02-28
+
+### Improvements — Developer Experience
+
+#### Added `connectWithPrivateKey` convenience method
+- You can now connect the `MegaFlowBuilder` and `MegaFlowClient` directly with a private key hex string, without needing to manually import `privateKeyToAccount` or create account objects.
+
+#### Expanded viem re-exports
+- Re-exported `parseAbi`, `parseAbiItem`, `parseAbiParameters` (ABI helpers)
+- Re-exported `createPublicClient`, `createWalletClient`, `http`, `webSocket` (Client factories)
+- Re-exported `Chain`, `decodeAbiParameters` (Types and Encoding)
+- This allows developers to rely **entirely** on the SDK imports for script and dapp building, eliminating duplicate `viem` dependencies.
+
+---
+
+## [0.1.1] – 2026-02-26
+
+### Improvements — Developer Experience
+
+#### Zero external imports (single SDK import pattern)
+- Added `MegaFlowClient.fromPrivateKey(privateKey)` static factory — no need to import `privateKeyToAccount` from viem
+- Added `MegaFlowClient.fromMnemonic(mnemonic)` static factory — create a client from a BIP-39 phrase in one line
+- Added `client.address` getter — access the connected account's address without reaching into viem internals
+
+#### viem re-exports
+The most commonly needed viem utilities are now re-exported from `@megaflow-labs/sdk` directly:
+- **Account factories**: `privateKeyToAccount`, `mnemonicToAccount`, `hdKeyToAccount`
+- **Unit helpers**: `parseUnits`, `parseEther`, `formatUnits`, `formatEther`
+- **Address utilities**: `isAddress`, `getAddress`, `zeroAddress`
+- **Encoding**: `encodeFunctionData`, `decodeFunctionData`, `encodeAbiParameters`, `decodeAbiParameters`
+- **Types**: `Address`, `Hash`, `Hex`, `PublicClient`, `WalletClient`, `Account`, `TransactionReceipt`
+
+Before (v0.1.0):
+```typescript
+import { MegaFlowClient } from '@megaflow-labs/sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { parseUnits } from 'viem';
+const client = new MegaFlowClient().connectWithAccount(privateKeyToAccount('0x...'));
+```
+
+After (v0.1.1):
+```typescript
+import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
+const client = MegaFlowClient.fromPrivateKey('0x...');
+```
+
+---
+
 ## [0.1.0] – 2026-02-26
 
 ### Initial release

package/README.md

@@ -26,25 +26,21 @@ On standard EVM chains, sending multiple transactions requires multiple wallet c
 npm install @megaflow-labs/sdk
 ```
 
-> Requires `viem ^2.0.0` (peer dependency) and Node.js ≥ 18.
+> **Node.js ≥ 18** required. `viem` is a peer dependency — but all commonly used viem utilities are **re-exported from the SDK** so you rarely need to install it separately.
 
 ---
 
 ## Quick Start
 
 ```typescript
-import { MegaFlowClient, MEGAETH_TOKENS } from '@megaflow-labs/sdk';
-import { privateKeyToAccount } from 'viem/accounts';
-import { parseUnits, parseEther } from 'viem';
+import { MegaFlowClient, MEGAETH_TOKENS, parseUnits, parseEther } from '@megaflow-labs/sdk';
 
-const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
-
-// Zero-config: connects to MegaETH Mainnet automatically
-const client = new MegaFlowClient().connectWithAccount(account);
+// fromPrivateKey() creates a fully connected client in one line
+const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
 
 // Read on-chain state
-const balance = await client.getTokenBalance(MEGAETH_TOKENS.WETH, account.address);
-const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+const balance = await client.getTokenBalance(MEGAETH_TOKENS.WETH, client.address!);
+const allowance = await client.getAllowance(USDC, client.address!, DEX_ROUTER);
 
 // Build, simulate, and execute — all in one chain
 const result = await client
@@ -55,7 +51,7 @@ const result = await client
     amountIn: parseUnits('100', 6),
     amountOutMin: parseEther('0.03'),
     path: [USDC, MEGAETH_TOKENS.WETH],
-    to: account.address,
+    to: client.address!,
   })
   .executeSync(); // instant receipt on MegaETH (~10ms)
 
@@ -63,6 +59,13 @@ console.log(`Tx hash: ${result.receipt.transactionHash}`);
 console.log(`Gas used: ${result.gasUsed}`);
 ```
 
+> **Using an existing viem account or WalletClient?** Both still work:
+> ```typescript
+> import { MegaFlowClient, privateKeyToAccount } from '@megaflow-labs/sdk';
+> const client = new MegaFlowClient().connectWithAccount(privateKeyToAccount('0x...'));
+> // or: .connect(myExistingWalletClient)
+> ```
+
 ---
 
 ## Core Concepts
@@ -94,15 +97,16 @@ const result = await builder.execute();
 
 Stateful high-level client. Extends MegaFlowBuilder with token reads, nonce management, and WebSocket support.
 
+**Factory methods (v0.1.1+):**
+
 ```typescript
-import { MegaFlowClient } from '@megaflow-labs/sdk';
+import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
 
-const client = new MegaFlowClient({ debug: true });
-client.connectWithAccount(account);
+// From private key
+const client = MegaFlowClient.fromPrivateKey('0xYOUR_KEY');
 
-// Read token state
-const bal = await client.getTokenBalance(token, address);
-const allowance = await client.getAllowance(token, address, spender);
+// From mnemonic
+const client2 = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
 
 // Batch transfers to multiple recipients in one tx
 const result = await client
@@ -116,6 +120,22 @@ const result = await client
 
 ---
 
+## What's re-exported from viem
+
+You can import all of these directly from `@megaflow-labs/sdk` — **no separate `viem` install needed**:
+
+| Category | Exports |
+|---|---|
+| **Account factories** | `privateKeyToAccount`, `mnemonicToAccount`, `hdKeyToAccount` |
+| **Unit helpers** | `parseUnits`, `parseEther`, `formatUnits`, `formatEther` |
+| **ABI helpers** | `parseAbi`, `parseAbiItem`, `parseAbiParameters` |
+| **Client factories** | `createPublicClient`, `createWalletClient`, `http`, `webSocket` |
+| **Address utilities** | `isAddress`, `getAddress`, `zeroAddress` |
+| **Encoding** | `encodeFunctionData`, `decodeFunctionData`, `encodeAbiParameters`, `decodeAbiParameters` |
+| **Types** | `Address`, `Hash`, `Hex`, `Chain`, `PublicClient`, `WalletClient`, `Account`, `TransactionReceipt` |
+
+---
+
 ## API Reference
 
 ### Execution Methods
@@ -246,11 +266,41 @@ const client = new MegaFlowClient({ rpcUrl: 'https://your-rpc.example.com' });
 
 ---
 
+## Examples
+
+See the **[megaflow-labs/examples](https://github.com/megaflow-labs/examples)** repository for 14 working TypeScript scripts covering real DeFi patterns:
+
+| Script | Pattern |
+|---|---|
+| `04-yield-optimizer` | Wrap + Approve + Supply to Aave in one tx |
+| `05-leverage-loop` | Flashloan-style leverage loop without smart contracts |
+| `06-nft-sweep-and-stake` | Buy NFT + stake atomically |
+| `07-token-snipe-and-protect` | Snipe + stop-loss authorization |
+| `08-bridge-intent` | Swap + bridge to L1 in one signature |
+| `09-flash-arbitrage` | Zero-risk EOA arbitrage across two DEXes |
+| `10-debt-repayment` | Liquidation rescue (swap illiquid → repay) |
+| `11-airdrop-claim-and-sell` | Claim + sell before price collapses |
+| `12-payroll-batch` | Treasury swap + pay 50 contributors |
+| `13-portfolio-rebalance` | Multi-sell → single target buy |
+| `14-options-payoff` | Conditional options exercise |
+
+**Clone and run:**
+```bash
+git clone https://github.com/megaflow-labs/examples
+cd examples && npm install
+cp .env.example .env   # add your PRIVATE_KEY
+npm run 04-yield
+```
+
+---
+
 ## Links
 
 - **Website:** [megaflow.space](https://megaflow.space)
+- **Examples:** [github.com/megaflow-labs/examples](https://github.com/megaflow-labs/examples)
 - **GitHub:** [github.com/megaflow-labs](https://github.com/megaflow-labs)
 - **NPM:** [@megaflow-labs/sdk](https://www.npmjs.com/package/@megaflow-labs/sdk)
+- **AI Context:** [llms.txt](https://github.com/megaflow-labs/sdk/blob/main/llms.txt)
 
 ---
 

package/dist/index.d.mts

@@ -1,4 +1,6 @@
 import { Chain, Address, Hex, Hash, TransactionReceipt, PublicClient, WalletClient, Account } from 'viem';
+export { Account, Address, Chain, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, http, isAddress, numberToHex, parseAbi, parseAbiItem, parseAbiParameters, parseEther, parseUnits, webSocket, zeroAddress } from 'viem';
+export { hdKeyToAccount, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
 /**
  * MegaETH Chain Definitions
@@ -1288,8 +1290,13 @@ declare class MegaFlowBuilder {
      */
     connectWithAccount(account: Account, rpcUrl?: string): this;
     /**
-     * Disconnect the wallet (for cleanup).
+     * Connect using a raw private key hex string.
+     * The most convenient way to connect in scripts — no viem import needed.
+     *
+     * @example
+     * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
      */
+    connectWithPrivateKey(privateKey: `0x${string}`, rpcUrl?: string): this;
     disconnect(): this;
     /**
      * Add a raw call (pre-encoded calldata).
@@ -1472,26 +1479,26 @@ declare class MegaFlowBuilder {
  * - ERC20 balance/allowance reads
  * - Multicall token state fetching
  *
- * @example
+ * @example Zero-config (recommended)
  * ```typescript
- * import { MegaFlowClient } from '@megaflow-labs/sdk';
- * import { privateKeyToAccount } from 'viem/accounts';
- *
- * const account = privateKeyToAccount('0x...');
- *
- * // Zero-config: uses MegaETH Mainnet by default
- * const client = new MegaFlowClient().connectWithAccount(account);
+ * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
  *
- * // Read state
- * const balance = await client.getTokenBalance(USDC, account.address);
- * const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+ * // One import, no viem required
+ * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
  *
- * // Build + execute in one call
  * const result = await client.batch()
- *   .safeApprove(USDC, DEX_ROUTER, amountIn, allowance)
+ *   .safeApprove(USDC, DEX_ROUTER, parseUnits('100', 6), 0n)
  *   .swapExactTokensForTokens({ ... })
  *   .executeSync(); // instant receipt on MegaETH
  * ```
+ *
+ * @example With existing viem account
+ * ```typescript
+ * import { MegaFlowClient } from '@megaflow-labs/sdk';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const client = new MegaFlowClient().connectWithAccount(privateKeyToAccount('0x...'));
+ * ```
  */
 
 declare class MegaFlowClient {
@@ -1501,6 +1508,30 @@ declare class MegaFlowClient {
     private wsClient?;
     private nonceCache;
     constructor(config?: MegaFlowClientConfig);
+    /**
+     * Create a client from a raw private key.
+     * Eliminates the need to import `privateKeyToAccount` from viem/accounts.
+     *
+     * @example
+     * ```typescript
+     * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
+     * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
+     * ```
+     */
+    static fromPrivateKey(privateKey: Hex, config?: MegaFlowClientConfig): MegaFlowClient;
+    /**
+     * Create a client from a BIP-39 mnemonic phrase.
+     *
+     * @example
+     * ```typescript
+     * const client = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
+     * ```
+     */
+    static fromMnemonic(mnemonic: string, config?: MegaFlowClientConfig): MegaFlowClient;
+    /**
+     * The connected account's address, or undefined if not yet connected.
+     */
+    get address(): Address | undefined;
     connectWithAccount(account: Account, rpcUrl?: string): this;
     connect(walletClient: WalletClient): this;
     /**
@@ -1588,26 +1619,23 @@ declare class MegaFlowClient {
  * atomic transaction through the MegaRouter contract. All operations
  * either succeed together or revert together.
  *
- * @example Quick start
+ * @example Quick start — single import
  * ```typescript
- * import { MegaFlowClient } from '@megaflow-labs/sdk';
- * import { privateKeyToAccount } from 'viem/accounts';
- *
- * const account = privateKeyToAccount('0x...');
+ * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
  *
- * // Zero-config: uses MegaETH Mainnet by default
- * const client = new MegaFlowClient().connectWithAccount(account);
+ * // No viem import needed — fromPrivateKey handles it internally
+ * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
  *
- * const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+ * const allowance = await client.getAllowance(USDC, client.address!, DEX_ROUTER);
  *
  * const result = await client.batch()
  *   .safeApprove(USDC, DEX_ROUTER, parseUnits('100', 6), allowance)
  *   .swapExactTokensForTokens({
  *     router: DEX_ROUTER,
  *     amountIn: parseUnits('100', 6),
- *     amountOutMin: parseEther('0.03'),
+ *     amountOutMin: parseUnits('0.03', 18),
  *     path: [USDC, WETH],
- *     to: account.address,
+ *     to: client.address!,
  *   })
  *   .executeSync(); // instant receipt on MegaETH
  * ```

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { Chain, Address, Hex, Hash, TransactionReceipt, PublicClient, WalletClient, Account } from 'viem';
+export { Account, Address, Chain, Hash, Hex, PublicClient, TransactionReceipt, WalletClient, createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, formatUnits, getAddress, hexToBigInt, http, isAddress, numberToHex, parseAbi, parseAbiItem, parseAbiParameters, parseEther, parseUnits, webSocket, zeroAddress } from 'viem';
+export { hdKeyToAccount, mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
 /**
  * MegaETH Chain Definitions
@@ -1288,8 +1290,13 @@ declare class MegaFlowBuilder {
      */
     connectWithAccount(account: Account, rpcUrl?: string): this;
     /**
-     * Disconnect the wallet (for cleanup).
+     * Connect using a raw private key hex string.
+     * The most convenient way to connect in scripts — no viem import needed.
+     *
+     * @example
+     * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
      */
+    connectWithPrivateKey(privateKey: `0x${string}`, rpcUrl?: string): this;
     disconnect(): this;
     /**
      * Add a raw call (pre-encoded calldata).
@@ -1472,26 +1479,26 @@ declare class MegaFlowBuilder {
  * - ERC20 balance/allowance reads
  * - Multicall token state fetching
  *
- * @example
+ * @example Zero-config (recommended)
  * ```typescript
- * import { MegaFlowClient } from '@megaflow-labs/sdk';
- * import { privateKeyToAccount } from 'viem/accounts';
- *
- * const account = privateKeyToAccount('0x...');
- *
- * // Zero-config: uses MegaETH Mainnet by default
- * const client = new MegaFlowClient().connectWithAccount(account);
+ * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
  *
- * // Read state
- * const balance = await client.getTokenBalance(USDC, account.address);
- * const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+ * // One import, no viem required
+ * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
  *
- * // Build + execute in one call
  * const result = await client.batch()
- *   .safeApprove(USDC, DEX_ROUTER, amountIn, allowance)
+ *   .safeApprove(USDC, DEX_ROUTER, parseUnits('100', 6), 0n)
  *   .swapExactTokensForTokens({ ... })
  *   .executeSync(); // instant receipt on MegaETH
  * ```
+ *
+ * @example With existing viem account
+ * ```typescript
+ * import { MegaFlowClient } from '@megaflow-labs/sdk';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const client = new MegaFlowClient().connectWithAccount(privateKeyToAccount('0x...'));
+ * ```
  */
 
 declare class MegaFlowClient {
@@ -1501,6 +1508,30 @@ declare class MegaFlowClient {
     private wsClient?;
     private nonceCache;
     constructor(config?: MegaFlowClientConfig);
+    /**
+     * Create a client from a raw private key.
+     * Eliminates the need to import `privateKeyToAccount` from viem/accounts.
+     *
+     * @example
+     * ```typescript
+     * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
+     * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
+     * ```
+     */
+    static fromPrivateKey(privateKey: Hex, config?: MegaFlowClientConfig): MegaFlowClient;
+    /**
+     * Create a client from a BIP-39 mnemonic phrase.
+     *
+     * @example
+     * ```typescript
+     * const client = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
+     * ```
+     */
+    static fromMnemonic(mnemonic: string, config?: MegaFlowClientConfig): MegaFlowClient;
+    /**
+     * The connected account's address, or undefined if not yet connected.
+     */
+    get address(): Address | undefined;
     connectWithAccount(account: Account, rpcUrl?: string): this;
     connect(walletClient: WalletClient): this;
     /**
@@ -1588,26 +1619,23 @@ declare class MegaFlowClient {
  * atomic transaction through the MegaRouter contract. All operations
  * either succeed together or revert together.
  *
- * @example Quick start
+ * @example Quick start — single import
  * ```typescript
- * import { MegaFlowClient } from '@megaflow-labs/sdk';
- * import { privateKeyToAccount } from 'viem/accounts';
- *
- * const account = privateKeyToAccount('0x...');
+ * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
  *
- * // Zero-config: uses MegaETH Mainnet by default
- * const client = new MegaFlowClient().connectWithAccount(account);
+ * // No viem import needed — fromPrivateKey handles it internally
+ * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
  *
- * const allowance = await client.getAllowance(USDC, account.address, DEX_ROUTER);
+ * const allowance = await client.getAllowance(USDC, client.address!, DEX_ROUTER);
  *
  * const result = await client.batch()
  *   .safeApprove(USDC, DEX_ROUTER, parseUnits('100', 6), allowance)
  *   .swapExactTokensForTokens({
  *     router: DEX_ROUTER,
  *     amountIn: parseUnits('100', 6),
- *     amountOutMin: parseEther('0.03'),
+ *     amountOutMin: parseUnits('0.03', 18),
  *     path: [USDC, WETH],
- *     to: account.address,
+ *     to: client.address!,
  *   })
  *   .executeSync(); // instant receipt on MegaETH
  * ```

package/dist/index.js

@@ -45,17 +45,40 @@ __export(index_exports, {
   createMegaFlowClientTestnet: () => createMegaFlowClientTestnet,
   createMegaFlowMainnet: () => createMegaFlowMainnet,
   createMegaFlowTestnet: () => createMegaFlowTestnet,
+  createPublicClient: () => import_viem8.createPublicClient,
+  createWalletClient: () => import_viem8.createWalletClient,
   deadlineInMinutes: () => deadlineInMinutes,
+  decodeAbiParameters: () => import_viem9.decodeAbiParameters,
+  decodeFunctionData: () => import_viem9.decodeFunctionData,
+  encodeAbiParameters: () => import_viem9.encodeAbiParameters,
+  encodeFunctionData: () => import_viem9.encodeFunctionData,
+  formatEther: () => import_viem5.formatEther,
+  formatUnits: () => import_viem5.formatUnits,
+  getAddress: () => import_viem7.getAddress,
   getKyberQuote: () => getKyberQuote,
+  hdKeyToAccount: () => import_accounts3.hdKeyToAccount,
+  hexToBigInt: () => import_viem5.hexToBigInt,
+  http: () => import_viem8.http,
+  isAddress: () => import_viem7.isAddress,
   isUserRejection: () => isUserRejection,
   isValidAddress: () => isValidAddress,
   isValidHex: () => isValidHex,
   megaethChains: () => megaethChains,
   megaethMainnet: () => megaethMainnet,
   megaethTestnet: () => megaethTestnet,
+  mnemonicToAccount: () => import_accounts3.mnemonicToAccount,
+  numberToHex: () => import_viem5.numberToHex,
+  parseAbi: () => import_viem6.parseAbi,
+  parseAbiItem: () => import_viem6.parseAbiItem,
+  parseAbiParameters: () => import_viem6.parseAbiParameters,
   parseBatchExecutedEvent: () => parseBatchExecutedEvent,
   parseCallExecutedEvents: () => parseCallExecutedEvents,
-  parseCallResults: () => parseCallResults
+  parseCallResults: () => parseCallResults,
+  parseEther: () => import_viem5.parseEther,
+  parseUnits: () => import_viem5.parseUnits,
+  privateKeyToAccount: () => import_accounts3.privateKeyToAccount,
+  webSocket: () => import_viem8.webSocket,
+  zeroAddress: () => import_viem7.zeroAddress
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -494,6 +517,7 @@ var MegaFlowError = class extends Error {
 
 // src/builder.ts
 var import_viem3 = require("viem");
+var import_accounts = require("viem/accounts");
 var MegaFlowBuilder = class {
   constructor(config = {}) {
     this.calls = [];
@@ -533,8 +557,16 @@ var MegaFlowBuilder = class {
     return this;
   }
   /**
-   * Disconnect the wallet (for cleanup).
+   * Connect using a raw private key hex string.
+   * The most convenient way to connect in scripts — no viem import needed.
+   *
+   * @example
+   * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
    */
+  connectWithPrivateKey(privateKey, rpcUrl) {
+    const account = (0, import_accounts.privateKeyToAccount)(privateKey);
+    return this.connectWithAccount(account, rpcUrl);
+  }
   disconnect() {
     this.walletClient = void 0;
     return this;
@@ -1078,7 +1110,8 @@ var MegaFlowBuilder = class {
 // src/client.ts
 var import_viem4 = require("viem");
 var import_actions = require("viem/actions");
-var MegaFlowClient = class {
+var import_accounts2 = require("viem/accounts");
+var MegaFlowClient = class _MegaFlowClient {
   constructor(config = {}) {
     // Local nonce cache: address → last used nonce
     this.nonceCache = /* @__PURE__ */ new Map();
@@ -1100,8 +1133,43 @@ var MegaFlowClient = class {
     }
   }
   // ==========================================================================
+  // Static factories — zero external imports needed
+  // ==========================================================================
+  /**
+   * Create a client from a raw private key.
+   * Eliminates the need to import `privateKeyToAccount` from viem/accounts.
+   *
+   * @example
+   * ```typescript
+   * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
+   * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
+   * ```
+   */
+  static fromPrivateKey(privateKey, config = {}) {
+    const account = (0, import_accounts2.privateKeyToAccount)(privateKey);
+    return new _MegaFlowClient(config).connectWithAccount(account);
+  }
+  /**
+   * Create a client from a BIP-39 mnemonic phrase.
+   *
+   * @example
+   * ```typescript
+   * const client = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
+   * ```
+   */
+  static fromMnemonic(mnemonic, config = {}) {
+    const account = (0, import_accounts2.mnemonicToAccount)(mnemonic);
+    return new _MegaFlowClient(config).connectWithAccount(account);
+  }
+  // ==========================================================================
   // Connection
   // ==========================================================================
+  /**
+   * The connected account's address, or undefined if not yet connected.
+   */
+  get address() {
+    return this.walletClient?.account?.address;
+  }
   connectWithAccount(account, rpcUrl) {
     const chain = this.config.chain ?? megaethMainnet;
     this.walletClient = (0, import_viem4.createWalletClient)({
@@ -1316,6 +1384,12 @@ var MegaFlowClient = class {
 };
 
 // src/index.ts
+var import_accounts3 = require("viem/accounts");
+var import_viem5 = require("viem");
+var import_viem6 = require("viem");
+var import_viem7 = require("viem");
+var import_viem8 = require("viem");
+var import_viem9 = require("viem");
 function createMegaFlow(config) {
   return new MegaFlowBuilder(config);
 }
@@ -1361,15 +1435,38 @@ function createMegaFlowClientTestnet(routerAddress, rpcUrl) {
   createMegaFlowClientTestnet,
   createMegaFlowMainnet,
   createMegaFlowTestnet,
+  createPublicClient,
+  createWalletClient,
   deadlineInMinutes,
+  decodeAbiParameters,
+  decodeFunctionData,
+  encodeAbiParameters,
+  encodeFunctionData,
+  formatEther,
+  formatUnits,
+  getAddress,
   getKyberQuote,
+  hdKeyToAccount,
+  hexToBigInt,
+  http,
+  isAddress,
   isUserRejection,
   isValidAddress,
   isValidHex,
   megaethChains,
   megaethMainnet,
   megaethTestnet,
+  mnemonicToAccount,
+  numberToHex,
+  parseAbi,
+  parseAbiItem,
+  parseAbiParameters,
   parseBatchExecutedEvent,
   parseCallExecutedEvents,
-  parseCallResults
+  parseCallResults,
+  parseEther,
+  parseUnits,
+  privateKeyToAccount,
+  webSocket,
+  zeroAddress
 });

package/dist/index.mjs

@@ -441,6 +441,7 @@ import {
   encodeFunctionData,
   http
 } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
 var MegaFlowBuilder = class {
   constructor(config = {}) {
     this.calls = [];
@@ -480,8 +481,16 @@ var MegaFlowBuilder = class {
     return this;
   }
   /**
-   * Disconnect the wallet (for cleanup).
+   * Connect using a raw private key hex string.
+   * The most convenient way to connect in scripts — no viem import needed.
+   *
+   * @example
+   * builder.connectWithPrivateKey(process.env.PRIVATE_KEY!)
    */
+  connectWithPrivateKey(privateKey, rpcUrl) {
+    const account = privateKeyToAccount(privateKey);
+    return this.connectWithAccount(account, rpcUrl);
+  }
   disconnect() {
     this.walletClient = void 0;
     return this;
@@ -1030,7 +1039,8 @@ import {
   webSocket as webSocket2
 } from "viem";
 import { multicall } from "viem/actions";
-var MegaFlowClient = class {
+import { privateKeyToAccount as privateKeyToAccount2, mnemonicToAccount } from "viem/accounts";
+var MegaFlowClient = class _MegaFlowClient {
   constructor(config = {}) {
     // Local nonce cache: address → last used nonce
     this.nonceCache = /* @__PURE__ */ new Map();
@@ -1052,8 +1062,43 @@ var MegaFlowClient = class {
     }
   }
   // ==========================================================================
+  // Static factories — zero external imports needed
+  // ==========================================================================
+  /**
+   * Create a client from a raw private key.
+   * Eliminates the need to import `privateKeyToAccount` from viem/accounts.
+   *
+   * @example
+   * ```typescript
+   * import { MegaFlowClient, parseUnits } from '@megaflow-labs/sdk';
+   * const client = MegaFlowClient.fromPrivateKey('0xYOUR_PRIVATE_KEY');
+   * ```
+   */
+  static fromPrivateKey(privateKey, config = {}) {
+    const account = privateKeyToAccount2(privateKey);
+    return new _MegaFlowClient(config).connectWithAccount(account);
+  }
+  /**
+   * Create a client from a BIP-39 mnemonic phrase.
+   *
+   * @example
+   * ```typescript
+   * const client = MegaFlowClient.fromMnemonic('word1 word2 ... word12');
+   * ```
+   */
+  static fromMnemonic(mnemonic, config = {}) {
+    const account = mnemonicToAccount(mnemonic);
+    return new _MegaFlowClient(config).connectWithAccount(account);
+  }
+  // ==========================================================================
   // Connection
   // ==========================================================================
+  /**
+   * The connected account's address, or undefined if not yet connected.
+   */
+  get address() {
+    return this.walletClient?.account?.address;
+  }
   connectWithAccount(account, rpcUrl) {
     const chain = this.config.chain ?? megaethMainnet;
     this.walletClient = createWalletClient2({
@@ -1268,6 +1313,12 @@ var MegaFlowClient = class {
 };
 
 // src/index.ts
+import { privateKeyToAccount as privateKeyToAccount3, mnemonicToAccount as mnemonicToAccount2, hdKeyToAccount } from "viem/accounts";
+import { parseUnits, parseEther as parseEther2, formatUnits, formatEther, hexToBigInt, numberToHex } from "viem";
+import { parseAbi as parseAbi2, parseAbiItem, parseAbiParameters } from "viem";
+import { isAddress, getAddress, zeroAddress } from "viem";
+import { createPublicClient as createPublicClient3, createWalletClient as createWalletClient3, http as http3, webSocket as webSocket3 } from "viem";
+import { encodeFunctionData as encodeFunctionData2, decodeFunctionData, encodeAbiParameters, decodeAbiParameters as decodeAbiParameters2 } from "viem";
 function createMegaFlow(config) {
   return new MegaFlowBuilder(config);
 }
@@ -1312,15 +1363,38 @@ export {
   createMegaFlowClientTestnet,
   createMegaFlowMainnet,
   createMegaFlowTestnet,
+  createPublicClient3 as createPublicClient,
+  createWalletClient3 as createWalletClient,
   deadlineInMinutes,
+  decodeAbiParameters2 as decodeAbiParameters,
+  decodeFunctionData,
+  encodeAbiParameters,
+  encodeFunctionData2 as encodeFunctionData,
+  formatEther,
+  formatUnits,
+  getAddress,
   getKyberQuote,
+  hdKeyToAccount,
+  hexToBigInt,
+  http3 as http,
+  isAddress,
   isUserRejection,
   isValidAddress,
   isValidHex,
   megaethChains,
   megaethMainnet,
   megaethTestnet,
+  mnemonicToAccount2 as mnemonicToAccount,
+  numberToHex,
+  parseAbi2 as parseAbi,
+  parseAbiItem,
+  parseAbiParameters,
   parseBatchExecutedEvent,
   parseCallExecutedEvents,
-  parseCallResults
+  parseCallResults,
+  parseEther2 as parseEther,
+  parseUnits,
+  privateKeyToAccount3 as privateKeyToAccount,
+  webSocket3 as webSocket,
+  zeroAddress
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@megaflow-labs/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Batch transaction SDK for MegaETH — compose, simulate and execute multiple on-chain operations in a single atomic transaction.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",