@lifi/perps-sdk 0.1.1-alpha.0

package/dist/types/services/submitAuthorization.d.ts

@@ -0,0 +1,42 @@
+import type { Address, AuthorizationsResponse, SignedAuthorization } from '@lifi/perps-types';
+import type { PerpsSDKClient, SDKRequestOptions } from '../client/createPerpsClient.js';
+export interface SubmitAuthorizationParams {
+    /** DEX to authorize (e.g., 'hyperliquid') */
+    dex: string;
+    /** Wallet address */
+    address: Address;
+    /** Address of the signer (for agent mode, this is the agent address) */
+    signerAddress?: Address;
+    /** Signed authorization actions */
+    actions: SignedAuthorization[];
+}
+/**
+ * Submit signed authorizations to the DEX.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Results for each authorization action
+ * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ * const { results } = await submitAuthorization(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   actions: signedActions
+ * })
+ *
+ * for (const result of results) {
+ *   if (result.success) {
+ *     console.log(`${result.action} authorized`)
+ *   } else {
+ *     console.error(`${result.action} failed: ${result.error}`)
+ *   }
+ * }
+ * ```
+ */
+export declare function submitAuthorization(client: PerpsSDKClient, params: SubmitAuthorizationParams, options?: SDKRequestOptions): Promise<AuthorizationsResponse>;
+//# sourceMappingURL=submitAuthorization.d.ts.map

package/dist/types/services/submitAuthorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitAuthorization.d.ts","sourceRoot":"","sources":["../../../src/services/submitAuthorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAClB,MAAM,gCAAgC,CAAA;AAGvC,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAA;IACX,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mCAAmC;IACnC,OAAO,EAAE,mBAAmB,EAAE,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,yBAAyB,EACjC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CAejC"}

package/dist/types/services/submitOrder.d.ts

@@ -0,0 +1,44 @@
+import type { Address, SignedOrderAction, SubmitOrderResponse } from '@lifi/perps-types';
+import type { PerpsSDKClient, SDKRequestOptions } from '../client/createPerpsClient.js';
+export interface SubmitOrderParams {
+    /** DEX to submit order to (e.g., 'hyperliquid') */
+    dex: string;
+    /** Wallet address */
+    address: Address;
+    /** Address of the signer (for agent mode, this is the agent address) */
+    signerAddress?: Address;
+    /** Signed order actions */
+    actions: SignedOrderAction[];
+}
+/**
+ * Submit signed order actions to the DEX.
+ *
+ * @param client - The SDK client instance
+ * @param params - Request parameters
+ * @param options - Request options (e.g., AbortSignal)
+ * @returns Results for each order action
+ * @throws {HTTPError} On API error responses
+ * @throws {PerpsError} On network or parsing errors
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ integrator: 'my-app' })
+ *
+ * // After creating and signing order actions
+ * const { results } = await submitOrder(client, {
+ *   dex: 'hyperliquid',
+ *   address: '0x1234...',
+ *   actions: signedActions
+ * })
+ *
+ * for (const result of results) {
+ *   if (result.success) {
+ *     console.log(`Order placed: ${result.orderId}`)
+ *   } else {
+ *     console.error(`Order failed: ${result.error}`)
+ *   }
+ * }
+ * ```
+ */
+export declare function submitOrder(client: PerpsSDKClient, params: SubmitOrderParams, options?: SDKRequestOptions): Promise<SubmitOrderResponse>;
+//# sourceMappingURL=submitOrder.d.ts.map

package/dist/types/services/submitOrder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submitOrder.d.ts","sourceRoot":"","sources":["../../../src/services/submitOrder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAClB,MAAM,gCAAgC,CAAA;AAGvC,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,2BAA2B;IAC3B,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAe9B"}

package/dist/types/utils/request.d.ts

@@ -0,0 +1,26 @@
+import type { PerpsBaseConfig, SDKRequestOptions } from '../client/createPerpsClient.js';
+export interface RequestOptions extends RequestInit {
+    /** Number of retries on 5xx errors. Default: 1 */
+    retries?: number;
+}
+/**
+ * Make an HTTP request to the Perps API.
+ *
+ * @param config - SDK configuration
+ * @param url - The full URL to request
+ * @param options - Fetch options plus retries
+ * @param sdkOptions - SDK-specific options (signal, etc.)
+ * @returns Parsed JSON response
+ * @throws {HTTPError} On non-2xx responses
+ * @throws {PerpsError} On network or parsing errors
+ */
+export declare function request<T>(config: PerpsBaseConfig, url: string, options?: RequestOptions, sdkOptions?: SDKRequestOptions): Promise<T>;
+/**
+ * Build a URL with query parameters.
+ *
+ * @param baseUrl - The base URL
+ * @param params - Query parameters (undefined values are filtered out)
+ * @returns Full URL with query string
+ */
+export declare function buildUrl(baseUrl: string, params: Record<string, string | number | boolean | undefined>): string;
+//# sourceMappingURL=request.d.ts.map

package/dist/types/utils/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/utils/request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,gCAAgC,CAAA;AAMvC,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,EAC5B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAgEZ;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC5D,MAAM,CAWR"}

package/dist/types/utils/signTypedData.d.ts

@@ -0,0 +1,15 @@
+import type { Hex, PerpsTypedData } from '@lifi/perps-types';
+/**
+ * Sign EIP-712 typed data with a private key.
+ *
+ * @param privateKey - The private key to sign with
+ * @param typedData - The typed data to sign
+ * @returns The signature as a hex string
+ *
+ * @example
+ * ```ts
+ * const signature = await signTypedData(agentPrivateKey, typedData)
+ * ```
+ */
+export declare function signTypedData(privateKey: Hex, typedData: PerpsTypedData): Promise<Hex>;
+//# sourceMappingURL=signTypedData.d.ts.map

package/dist/types/utils/signTypedData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signTypedData.d.ts","sourceRoot":"","sources":["../../../src/utils/signTypedData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAG5D;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,GAAG,EACf,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,CAYd"}

package/dist/types/utils/sleep.d.ts

@@ -0,0 +1,2 @@
+export declare const sleep: (ms: number) => Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/types/utils/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CACI,CAAA"}

package/dist/types/version.d.ts

@@ -0,0 +1,3 @@
+export declare const name = "@lifi/perps-sdk";
+export declare const version = "0.1.1-alpha.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/types/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,oBAAoB,CAAA;AACrC,eAAO,MAAM,OAAO,kBAAkB,CAAA"}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@lifi/perps-sdk",
+  "version": "0.1.1-alpha.0",
+  "description": "LI.FI Perps SDK for perpetuals trading",
+  "homepage": "https://github.com/lifinance/perps-sdk",
+  "bugs": {
+    "url": "https://github.com/lifinance/perps-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lifinance/perps-sdk.git"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "Apache-2.0",
+  "author": "LI.FI <dev@li.fi>",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@lifi/perps-types": "^0.1.1-alpha.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@biomejs/biome": "^2.3.13",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "@vitest/coverage-v8": "^2.1.8",
+    "husky": "^9.1.7",
+    "knip": "^5.82.1",
+    "madge": "^8.0.0",
+    "msw": "^2.7.0",
+    "standard-version": "^9.5.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "!dist/**/*.tsbuildinfo",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.mock.ts",
+    "!src/**/*.handlers.ts",
+    "!src/**/*.tsbuildinfo",
+    "!**/__mocks__/**",
+    "!*.tmp",
+    "!*.env",
+    "!tsconfig.json"
+  ],
+  "keywords": [
+    "perps",
+    "perpetuals",
+    "trading",
+    "defi",
+    "ethereum",
+    "lifi",
+    "sdk",
+    "viem",
+    "hyperliquid"
+  ],
+  "scripts": {
+    "build": "pnpm clean && pnpm build:version && pnpm build:cjs && pnpm build:esm && pnpm build:types && pnpm build:clean",
+    "build:cjs": "tsc --project ./tsconfig.json --module commonjs --outDir ./dist/cjs --removeComments --verbatimModuleSyntax false && mkdir -p ./dist/cjs && printf '{\"type\":\"commonjs\"}' > ./dist/cjs/package.json",
+    "build:esm": "tsc --project ./tsconfig.json --module es2015 --outDir ./dist/esm && mkdir -p ./dist/esm && printf '{\"type\": \"module\",\"sideEffects\":false}' > ./dist/esm/package.json",
+    "build:types": "tsc --project ./tsconfig.json --module esnext --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
+    "build:clean": "rm -rf tsconfig.tsbuildinfo ./dist/tsconfig.tsbuildinfo",
+    "build:version": "node scripts/version.js",
+    "clean": "pnpm build:clean && rm -rf dist",
+    "check": "biome check",
+    "check:write": "biome check --write",
+    "check:types": "tsc --noEmit",
+    "check:circular-deps": "madge --circular $(find ./src -name '*.ts')",
+    "knip:check": "knip --dependencies --files --no-config-hints --exclude binaries",
+    "knip:write": "pnpm knip:check --fix",
+    "release": "standard-version -a -s",
+    "release:alpha": "standard-version -a -s --prerelease alpha --skip.changelog",
+    "release:beta": "standard-version -a -s --prerelease beta --skip.changelog",
+    "test": "vitest --run",
+    "test:cov": "vitest --run --coverage",
+    "test:unit": "vitest --run .unit.spec.ts --passWithNoTests",
+    "pre-commit": "pnpm check && pnpm check:types && pnpm check:circular-deps && pnpm knip:check",
+    "pre-push": "pnpm test:unit",
+    "postinstall": "husky"
+  }
+}

package/src/agent/AgentManager.ts

@@ -0,0 +1,135 @@
+import type { Address, Hex } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { PerpsErrorMessage } from '../errors/constants.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { localStorageAdapter } from './storage.js'
+import type { Agent, StorageAdapter } from './types.js'
+
+const STORAGE_PREFIX = 'lifi-perps-agent'
+
+/**
+ * Manages agent keypairs for USER_AGENT signing mode.
+ * Agent keys are stored per user address + DEX combination.
+ */
+export class AgentManager {
+  private storage: StorageAdapter
+  private cache: Map<string, Agent> = new Map()
+
+  constructor(storage?: StorageAdapter) {
+    this.storage = storage ?? localStorageAdapter
+  }
+
+  /**
+   * Get the storage key for an agent.
+   */
+  private storageKey(address: Address, dex: string): string {
+    return `${STORAGE_PREFIX}:${address.toLowerCase()}:${dex.toLowerCase()}`
+  }
+
+  /**
+   * Get an existing agent for a user + DEX pair.
+   *
+   * @throws {PerpsError} If agent not found
+   */
+  async getAgent(address: Address, dex: string): Promise<Agent> {
+    const key = this.storageKey(address, dex)
+
+    // Check cache first
+    const cached = this.cache.get(key)
+    if (cached) {
+      return cached
+    }
+
+    // Check storage
+    const stored = await this.storage.get(key)
+    if (stored) {
+      const agent = JSON.parse(stored) as Agent
+      this.cache.set(key, agent)
+      return agent
+    }
+
+    throw new PerpsError(
+      PerpsErrorCode.AgentUnauthorized,
+      PerpsErrorMessage.AgentNotFound
+    )
+  }
+
+  /**
+   * Get an existing agent or create a new one.
+   */
+  async getOrCreateAgent(address: Address, dex: string): Promise<Agent> {
+    try {
+      return await this.getAgent(address, dex)
+    } catch {
+      // Generate new agent
+      const privateKey = generatePrivateKey()
+      const account = privateKeyToAccount(privateKey)
+
+      const agent: Agent = {
+        address: account.address,
+        privateKey,
+      }
+
+      // Store
+      const key = this.storageKey(address, dex)
+      await this.storage.set(key, JSON.stringify(agent))
+      this.cache.set(key, agent)
+
+      return agent
+    }
+  }
+
+  /**
+   * Check if an agent exists for a user + DEX pair.
+   */
+  async hasAgent(address: Address, dex: string): Promise<boolean> {
+    try {
+      await this.getAgent(address, dex)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Remove an agent for a user + DEX pair.
+   * Call this when the user revokes agent authorization.
+   */
+  async removeAgent(address: Address, dex: string): Promise<void> {
+    const key = this.storageKey(address, dex)
+    this.cache.delete(key)
+    await this.storage.remove(key)
+  }
+
+  /**
+   * Import an existing agent keypair.
+   * Useful for restoring from backup or using a specific key.
+   */
+  async importAgent(
+    address: Address,
+    dex: string,
+    privateKey: Hex
+  ): Promise<Agent> {
+    const account = privateKeyToAccount(privateKey)
+
+    const agent: Agent = {
+      address: account.address,
+      privateKey,
+    }
+
+    const key = this.storageKey(address, dex)
+    await this.storage.set(key, JSON.stringify(agent))
+    this.cache.set(key, agent)
+
+    return agent
+  }
+
+  /**
+   * Clear all cached agents.
+   * Does not remove from storage.
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+}

package/src/agent/storage.ts

@@ -0,0 +1,58 @@
+import type { StorageAdapter } from './types.js'
+
+/**
+ * localStorage adapter for browser environments.
+ * Agent keys are stored as JSON strings with the key pattern:
+ * `lifi-perps-agent:{address}:{dex}`
+ */
+export const localStorageAdapter: StorageAdapter = {
+  get: (key: string): Promise<string | null> => {
+    try {
+      return Promise.resolve(localStorage.getItem(key))
+    } catch {
+      // localStorage not available (e.g., SSR)
+      return Promise.resolve(null)
+    }
+  },
+
+  set: (key: string, value: string): Promise<void> => {
+    try {
+      localStorage.setItem(key, value)
+    } catch {
+      // localStorage not available
+    }
+    return Promise.resolve()
+  },
+
+  remove: (key: string): Promise<void> => {
+    try {
+      localStorage.removeItem(key)
+    } catch {
+      // localStorage not available
+    }
+    return Promise.resolve()
+  },
+}
+
+/**
+ * In-memory storage adapter for testing or server-side use.
+ */
+export function createMemoryStorage(): StorageAdapter {
+  const store = new Map<string, string>()
+
+  return {
+    get: (key: string): Promise<string | null> => {
+      return Promise.resolve(store.get(key) ?? null)
+    },
+
+    set: (key: string, value: string): Promise<void> => {
+      store.set(key, value)
+      return Promise.resolve()
+    },
+
+    remove: (key: string): Promise<void> => {
+      store.delete(key)
+      return Promise.resolve()
+    },
+  }
+}

package/src/agent/types.ts

@@ -0,0 +1,24 @@
+import type { Address, Hex } from '@lifi/perps-types'
+
+/**
+ * Agent keypair for signing trading actions.
+ */
+export interface Agent {
+  /** Agent wallet address */
+  address: Address
+  /** Agent private key */
+  privateKey: Hex
+}
+
+/**
+ * Storage adapter interface for persisting agent keys.
+ * Implement this interface to use custom storage (e.g., encrypted storage, database).
+ */
+export interface StorageAdapter {
+  /** Get a value by key */
+  get(key: string): Promise<string | null>
+  /** Set a value by key */
+  set(key: string, value: string): Promise<void>
+  /** Remove a value by key */
+  remove(key: string): Promise<void>
+}