txflow-sdk 0.2.1 → 0.2.3

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...",
@@ -188,10 +206,18 @@ const candles = await client.getCandleSnapshot({
   endTime: Date.now(),
 });
 const fees = await client.getUserFees("0xUSER_ADDRESS");
-const funding = await client.getFundingHistory({
+```
+
+### History
+
+```typescript
+const orderHistory = await client.getOrderHistory({
   user: "0xUSER_ADDRESS",
-  startTime: Date.now() - 86400000,
+  startTime: Date.now() - 30 * 86400000,
 });
+const tradeHistory = await client.getTradeHistory("0xUSER_ADDRESS");
+const fundingHistory = await client.getFundingHistory("0xUSER_ADDRESS");
+const ledger = await client.getUserNonFundingLedgerUpdates("0xUSER_ADDRESS");
 ```
 
 ### Testnet Faucet
@@ -324,8 +350,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/dist/client.d.ts

@@ -51,17 +51,20 @@ export declare class TxFlowClient {
         reduceOnly: boolean;
     }): Promise<InfoResponse>;
     getUserState(user: string): Promise<InfoResponse>;
-    getFundingHistory(params: {
-        user: string;
-        startTime: number;
-        endTime?: number;
-    }): Promise<InfoResponse>;
+    getFundingHistory(user: string): Promise<InfoResponse>;
     getUserFees(user: string): Promise<InfoResponse>;
     getReferral(user: string): Promise<InfoResponse>;
     getPerpMeta(dex?: string): Promise<InfoResponse>;
     getSpotMeta(dex?: string): Promise<InfoResponse>;
     getActiveAssetData(user: string, coin: string): Promise<InfoResponse>;
     getL2Book(coin: string | number): Promise<InfoResponse>;
+    getOrderHistory(params: {
+        user: string;
+        startTime: number;
+        endTime?: number;
+    }): Promise<InfoResponse>;
+    getTradeHistory(user: string): Promise<InfoResponse>;
+    getUserNonFundingLedgerUpdates(user: string): Promise<InfoResponse>;
     getCandleSnapshot(params: {
         coin: string;
         interval: string;

package/dist/client.js

@@ -344,8 +344,8 @@ export class TxFlowClient {
     async getUserState(user) {
         return this.postInfo({ type: "clearinghouseState", user });
     }
-    async getFundingHistory(params) {
-        return this.postInfo({ type: "userfunding", ...params });
+    async getFundingHistory(user) {
+        return this.postInfo({ type: "userFundings", user });
     }
     async getUserFees(user) {
         return this.postInfo({ type: "userfees", user });
@@ -365,6 +365,20 @@ export class TxFlowClient {
     async getL2Book(coin) {
         return this.postInfo({ type: "l2book", coin: String(coin) });
     }
+    async getOrderHistory(params) {
+        return this.postInfo({
+            type: "historicalOrders",
+            user: params.user,
+            startTime: params.startTime,
+            endTime: params.endTime ?? Date.now(),
+        });
+    }
+    async getTradeHistory(user) {
+        return this.postInfo({ type: "userFills", user });
+    }
+    async getUserNonFundingLedgerUpdates(user) {
+        return this.postInfo({ type: "userNonFundingLedgerUpdates", user });
+    }
     async getCandleSnapshot(params) {
         return this.postInfo({ type: "candleSnapshot", ...params });
     }

package/package.json

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