txflow-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 andy-vibecoding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# txflow-sdk
+
+TypeScript SDK for [TxFlow](https://txflow-testnet.xyz) perpetual DEX with EIP-712 signing and MCP (Model Context Protocol) server.
+
+## Installation
+
+```bash
+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.
+
+```typescript
+import { TxFlowClient } from "txflow-sdk";
+import { ethers } from "ethers";
+
+const userWallet = new ethers.Wallet("0xUSER_PRIVATE_KEY");
+const agentWallet = new ethers.Wallet("0xAGENT_PRIVATE_KEY");
+
+const client = new TxFlowClient({
+  privateKey: agentWallet.privateKey,
+});
+
+// Step 1: Authorize the agent wallet (one-time)
+await client.approveAgent(userWallet);
+
+// Step 2: Place orders using the agent wallet
+const result = await client.placeOrder({
+  asset: 1,       // Asset index (use getPerpMeta to look up)
+  isBuy: true,
+  price: "50000",
+  size: "0.01",
+  reduceOnly: false,
+  timeInForce: "gtc",
+});
+```
+
+## Configuration
+
+```typescript
+const client = new TxFlowClient({
+  privateKey: "0x...",             // Agent wallet private key (required)
+  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)
+});
+```
+
+### Mainnet Migration
+
+When TxFlow launches mainnet, update the config:
+
+```typescript
+import { TxFlowClient, MAINNET_API_URL } from "txflow-sdk";
+
+const client = new TxFlowClient({
+  privateKey: "0x...",
+  baseUrl: MAINNET_API_URL,       // or the actual mainnet URL
+  chainId: 1337,                  // update if mainnet uses a different chain ID
+});
+```
+
+All signing logic, EIP-712 domains, and API calls adapt automatically based on the config.
+
+## API Reference
+
+### Trading
+
+#### `placeOrder(params)`
+
+```typescript
+await client.placeOrder({
+  asset: 1,
+  isBuy: true,
+  price: "50000",
+  size: "0.01",
+  reduceOnly: false,
+  timeInForce: "gtc", // "gtc" | "ioc" | "alo"
+});
+```
+
+#### `placeBatchOrders(params[])`
+
+```typescript
+await client.placeBatchOrders([
+  { asset: 1, isBuy: true, price: "50000", size: "0.01" },
+  { asset: 1, isBuy: false, price: "60000", size: "0.01" },
+]);
+```
+
+#### `cancelOrder(params)`
+
+```typescript
+await client.cancelOrder({ asset: 1, orderId: "123456" });
+```
+
+#### `cancelOrders(params[])`
+
+```typescript
+await client.cancelOrders([
+  { asset: 1, orderId: "123456" },
+  { asset: 1, orderId: "789012" },
+]);
+```
+
+#### `modifyOrder(params)`
+
+```typescript
+await client.modifyOrder({
+  orderId: "123456",
+  asset: 1,
+  isBuy: true,
+  price: "51000",
+  size: "0.02",
+});
+```
+
+### Account Settings
+
+#### `updateLeverage(params)`
+
+```typescript
+await client.updateLeverage({ asset: 1, leverage: 10 });
+```
+
+#### `updateMarginMode(params)`
+
+```typescript
+await client.updateMarginMode({ asset: 1, isCross: true });
+```
+
+### User Actions
+
+These methods require the **user wallet** (not the agent wallet).
+
+#### `approveAgent(userWallet, params?)`
+
+```typescript
+await client.approveAgent(userWallet, {
+  agentAddress: "0x...", // defaults to SDK agent address
+  agentName: "MyBot",    // defaults to "TradeAgent"
+});
+```
+
+#### `withdraw(userWallet, params)`
+
+```typescript
+await client.withdraw(userWallet, {
+  destination: "0x...",
+  amount: "100",
+});
+```
+
+#### `transferToken(userWallet, params)`
+
+```typescript
+await client.transferToken(userWallet, {
+  amount: "100",
+  fromAccountType: "perp",
+  toAccountType: "spot",
+});
+```
+
+#### `sendToken(userWallet, params)`
+
+```typescript
+await client.sendToken(userWallet, {
+  toAddress: "0x...",
+  amount: "50",
+});
+```
+
+### Queries
+
+```typescript
+const meta = await client.getPerpMeta();
+const state = await client.getUserState("0xUSER_ADDRESS");
+const orders = await client.getOpenOrders("0xUSER_ADDRESS");
+const book = await client.getL2Book(1);
+const assetData = await client.getActiveAssetData("0xUSER_ADDRESS", "1");
+const candles = await client.getCandleSnapshot({
+  coin: "BTC",
+  interval: "1h",
+  startTime: Date.now() - 86400000,
+  endTime: Date.now(),
+});
+const fees = await client.getUserFees("0xUSER_ADDRESS");
+const funding = await client.getFundingHistory({
+  user: "0xUSER_ADDRESS",
+  startTime: Date.now() - 86400000,
+});
+```
+
+### Testnet Faucet
+
+```typescript
+await client.requestFund("0xUSER_ADDRESS");
+```
+
+## Advanced: Low-Level Signing
+
+For custom integrations, the signing primitives are exported directly:
+
+```typescript
+import {
+  actionHash,
+  signL1Action,
+  createSign,
+  signUserAction,
+  getL1ActionDomain,
+  L1_ACTION_TYPES,
+  USER_ACTION_DOMAIN,
+  APPROVE_AGENT_TYPES,
+} from "txflow-sdk";
+
+// Compute action hash (MessagePack + nonce + vault encoding + keccak256)
+const hash = actionHash(action, vaultAddress, nonce);
+
+// Sign an L1 action (order, cancel, modify, leverage, margin mode)
+const sig = await signL1Action(wallet, action, vaultAddress, nonce, isMainnet, chainId);
+
+// Sign a user action (approve, withdraw, transfer)
+const sig = await signUserAction(wallet, domain, types, message);
+```
+
+### Signing Algorithm
+
+1. Remove trailing zeros from `p` and `s` string fields recursively
+2. MessagePack encode the action with BigInt64 support
+3. Append nonce as 8-byte big-endian uint64
+4. Append vault flag: `0x00` if null (9 extra bytes), or `0x01` + 20-byte address (29 extra bytes)
+5. Keccak256 hash the buffer
+6. Sign via EIP-712 typed data with the L1 action domain
+
+## MCP Server
+
+The SDK includes an MCP server for AI agent integration (e.g., Claude Desktop, Cursor, OpenClaw).
+
+### Setup
+
+Build the project first:
+
+```bash
+npm install && npm run build
+```
+
+### Configuration
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "txflow": {
+      "command": "node",
+      "args": ["/path/to/txflow-sdk/dist/mcp.js"],
+      "env": {
+        "TXFLOW_AGENT_PRIVATE_KEY": "0xAGENT_PRIVATE_KEY",
+        "TXFLOW_USER_PRIVATE_KEY": "0xUSER_PRIVATE_KEY",
+        "TXFLOW_BASE_URL": "https://testnet-api.txflow.net"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally via npm:
+
+```json
+{
+  "mcpServers": {
+    "txflow": {
+      "command": "txflow-mcp",
+      "env": {
+        "TXFLOW_AGENT_PRIVATE_KEY": "0xAGENT_PRIVATE_KEY",
+        "TXFLOW_USER_PRIVATE_KEY": "0xUSER_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| 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_BASE_URL` | No | API URL (default: `https://testnet-api.txflow.net`) |
+
+### Available Tools
+
+| Tool | Description |
+|---|---|
+| `place_order` | Place a perpetual futures order |
+| `cancel_order` | Cancel an open order |
+| `cancel_orders` | Cancel multiple orders |
+| `modify_order` | Modify an existing order |
+| `update_leverage` | Update leverage for an asset |
+| `update_margin_mode` | Switch cross/isolated margin |
+| `approve_agent` | Authorize agent wallet (requires user key) |
+| `get_open_orders` | List open orders for a user |
+| `get_user_state` | Get account state, positions, balances |
+| `get_perp_meta` | Get available assets and their indices |
+| `get_l2_book` | Get order book depth for a coin |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { ethers } from "ethers";
+import type { TxFlowConfig, PlaceOrderParams, CancelOrderParams, ModifyOrderParams, UpdateLeverageParams, UpdateMarginModeParams, ApproveAgentParams, WithdrawParams, TransferTokenParams, SendTokenParams, ApiResponse, InfoResponse } from "./types.js";
+export declare class TxFlowClient {
+    private wallet;
+    private baseUrl;
+    private isMainnet;
+    private vaultAddress;
+    private chainId?;
+    constructor(config: TxFlowConfig);
+    get address(): string;
+    private postExchange;
+    private postInfo;
+    private buildOrderWire;
+    placeOrder(params: PlaceOrderParams): Promise<ApiResponse>;
+    placeBatchOrders(orderParams: PlaceOrderParams[]): Promise<ApiResponse>;
+    cancelOrder(params: CancelOrderParams): Promise<ApiResponse>;
+    cancelOrders(params: CancelOrderParams[]): Promise<ApiResponse>;
+    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>;
+    getOpenOrders(user: string): Promise<InfoResponse>;
+    getMultiUserOpenOrders(users: string[]): Promise<InfoResponse>;
+    getMaxPositions(params: {
+        user: string;
+        asset: string;
+        orderType: string;
+        buyPrice: string;
+        sellPrice: string;
+        reduceOnly: boolean;
+    }): Promise<InfoResponse>;
+    getLiquidationPrices(params: {
+        user: string;
+        asset: string;
+        orderType: string;
+        buyPrice: string;
+        sellPrice: string;
+        buyQuantity: string;
+        sellQuantity: string;
+        reduceOnly: boolean;
+    }): Promise<InfoResponse>;
+    getUserState(user: string): Promise<InfoResponse>;
+    getFundingHistory(params: {
+        user: string;
+        startTime: number;
+        endTime?: number;
+    }): 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>;
+    getCandleSnapshot(params: {
+        coin: string;
+        interval: string;
+        startTime: number;
+        endTime: number;
+    }): Promise<InfoResponse>;
+    requestFund(address?: string): Promise<ApiResponse>;
+}

package/dist/client.js

@@ -0,0 +1,283 @@
+import { ethers } from "ethers";
+import { createSign, signUserAction } from "./signing.js";
+import { TESTNET_API_URL, USDC_TOKEN_ADDRESS, USER_ACTION_DOMAIN, APPROVE_AGENT_TYPES, WITHDRAW_TYPES, TRANSFER_TOKEN_TYPES, SEND_TOKEN_TYPES, } from "./constants.js";
+export class TxFlowClient {
+    wallet;
+    baseUrl;
+    isMainnet;
+    vaultAddress;
+    chainId;
+    constructor(config) {
+        this.wallet = 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 postExchange(body) {
+        const resp = await fetch(`${this.baseUrl}/exchange`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body, (_key, value) => typeof value === "bigint" ? Number(value) : value),
+        });
+        return resp.json();
+    }
+    async postInfo(body) {
+        const resp = await fetch(`${this.baseUrl}/info`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return resp.json();
+    }
+    buildOrderWire(params) {
+        return {
+            a: params.asset,
+            b: params.isBuy,
+            p: params.price,
+            s: params.size,
+            r: params.reduceOnly ?? false,
+            t: { limit: { tif: params.timeInForce ?? "gtc" } },
+        };
+    }
+    async placeOrder(params) {
+        const order = this.buildOrderWire(params);
+        const action = { grouping: "na", orders: [order] };
+        const { signature, nonce } = await createSign(this.wallet, action, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "order", grouping: "na", orders: [order], nonce },
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+        });
+    }
+    async placeBatchOrders(orderParams) {
+        const orders = orderParams.map((p) => this.buildOrderWire(p));
+        const action = { grouping: "na", orders };
+        const { signature, nonce } = await createSign(this.wallet, action, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "order", grouping: "na", orders, nonce },
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+        });
+    }
+    async cancelOrder(params) {
+        const cancelAction = {
+            cancels: [{ a: params.asset, o: BigInt(params.orderId) }],
+        };
+        const { signature, nonce } = await createSign(this.wallet, cancelAction, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "cancel", cancels: [{ a: params.asset, o: params.orderId }] },
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+            vaultAddress: this.vaultAddress,
+        });
+    }
+    async cancelOrders(params) {
+        const cancelAction = {
+            cancels: params.map((p) => ({ a: p.asset, o: BigInt(p.orderId) })),
+        };
+        const { signature, nonce } = await createSign(this.wallet, cancelAction, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: {
+                type: "cancel",
+                cancels: params.map((p) => ({ a: p.asset, o: p.orderId })),
+            },
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+            vaultAddress: this.vaultAddress,
+        });
+    }
+    async modifyOrder(params) {
+        const order = this.buildOrderWire({
+            asset: params.asset,
+            isBuy: params.isBuy,
+            price: params.price,
+            size: params.size,
+            reduceOnly: params.reduceOnly,
+            timeInForce: params.timeInForce,
+        });
+        const modifyAction = { oid: BigInt(params.orderId), order };
+        const { signature, nonce } = await createSign(this.wallet, modifyAction, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "modify", oid: params.orderId, order },
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+            vaultAddress: this.vaultAddress,
+        });
+    }
+    async updateLeverage(params) {
+        const action = { asset: params.asset, leverage: params.leverage };
+        const { signature, nonce } = await createSign(this.wallet, action, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "updateLeverage", ...action },
+            isFrontend: true,
+            vaultAddress: this.vaultAddress,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+        });
+    }
+    async updateMarginMode(params) {
+        const action = { asset: params.asset, isCross: params.isCross };
+        const { signature, nonce } = await createSign(this.wallet, action, this.isMainnet, this.vaultAddress, this.chainId);
+        return this.postExchange({
+            action: { type: "updateMarginMode", ...action },
+            isFrontend: true,
+            vaultAddress: this.vaultAddress,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+            nonce,
+        });
+    }
+    async approveAgent(userWallet, params) {
+        const agentAddress = params?.agentAddress ?? this.wallet.address;
+        const agentName = params?.agentName ?? "TradeAgent";
+        const nonce = params?.nonce ?? Date.now();
+        const message = {
+            ofinChain: "ofin",
+            agentAddress,
+            agentName,
+            nonce,
+        };
+        const signature = await signUserAction(userWallet, USER_ACTION_DOMAIN, APPROVE_AGENT_TYPES, message);
+        return this.postExchange({
+            action: {
+                type: "approveAgent",
+                agentAddress,
+                agentName,
+                nonce,
+                ofinChain: "ofin",
+            },
+            nonce,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+        });
+    }
+    async withdraw(userWallet, params) {
+        const nonce = Date.now();
+        const signatureChainId = params.signatureChainId ?? "0x66eee";
+        const message = {
+            ofinChain: "ofin",
+            destination: params.destination,
+            signatureChainId,
+            tokenAddress: USDC_TOKEN_ADDRESS,
+            amount: params.amount,
+            nonce,
+        };
+        const signature = await signUserAction(userWallet, USER_ACTION_DOMAIN, WITHDRAW_TYPES, message);
+        return this.postExchange({
+            action: {
+                type: "withdraw3",
+                ofinChain: "ofin",
+                signatureChainId,
+                destination: params.destination,
+                tokenAddress: USDC_TOKEN_ADDRESS,
+                amount: params.amount,
+                nonce,
+            },
+            nonce,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+        });
+    }
+    async transferToken(userWallet, params) {
+        const nonce = Date.now();
+        const token = `USDC:${USDC_TOKEN_ADDRESS}`;
+        const message = {
+            ofinChain: "ofin",
+            amount: params.amount,
+            fromAccountType: params.fromAccountType,
+            toAccountType: params.toAccountType,
+            token,
+            nonce,
+        };
+        const signature = await signUserAction(userWallet, USER_ACTION_DOMAIN, TRANSFER_TOKEN_TYPES, message);
+        return this.postExchange({
+            action: {
+                type: "transferToken",
+                ofinChain: "ofin",
+                amount: params.amount,
+                fromAccountType: params.fromAccountType,
+                toAccountType: params.toAccountType,
+                token,
+                nonce,
+            },
+            nonce,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+        });
+    }
+    async sendToken(userWallet, params) {
+        const nonce = Date.now();
+        const token = `USDC:${USDC_TOKEN_ADDRESS}`;
+        const message = {
+            ofinChain: "ofin",
+            toAddress: params.toAddress,
+            amount: params.amount,
+            fromAccountType: params.fromAccountType ?? "perp",
+            toAccountType: params.toAccountType ?? "perp",
+            token,
+            nonce,
+        };
+        const signature = await signUserAction(userWallet, USER_ACTION_DOMAIN, SEND_TOKEN_TYPES, message);
+        return this.postExchange({
+            action: {
+                type: "sendToken",
+                ofinChain: "ofin",
+                toAddress: params.toAddress,
+                amount: params.amount,
+                fromAccountType: params.fromAccountType ?? "perp",
+                toAccountType: params.toAccountType ?? "perp",
+                token,
+                nonce,
+            },
+            nonce,
+            signature: { r: signature.r, s: signature.s, v: signature.v },
+        });
+    }
+    async getOpenOrders(user) {
+        return this.postInfo({ type: "openorders", user });
+    }
+    async getMultiUserOpenOrders(users) {
+        return this.postInfo({ type: "multiuseropenorders", users, limit: "" });
+    }
+    async getMaxPositions(params) {
+        return this.postInfo({ type: "getmaxpositions", ...params });
+    }
+    async getLiquidationPrices(params) {
+        return this.postInfo({ type: "getliquidationprices", ...params });
+    }
+    async getUserState(user) {
+        return this.postInfo({ type: "clearinghouseState", user });
+    }
+    async getFundingHistory(params) {
+        return this.postInfo({ type: "userfunding", ...params });
+    }
+    async getUserFees(user) {
+        return this.postInfo({ type: "userfees", user });
+    }
+    async getReferral(user) {
+        return this.postInfo({ type: "referral", user });
+    }
+    async getPerpMeta(dex) {
+        return this.postInfo({ type: "perpmeta", dex: dex ?? "" });
+    }
+    async getSpotMeta(dex) {
+        return this.postInfo({ type: "spotmeta", dex: dex ?? "" });
+    }
+    async getActiveAssetData(user, coin) {
+        return this.postInfo({ type: "activeassetdata", user, coin });
+    }
+    async getL2Book(coin) {
+        return this.postInfo({ type: "l2book", coin: String(coin) });
+    }
+    async getCandleSnapshot(params) {
+        return this.postInfo({ type: "candleSnapshot", ...params });
+    }
+    async requestFund(address) {
+        const resp = await fetch(`${this.baseUrl}/request-fund`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ address: address ?? this.wallet.address }),
+        });
+        return resp.json();
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,47 @@
+export declare const TESTNET_API_URL = "https://testnet-api.txflow.net";
+export declare const MAINNET_API_URL = "https://api.txflow.net";
+export declare const USDC_TOKEN_ADDRESS = "0xd04f0d19E8FbA49cfA541E272F9C60a2ad720464";
+export declare const TESTNET_L1_CHAIN_ID = 1337;
+export declare const MAINNET_L1_CHAIN_ID = 1337;
+export declare function getL1ActionDomain(chainId?: number): {
+    name: "Exchange";
+    version: "1";
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+export declare const L1_ACTION_TYPES: {
+    Agent: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const USER_ACTION_DOMAIN: {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+export declare const APPROVE_AGENT_TYPES: {
+    ApproveAgent: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const WITHDRAW_TYPES: {
+    Withdraw3: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const TRANSFER_TOKEN_TYPES: {
+    TransferToken: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const SEND_TOKEN_TYPES: {
+    SendToken: {
+        name: string;
+        type: string;
+    }[];
+};

package/dist/constants.js

@@ -0,0 +1,64 @@
+export const TESTNET_API_URL = "https://testnet-api.txflow.net";
+export const MAINNET_API_URL = "https://api.txflow.net";
+export const USDC_TOKEN_ADDRESS = "0xd04f0d19E8FbA49cfA541E272F9C60a2ad720464";
+export const TESTNET_L1_CHAIN_ID = 1337;
+export const MAINNET_L1_CHAIN_ID = 1337;
+export function getL1ActionDomain(chainId = TESTNET_L1_CHAIN_ID) {
+    return {
+        name: "Exchange",
+        version: "1",
+        chainId,
+        verifyingContract: "0x0000000000000000000000000000000000000000",
+    };
+}
+export const L1_ACTION_TYPES = {
+    Agent: [
+        { name: "source", type: "string" },
+        { name: "connectionId", type: "bytes32" },
+    ],
+};
+export const USER_ACTION_DOMAIN = {
+    name: "Ofin",
+    version: "1",
+    chainId: 1,
+    verifyingContract: "0x0000000000000000000000000000000000000000",
+};
+export const APPROVE_AGENT_TYPES = {
+    ApproveAgent: [
+        { name: "ofinChain", type: "string" },
+        { name: "agentAddress", type: "address" },
+        { name: "agentName", type: "string" },
+        { name: "nonce", type: "uint64" },
+    ],
+};
+export const WITHDRAW_TYPES = {
+    Withdraw3: [
+        { name: "ofinChain", type: "string" },
+        { name: "destination", type: "address" },
+        { name: "signatureChainId", type: "string" },
+        { name: "tokenAddress", type: "address" },
+        { name: "amount", type: "string" },
+        { name: "nonce", type: "uint64" },
+    ],
+};
+export const TRANSFER_TOKEN_TYPES = {
+    TransferToken: [
+        { name: "ofinChain", type: "string" },
+        { name: "amount", type: "string" },
+        { name: "fromAccountType", type: "string" },
+        { name: "toAccountType", type: "string" },
+        { name: "token", type: "string" },
+        { name: "nonce", type: "uint64" },
+    ],
+};
+export const SEND_TOKEN_TYPES = {
+    SendToken: [
+        { name: "ofinChain", type: "string" },
+        { name: "toAddress", type: "address" },
+        { name: "amount", type: "string" },
+        { name: "fromAccountType", type: "string" },
+        { name: "toAccountType", type: "string" },
+        { name: "token", type: "string" },
+        { name: "nonce", type: "uint64" },
+    ],
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { TxFlowClient } from "./client.js";
+export { actionHash, signL1Action, createSign, signUserAction, generateNonce } from "./signing.js";
+export { TESTNET_API_URL, MAINNET_API_URL, USDC_TOKEN_ADDRESS, TESTNET_L1_CHAIN_ID, MAINNET_L1_CHAIN_ID, getL1ActionDomain, L1_ACTION_TYPES, USER_ACTION_DOMAIN, APPROVE_AGENT_TYPES, WITHDRAW_TYPES, TRANSFER_TOKEN_TYPES, SEND_TOKEN_TYPES, } from "./constants.js";
+export type { TxFlowConfig, OrderWire, OrderGrouping, CancelWire, CancelAction, ModifyWire, Signature, SignedRequest, PlaceOrderParams, CancelOrderParams, ModifyOrderParams, UpdateLeverageParams, UpdateMarginModeParams, ApproveAgentParams, WithdrawParams, TransferTokenParams, SendTokenParams, ApiResponse, InfoResponse, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { TxFlowClient } from "./client.js";
+export { actionHash, signL1Action, createSign, signUserAction, generateNonce } from "./signing.js";
+export { TESTNET_API_URL, MAINNET_API_URL, USDC_TOKEN_ADDRESS, TESTNET_L1_CHAIN_ID, MAINNET_L1_CHAIN_ID, getL1ActionDomain, L1_ACTION_TYPES, USER_ACTION_DOMAIN, APPROVE_AGENT_TYPES, WITHDRAW_TYPES, TRANSFER_TOKEN_TYPES, SEND_TOKEN_TYPES, } from "./constants.js";

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { TxFlowClient } from "./client.js";
+import { ethers } from "ethers";
+function getEnvOrThrow(name) {
+    const val = process.env[name];
+    if (!val)
+        throw new Error(`Missing required env var: ${name}`);
+    return val;
+}
+function fmt(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+async function main() {
+    const agentPrivateKey = getEnvOrThrow("TXFLOW_AGENT_PRIVATE_KEY");
+    const baseUrl = process.env.TXFLOW_BASE_URL || "https://testnet-api.txflow.net";
+    const userPrivateKey = process.env.TXFLOW_USER_PRIVATE_KEY;
+    const client = new TxFlowClient({
+        privateKey: agentPrivateKey,
+        baseUrl,
+        isMainnet: true,
+    });
+    const userWallet = userPrivateKey ? new ethers.Wallet(userPrivateKey) : null;
+    const server = new McpServer({
+        name: "txflow-mcp",
+        version: "0.1.0",
+    });
+    server.tool("place_order", "Place a perpetual futures order on TxFlow DEX.", {
+        asset: z.number().describe("Asset index (e.g. 0 for BTC)"),
+        isBuy: z.boolean().describe("True for buy/long, false for sell/short"),
+        price: z.string().describe("Order price"),
+        size: z.string().describe("Order size"),
+        reduceOnly: z.boolean().optional().describe("Reduce-only order"),
+        timeInForce: z.string().optional().describe("Time in force: gtc, ioc, alo"),
+    }, async (params) => {
+        const result = await client.placeOrder(params);
+        return fmt(result);
+    });
+    server.tool("cancel_order", "Cancel an open order on TxFlow DEX.", {
+        asset: z.number().describe("Asset index"),
+        orderId: z.string().describe("Order ID to cancel"),
+    }, async (params) => {
+        const result = await client.cancelOrder(params);
+        return fmt(result);
+    });
+    server.tool("cancel_orders", "Cancel multiple open orders on TxFlow DEX.", {
+        orders: z
+            .string()
+            .describe('JSON array of {asset: number, orderId: string} objects'),
+    }, async ({ orders }) => {
+        const parsed = JSON.parse(orders);
+        const result = await client.cancelOrders(parsed);
+        return fmt(result);
+    });
+    server.tool("modify_order", "Modify an existing order on TxFlow DEX.", {
+        orderId: z.string().describe("Order ID to modify"),
+        asset: z.number().describe("Asset index"),
+        isBuy: z.boolean().describe("True for buy, false for sell"),
+        price: z.string().describe("New price"),
+        size: z.string().describe("New size"),
+        reduceOnly: z.boolean().optional().describe("Reduce-only"),
+        timeInForce: z.string().optional().describe("Time in force"),
+    }, async (params) => {
+        const result = await client.modifyOrder(params);
+        return fmt(result);
+    });
+    server.tool("update_leverage", "Update leverage for an asset on TxFlow DEX.", {
+        asset: z.number().describe("Asset index"),
+        leverage: z.number().describe("New leverage value"),
+    }, async (params) => {
+        const result = await client.updateLeverage(params);
+        return fmt(result);
+    });
+    server.tool("update_margin_mode", "Update margin mode (cross/isolated) for an asset.", {
+        asset: z.number().describe("Asset index"),
+        isCross: z.boolean().describe("True for cross margin, false for isolated"),
+    }, async (params) => {
+        const result = await client.updateMarginMode(params);
+        return fmt(result);
+    });
+    server.tool("get_open_orders", "Get open orders for a user on TxFlow DEX.", {
+        user: z.string().describe("User address"),
+    }, async ({ user }) => {
+        const result = await client.getOpenOrders(user);
+        return fmt(result);
+    });
+    server.tool("get_user_state", "Get user account state including positions and balances.", {
+        user: z.string().describe("User address"),
+    }, async ({ user }) => {
+        const result = await client.getUserState(user);
+        return fmt(result);
+    });
+    server.tool("get_perp_meta", "Get perpetual futures metadata including available assets and their indices.", {
+        dex: z.string().optional().describe("DEX identifier (optional)"),
+    }, async ({ dex }) => {
+        const result = await client.getPerpMeta(dex);
+        return fmt(result);
+    });
+    server.tool("get_l2_book", "Get L2 order book for a coin.", {
+        coin: z.string().describe("Coin symbol, e.g. BTC"),
+    }, async ({ coin }) => {
+        const result = await client.getL2Book(coin);
+        return fmt(result);
+    });
+    server.tool("approve_agent", "Approve agent wallet for trading. Requires TXFLOW_USER_PRIVATE_KEY.", {
+        agentAddress: z.string().optional().describe("Agent address (defaults to SDK agent)"),
+        agentName: z.string().optional().describe("Agent name (defaults to TradeAgent)"),
+    }, async (params) => {
+        if (!userWallet) {
+            return fmt({ error: "TXFLOW_USER_PRIVATE_KEY env var is required for approve_agent" });
+        }
+        const result = await client.approveAgent(userWallet, params);
+        return fmt(result);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/signing.d.ts

@@ -0,0 +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 generateNonce(): number;
+export declare function createSign(wallet: ethers.Wallet, 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>;

package/dist/signing.js

@@ -0,0 +1,81 @@
+import { ethers } from "ethers";
+import { encode } from "@msgpack/msgpack";
+import { getL1ActionDomain, L1_ACTION_TYPES } from "./constants.js";
+function removeTrailingZeros(value) {
+    if (!value.includes("."))
+        return value;
+    const result = value.replace(/\.?0+$/, "");
+    return result === "-0" ? "0" : result;
+}
+function cleanAction(obj) {
+    if (!obj || typeof obj !== "object")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map((item) => cleanAction(item));
+    const cleaned = { ...obj };
+    for (const key in cleaned) {
+        if (Object.prototype.hasOwnProperty.call(cleaned, key)) {
+            const val = cleaned[key];
+            if (val && typeof val === "object") {
+                cleaned[key] = cleanAction(val);
+            }
+            else if ((key === "p" || key === "s") && typeof val === "string") {
+                cleaned[key] = removeTrailingZeros(val);
+            }
+        }
+    }
+    return cleaned;
+}
+function msgpackEncode(action) {
+    return encode(action, { useBigInt64: true });
+}
+export function actionHash(action, vaultAddress, nonce) {
+    const cleaned = cleanAction(action);
+    const encoded = msgpackEncode(cleaned);
+    const extraBytes = vaultAddress === null ? 9 : 29;
+    const buffer = new Uint8Array(encoded.length + extraBytes);
+    buffer.set(encoded);
+    const view = new DataView(buffer.buffer);
+    view.setBigUint64(encoded.length, BigInt(nonce), false);
+    if (vaultAddress === null) {
+        buffer[encoded.length + 8] = 0;
+    }
+    else {
+        buffer[encoded.length + 8] = 1;
+        const addrBytes = ethers.getBytes(vaultAddress);
+        buffer.set(addrBytes, encoded.length + 9);
+    }
+    return ethers.keccak256(buffer);
+}
+export async function signL1Action(wallet, action, vaultAddress, nonce, isMainnet, chainId) {
+    const hash = actionHash(action, vaultAddress, nonce);
+    const message = {
+        source: isMainnet ? "a" : "b",
+        connectionId: hash,
+    };
+    const domain = getL1ActionDomain(chainId);
+    const sig = await wallet.signTypedData(domain, L1_ACTION_TYPES, message);
+    const split = ethers.Signature.from(sig);
+    return {
+        r: split.r,
+        s: split.s,
+        v: split.v,
+    };
+}
+export function generateNonce() {
+    return Date.now();
+}
+export async function createSign(wallet, action, isMainnet, vaultAddress = null, chainId) {
+    const nonce = generateNonce();
+    const signature = await signL1Action(wallet, action, vaultAddress, nonce, isMainnet, chainId);
+    return { signature, nonce };
+}
+export async function signUserAction(wallet, domain, types, message) {
+    const sig = await wallet.signTypedData(domain, types, message);
+    const split = ethers.Signature.from(sig);
+    return {
+        r: split.r,
+        s: split.s,
+        v: split.v,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+export interface TxFlowConfig {
+    privateKey: string;
+    baseUrl?: string;
+    isMainnet?: boolean;
+    vaultAddress?: string | null;
+    chainId?: number;
+}
+export interface OrderWire {
+    a: number;
+    b: boolean;
+    p: string;
+    s: string;
+    r: boolean;
+    t: {
+        limit: {
+            tif: string;
+        };
+    };
+}
+export interface OrderGrouping {
+    grouping: string;
+    orders: OrderWire[];
+}
+export interface CancelWire {
+    a: number;
+    o: bigint;
+}
+export interface CancelAction {
+    cancels: CancelWire[];
+}
+export interface ModifyWire {
+    oid: bigint;
+    order: OrderWire;
+}
+export interface Signature {
+    r: string;
+    s: string;
+    v: number;
+}
+export interface SignedRequest {
+    action: Record<string, unknown>;
+    signature: Signature;
+    nonce: number;
+    vaultAddress?: string | null;
+}
+export interface PlaceOrderParams {
+    asset: number;
+    isBuy: boolean;
+    price: string;
+    size: string;
+    reduceOnly?: boolean;
+    timeInForce?: string;
+}
+export interface CancelOrderParams {
+    asset: number;
+    orderId: string;
+}
+export interface ModifyOrderParams {
+    orderId: string;
+    asset: number;
+    isBuy: boolean;
+    price: string;
+    size: string;
+    reduceOnly?: boolean;
+    timeInForce?: string;
+}
+export interface UpdateLeverageParams {
+    asset: number;
+    leverage: number;
+}
+export interface UpdateMarginModeParams {
+    asset: number;
+    isCross: boolean;
+}
+export interface ApproveAgentParams {
+    agentAddress: string;
+    agentName?: string;
+    nonce?: number;
+}
+export interface WithdrawParams {
+    destination: string;
+    amount: string;
+    signatureChainId?: string;
+}
+export interface TransferTokenParams {
+    amount: string;
+    fromAccountType: string;
+    toAccountType: string;
+}
+export interface SendTokenParams {
+    toAddress: string;
+    amount: string;
+    fromAccountType?: string;
+    toAccountType?: string;
+}
+export interface ApiResponse<T = unknown> {
+    status: string;
+    response?: string;
+    data?: T;
+}
+export interface InfoResponse<T = unknown> {
+    code: number;
+    success: boolean;
+    data?: T;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "txflow-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for TxFlow perpetual DEX with EIP-712 signing and MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "txflow-mcp": "dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "txflow",
+    "perp",
+    "dex",
+    "eip712",
+    "trading",
+    "sdk",
+    "mcp",
+    "perpetual",
+    "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",
+    "ethers": "^6.13.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}