txflow-sdk 0.2.4 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ npm install txflow-sdk
 
 TxFlow uses an **agent wallet pattern** with two distinct wallets:
 
-- **User Wallet**: The main wallet that owns the funds. Required for authorization, withdrawals, and transfers.
+- **User Wallet**: The main wallet that owns the funds. Required for authorization, withdrawals, and transfers. Can be any `ethers.AbstractSigner` (private key, MetaMask, Privy, Turnkey, etc.).
 - **Agent Wallet**: A temporary wallet authorized by the user wallet. It only has **trading permissions** (place/cancel/modify orders, update leverage and margin mode). It cannot move funds.
 
 The user wallet signs an `ApproveAgent` message to grant the agent wallet trading rights. After that, all trading operations use the agent wallet's key.
@@ -47,14 +47,22 @@ await client.withdraw(userWallet, { destination: "0x...", amount: "100" });
 
 ## Configuration
 
+You can initialize the client with either a `privateKey` or a `signer`:
+
 ```typescript
+// Option A: Private key (for bots/scripts)
 const client = new TxFlowClient({
-  privateKey: "0x...",             // Agent wallet private key (required, trading only)
+  privateKey: "0x...",             // Agent wallet private key (trading only)
   baseUrl: "https://testnet-api.txflow.net", // API base URL (optional)
   isMainnet: true,                // Source identifier for signing (optional, default: true)
   vaultAddress: null,             // Vault address if applicable (optional)
   chainId: 1337,                  // L1 signing domain chain ID (optional)
 });
+
+// Option B: Any ethers.AbstractSigner (for browser wallets)
+const client = new TxFlowClient({
+  signer: myAgentSigner,          // Any ethers.AbstractSigner instance
+});
 ```
 
 ### Mainnet Migration
@@ -73,6 +81,75 @@ const client = new TxFlowClient({
 
 All signing logic, EIP-712 domains, and API calls adapt automatically based on the config.
 
+## Browser Wallet Integration
+
+The SDK accepts any `ethers.AbstractSigner` for user wallet operations (`approveAgent`, `withdraw`, `transferToken`, `sendToken`). This makes it compatible with MetaMask, Privy, Turnkey, and other wallet providers.
+
+### MetaMask / Injected Wallet
+
+```typescript
+import { TxFlowClient } from "txflow-sdk";
+import { ethers } from "ethers";
+
+// Connect to MetaMask
+const provider = new ethers.BrowserProvider(window.ethereum);
+const userSigner = await provider.getSigner(); // ethers.JsonRpcSigner
+
+// Generate a local agent wallet (trading only, no fund access)
+const agentWallet = ethers.Wallet.createRandom();
+// Persist agent key in localStorage so the user doesn't re-approve every session
+localStorage.setItem("txflow_agent_key", agentWallet.privateKey);
+
+const client = new TxFlowClient({
+  privateKey: agentWallet.privateKey,
+});
+
+// User's MetaMask signs the one-time agent authorization
+await client.approveAgent(userSigner);
+
+// All trading uses the local agent key (no MetaMask popups)
+await client.placeOrder({ asset: 1, isBuy: true, price: "50000", size: "0.01" });
+
+// Fund operations still go through MetaMask
+await client.withdraw(userSigner, { destination: "0x...", amount: "100" });
+```
+
+### Privy Embedded Wallet
+
+```typescript
+import { TxFlowClient } from "txflow-sdk";
+import { ethers } from "ethers";
+import { usePrivy, useWallets } from "@privy-io/react-auth";
+
+// Inside a React component
+const { wallets } = useWallets();
+const embeddedWallet = wallets.find((w) => w.walletClientType === "privy");
+
+// Get an ethers signer from Privy
+const privyProvider = await embeddedWallet.getEthersProvider();
+const userSigner = await privyProvider.getSigner(); // ethers.JsonRpcSigner
+
+// Generate a local agent wallet
+const stored = localStorage.getItem("txflow_agent_key");
+const agentWallet = stored
+  ? new ethers.Wallet(stored)
+  : ethers.Wallet.createRandom();
+localStorage.setItem("txflow_agent_key", agentWallet.privateKey);
+
+const client = new TxFlowClient({
+  privateKey: agentWallet.privateKey,
+});
+
+// Privy wallet signs the agent authorization (no browser extension needed)
+await client.approveAgent(userSigner);
+
+// Trading uses the local agent key (instant, no signing prompts)
+await client.placeOrder({ asset: 1, isBuy: true, price: "50000", size: "0.01" });
+
+// Fund operations go through Privy
+await client.withdraw(userSigner, { destination: "0x...", amount: "100" });
+```
+
 ## API Reference
 
 ### Trading (Agent Wallet)
@@ -144,7 +221,7 @@ await client.updateMarginMode({ asset: 1, isCross: true });
 
 ### User Actions (User Wallet)
 
-These methods require the **user wallet** to be passed explicitly. The user wallet is the main wallet that owns the funds and has full account control. The agent wallet **cannot** perform these operations.
+These methods require the **user wallet** to be passed explicitly. Any `ethers.AbstractSigner` is accepted (private key wallet, MetaMask signer, Privy signer, etc.). The agent wallet **cannot** perform these operations.
 
 #### `approveAgent(userWallet, params?)`
 

package/dist/client.d.ts

@@ -7,7 +7,7 @@ export declare class TxFlowClient {
     private vaultAddress;
     private chainId?;
     constructor(config: TxFlowConfig);
-    get address(): string;
+    getAddress(): Promise<string>;
     private postExchange;
     private postInfo;
     private buildOrderWire;
@@ -18,10 +18,10 @@ export declare class TxFlowClient {
     modifyOrder(params: ModifyOrderParams): Promise<ApiResponse>;
     updateLeverage(params: UpdateLeverageParams): Promise<ApiResponse>;
     updateMarginMode(params: UpdateMarginModeParams): Promise<ApiResponse>;
-    approveAgent(userWallet: ethers.Wallet, params?: Partial<ApproveAgentParams>): Promise<ApiResponse>;
-    withdraw(userWallet: ethers.Wallet, params: WithdrawParams): Promise<ApiResponse>;
-    transferToken(userWallet: ethers.Wallet, params: TransferTokenParams): Promise<ApiResponse>;
-    sendToken(userWallet: ethers.Wallet, params: SendTokenParams): Promise<ApiResponse>;
+    approveAgent(userWallet: ethers.AbstractSigner, params?: Partial<ApproveAgentParams>): Promise<ApiResponse>;
+    withdraw(userWallet: ethers.AbstractSigner, params: WithdrawParams): Promise<ApiResponse>;
+    transferToken(userWallet: ethers.AbstractSigner, params: TransferTokenParams): Promise<ApiResponse>;
+    sendToken(userWallet: ethers.AbstractSigner, params: SendTokenParams): Promise<ApiResponse>;
     buildPlaceOrder(params: PlaceOrderParams): Promise<SignedRequest>;
     buildPlaceBatchOrders(orderParams: PlaceOrderParams[]): Promise<SignedRequest>;
     buildCancelOrder(params: CancelOrderParams): Promise<SignedRequest>;

package/dist/client.js

@@ -8,14 +8,14 @@ export class TxFlowClient {
     vaultAddress;
     chainId;
     constructor(config) {
-        this.wallet = new ethers.Wallet(config.privateKey);
+        this.wallet = config.signer ?? new ethers.Wallet(config.privateKey);
         this.baseUrl = config.baseUrl ?? TESTNET_API_URL;
         this.isMainnet = config.isMainnet ?? true;
         this.vaultAddress = config.vaultAddress ?? null;
         this.chainId = config.chainId;
     }
-    get address() {
-        return this.wallet.address;
+    async getAddress() {
+        return this.wallet.getAddress();
     }
     async postExchange(body) {
         const resp = await fetch(`${this.baseUrl}/exchange`, {
@@ -131,7 +131,7 @@ export class TxFlowClient {
         });
     }
     async approveAgent(userWallet, params) {
-        const agentAddress = params?.agentAddress ?? this.wallet.address;
+        const agentAddress = params?.agentAddress ?? await this.wallet.getAddress();
         const agentName = params?.agentName ?? "TradeAgent";
         const nonce = params?.nonce ?? Date.now();
         const message = {
@@ -386,7 +386,7 @@ export class TxFlowClient {
         const resp = await fetch(`${this.baseUrl}/request-fund`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ address: address ?? this.wallet.address }),
+            body: JSON.stringify({ address: address ?? await this.wallet.getAddress() }),
         });
         return resp.json();
     }

package/dist/signing.d.ts

@@ -1,10 +1,10 @@
 import { ethers } from "ethers";
 import type { Signature } from "./types.js";
 export declare function actionHash(action: unknown, vaultAddress: string | null, nonce: number): string;
-export declare function signL1Action(wallet: ethers.Wallet, action: unknown, vaultAddress: string | null, nonce: number, isMainnet: boolean, chainId?: number): Promise<Signature>;
+export declare function signL1Action(wallet: ethers.AbstractSigner, action: unknown, vaultAddress: string | null, nonce: number, isMainnet: boolean, chainId?: number): Promise<Signature>;
 export declare function generateNonce(): number;
-export declare function createSign(wallet: ethers.Wallet, action: unknown, isMainnet: boolean, vaultAddress?: string | null, chainId?: number): Promise<{
+export declare function createSign(wallet: ethers.AbstractSigner, action: unknown, isMainnet: boolean, vaultAddress?: string | null, chainId?: number): Promise<{
     signature: Signature;
     nonce: number;
 }>;
-export declare function signUserAction(wallet: ethers.Wallet, domain: ethers.TypedDataDomain, types: Record<string, ethers.TypedDataField[]>, message: Record<string, unknown>): Promise<Signature>;
+export declare function signUserAction(wallet: ethers.AbstractSigner, domain: ethers.TypedDataDomain, types: Record<string, ethers.TypedDataField[]>, message: Record<string, unknown>): Promise<Signature>;

package/dist/types.d.ts

@@ -1,10 +1,15 @@
-export interface TxFlowConfig {
-    privateKey: string;
+export type TxFlowConfig = {
     baseUrl?: string;
     isMainnet?: boolean;
     vaultAddress?: string | null;
     chainId?: number;
-}
+} & ({
+    privateKey: string;
+    signer?: never;
+} | {
+    signer: import("ethers").AbstractSigner;
+    privateKey?: never;
+});
 export interface OrderWire {
     a: number;
     b: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "txflow-sdk",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "TypeScript SDK for TxFlow perpetual DEX with EIP-712 signing and MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -36,6 +36,10 @@
     "futures"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/andy-vibecoding/txflow-sdk.git"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@msgpack/msgpack": "^3.0.0-beta2",