txflow-sdk 0.2.1 → 0.2.2

package/README.md

@@ -10,7 +10,12 @@ npm install txflow-sdk
 
 ## Quick Start
 
-TxFlow uses an **agent wallet pattern**: a user wallet authorizes a temporary agent wallet via EIP-712 signature, and all subsequent trading actions are signed by the agent wallet.
+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.
+- **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.
 
 ```typescript
 import { TxFlowClient } from "txflow-sdk";
@@ -23,10 +28,10 @@ const client = new TxFlowClient({
   privateKey: agentWallet.privateKey,
 });
 
-// Step 1: Authorize the agent wallet (one-time)
+// Step 1: User wallet authorizes the agent wallet (one-time)
 await client.approveAgent(userWallet);
 
-// Step 2: Place orders using the agent wallet
+// Step 2: Agent wallet places orders (no user wallet needed)
 const result = await client.placeOrder({
   asset: 1,       // Asset index (use getPerpMeta to look up)
   isBuy: true,
@@ -35,13 +40,16 @@ const result = await client.placeOrder({
   reduceOnly: false,
   timeInForce: "gtc",
 });
+
+// User wallet is needed for fund operations
+await client.withdraw(userWallet, { destination: "0x...", amount: "100" });
 ```
 
 ## Configuration
 
 ```typescript
 const client = new TxFlowClient({
-  privateKey: "0x...",             // Agent wallet private key (required)
+  privateKey: "0x...",             // Agent wallet private key (required, 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)
@@ -67,7 +75,9 @@ All signing logic, EIP-712 domains, and API calls adapt automatically based on t
 
 ## API Reference
 
-### Trading
+### Trading (Agent Wallet)
+
+These methods are signed by the **agent wallet** (the `privateKey` provided in the constructor). The agent must be authorized by the user wallet via `approveAgent` before use.
 
 #### `placeOrder(params)`
 
@@ -118,7 +128,7 @@ await client.modifyOrder({
 });
 ```
 
-### Account Settings
+### Account Settings (Agent Wallet)
 
 #### `updateLeverage(params)`
 
@@ -132,12 +142,14 @@ await client.updateLeverage({ asset: 1, leverage: 10 });
 await client.updateMarginMode({ asset: 1, isCross: true });
 ```
 
-### User Actions
+### User Actions (User Wallet)
 
-These methods require the **user wallet** (not the agent 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.
 
 #### `approveAgent(userWallet, params?)`
 
+Authorizes the agent wallet for trading. Must be called once before the agent can trade.
+
 ```typescript
 await client.approveAgent(userWallet, {
   agentAddress: "0x...", // defaults to SDK agent address
@@ -147,6 +159,8 @@ await client.approveAgent(userWallet, {
 
 #### `withdraw(userWallet, params)`
 
+Withdraw USDC to an external address. Minimum amount is 2 USDC.
+
 ```typescript
 await client.withdraw(userWallet, {
   destination: "0x...",
@@ -156,6 +170,8 @@ await client.withdraw(userWallet, {
 
 #### `transferToken(userWallet, params)`
 
+Transfer USDC between your own perp and spot accounts.
+
 ```typescript
 await client.transferToken(userWallet, {
   amount: "100",
@@ -166,6 +182,8 @@ await client.transferToken(userWallet, {
 
 #### `sendToken(userWallet, params)`
 
+Send USDC to another user's address.
+
 ```typescript
 await client.sendToken(userWallet, {
   toAddress: "0x...",
@@ -324,8 +342,8 @@ Or if installed globally via npm:
 
 | Variable | Required | Description |
 |---|---|---|
-| `TXFLOW_AGENT_PRIVATE_KEY` | Yes | Agent wallet private key for signing trades |
-| `TXFLOW_USER_PRIVATE_KEY` | No | User wallet private key (only for `approve_agent`) |
+| `TXFLOW_AGENT_PRIVATE_KEY` | Yes | Agent wallet private key (trading only: orders, cancels, leverage, margin) |
+| `TXFLOW_USER_PRIVATE_KEY` | No | User wallet private key (for `approve_agent`, withdrawals, and transfers) |
 | `TXFLOW_BASE_URL` | No | API URL (default: `https://testnet-api.txflow.net`) |
 
 ### Available Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "txflow-sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TypeScript SDK for TxFlow perpetual DEX with EIP-712 signing and MCP server",
   "type": "module",
   "main": "dist/index.js",