@raintree-technology/perps 0.1.0

package/dist/lib/agent/x402.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage } from "node:http";
+export interface X402Requirement {
+    protocol: "x402";
+    version: string;
+    payTo: string;
+    network: string;
+    asset: string;
+    amount: string;
+    timeoutSeconds: number;
+}
+export interface X402Receipt {
+    paymentId: string;
+    proofHash: string;
+    rawProof: string;
+}
+export interface X402ValidationResult {
+    ok: boolean;
+    receipt?: X402Receipt;
+    requirement?: X402Requirement;
+    error?: string;
+}
+export declare function getX402Requirement(): X402Requirement;
+export declare function validateX402Payment(req: IncomingMessage): X402ValidationResult;

package/dist/lib/agent/x402.js

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+function header(message, name) {
+    const value = message.headers[name];
+    if (Array.isArray(value)) {
+        return value[0];
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return undefined;
+}
+export function getX402Requirement() {
+    return {
+        protocol: "x402",
+        version: "1",
+        payTo: (() => {
+            const addr = process.env.X402_PAY_TO;
+            if (!addr) {
+                console.warn("Warning: X402_PAY_TO is not set — payments will be sent to the zero address (burned).");
+                return "0x0000000000000000000000000000000000000000";
+            }
+            return addr;
+        })(),
+        network: process.env.X402_NETWORK ?? "base",
+        asset: process.env.X402_ASSET ?? "USDC",
+        amount: process.env.X402_AMOUNT ?? "0.05",
+        timeoutSeconds: Number(process.env.X402_TIMEOUT_SECONDS ?? 300),
+    };
+}
+export function validateX402Payment(req) {
+    const rawProof = header(req, "x402-payment") ??
+        header(req, "x-payment") ??
+        header(req, "payment");
+    if (!rawProof) {
+        return {
+            ok: false,
+            requirement: getX402Requirement(),
+            error: "missing_payment_proof",
+        };
+    }
+    const trimmed = rawProof.trim();
+    if (trimmed.length < 16) {
+        return {
+            ok: false,
+            requirement: getX402Requirement(),
+            error: "invalid_payment_proof",
+        };
+    }
+    const proofHash = createHash("sha256").update(trimmed).digest("hex");
+    const externalPaymentId = header(req, "x402-payment-id")?.trim();
+    const paymentId = externalPaymentId && externalPaymentId.length > 0
+        ? externalPaymentId
+        : `x402:${proofHash.slice(0, 24)}`;
+    return {
+        ok: true,
+        receipt: {
+            paymentId,
+            proofHash,
+            rawProof: trimmed,
+        },
+    };
+}

package/dist/lib/api-wallet.d.ts

@@ -0,0 +1,69 @@
+import type { Address, Hex } from "viem";
+/**
+ * Result of validating an API key
+ */
+export type ValidateApiKeyResult = {
+    valid: true;
+    masterAddress: Address;
+    apiWalletAddress: Address;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate an API private key by checking if it's registered as an agent wallet
+ * Returns the master address if valid, or an error message if not
+ */
+export declare function validateApiKey(apiPrivateKey: Hex, isTestnet?: boolean): Promise<ValidateApiKeyResult>;
+/**
+ * API wallet credentials
+ */
+export interface ApiWalletCredentials {
+    privateKey: Hex;
+    publicKey: Address;
+}
+/**
+ * Generate a new API wallet (random private key)
+ */
+export declare function generateApiWallet(): ApiWalletCredentials;
+/**
+ * User role response types from Hyperliquid API
+ */
+export type UserRoleResponse = {
+    role: "missing" | "user" | "vault";
+} | {
+    role: "agent";
+    data: {
+        user: Address;
+    };
+} | {
+    role: "subAccount";
+    data: {
+        master: Address;
+    };
+};
+/**
+ * Check if an API wallet is approved as an agent for a user
+ */
+export declare function checkApiWalletApproval(apiWalletAddress: Address, userAddress: Address, isTestnet?: boolean): Promise<{
+    approved: boolean;
+    masterAddress?: Address;
+}>;
+/**
+ * Get the Hyperliquid API approval URL
+ */
+export declare function getApprovalUrl(isTestnet?: boolean): string;
+/**
+ * Poll for API wallet approval with timeout
+ * Returns true if approved, false if timed out
+ */
+export declare function waitForApproval(apiWalletAddress: Address, userAddress: Address, isTestnet?: boolean, pollIntervalMs?: number, maxAttempts?: number): Promise<boolean>;
+/**
+ * Get all extra agents (API wallets) for a user address
+ */
+export interface ExtraAgent {
+    address: Address;
+    name: string;
+    validUntil: number;
+}
+export declare function getExtraAgents(userAddress: Address, isTestnet?: boolean): Promise<ExtraAgent[]>;

package/dist/lib/api-wallet.js

@@ -0,0 +1,101 @@
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+/**
+ * Validate an API private key by checking if it's registered as an agent wallet
+ * Returns the master address if valid, or an error message if not
+ */
+export async function validateApiKey(apiPrivateKey, isTestnet = false) {
+    const account = privateKeyToAccount(apiPrivateKey);
+    const apiWalletAddress = account.address;
+    const transport = new HttpTransport({ isTestnet });
+    const client = new InfoClient({ transport });
+    try {
+        const response = (await client.userRole({ user: apiWalletAddress }));
+        if (response.role === "agent") {
+            return {
+                valid: true,
+                masterAddress: response.data.user,
+                apiWalletAddress,
+            };
+        }
+        if (response.role === "missing") {
+            return { valid: false, error: "This key is not registered as an API wallet on Hyperliquid" };
+        }
+        return { valid: false, error: `Invalid role: ${response.role}. Expected an agent wallet.` };
+    }
+    catch (err) {
+        return { valid: false, error: `Failed to validate API key: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Generate a new API wallet (random private key)
+ */
+export function generateApiWallet() {
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    return {
+        privateKey,
+        publicKey: account.address,
+    };
+}
+/**
+ * Check if an API wallet is approved as an agent for a user
+ */
+export async function checkApiWalletApproval(apiWalletAddress, userAddress, isTestnet = false) {
+    const transport = new HttpTransport({ isTestnet });
+    const client = new InfoClient({ transport });
+    try {
+        const response = await client.userRole({ user: apiWalletAddress });
+        if (response.role === "agent") {
+            // Check if the agent is approved for the specified user
+            const isApprovedForUser = response.data.user.toLowerCase() === userAddress.toLowerCase();
+            return {
+                approved: isApprovedForUser,
+                masterAddress: response.data.user,
+            };
+        }
+        return { approved: false };
+    }
+    catch {
+        return { approved: false };
+    }
+}
+/**
+ * Get the Hyperliquid API approval URL
+ */
+export function getApprovalUrl(isTestnet = false) {
+    return isTestnet
+        ? "https://app.hyperliquid-testnet.xyz/API"
+        : "https://app.hyperliquid.xyz/API";
+}
+/**
+ * Poll for API wallet approval with timeout
+ * Returns true if approved, false if timed out
+ */
+export async function waitForApproval(apiWalletAddress, userAddress, isTestnet = false, pollIntervalMs = 3000, maxAttempts = 100 // About 5 minutes with 3s interval
+) {
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const result = await checkApiWalletApproval(apiWalletAddress, userAddress, isTestnet);
+        if (result.approved) {
+            return true;
+        }
+        // Wait before next poll
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return false;
+}
+export async function getExtraAgents(userAddress, isTestnet = false) {
+    const transport = new HttpTransport({ isTestnet });
+    const client = new InfoClient({ transport });
+    try {
+        const response = await client.extraAgents({ user: userAddress });
+        return response.map((agent) => ({
+            address: agent.address,
+            name: agent.name,
+            validUntil: agent.validUntil,
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/balance-watcher.d.ts

@@ -0,0 +1,25 @@
+import type { Address } from "viem";
+export interface BalanceData {
+    spotBalances: Array<{
+        token: string;
+        total: string;
+        hold: string;
+        available: string;
+    }>;
+    perpBalance: string;
+}
+export interface BalanceWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface BalanceWatcherConfig {
+    user: Address;
+    isTestnet: boolean;
+    onUpdate: (data: BalanceData) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates a balance watcher that subscribes to clearinghouse state updates
+ * and polls spot balances on each update
+ */
+export declare function createBalanceWatcher(config: BalanceWatcherConfig): BalanceWatcher;

package/dist/lib/balance-watcher.js

@@ -0,0 +1,83 @@
+import { WebSocketTransport, SubscriptionClient, HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates a balance watcher that subscribes to clearinghouse state updates
+ * and polls spot balances on each update
+ */
+export function createBalanceWatcher(config) {
+    let wsTransport = null;
+    let subscriptionClient = null;
+    let perpSubscription = null;
+    let httpClient = null;
+    return {
+        async start() {
+            // Create HTTP client for spot balance polling
+            const httpTransport = new HttpTransport({ isTestnet: config.isTestnet });
+            httpClient = new InfoClient({ transport: httpTransport });
+            // Fetch initial spot state
+            const spotState = await httpClient.spotClearinghouseState({ user: config.user });
+            let currentSpotBalances = spotState.balances
+                .filter((b) => parseFloat(b.total) !== 0)
+                .map((b) => ({
+                token: b.coin,
+                total: b.total,
+                hold: b.hold,
+                available: (parseFloat(b.total) - parseFloat(b.hold)).toString(),
+            }));
+            wsTransport = new WebSocketTransport({
+                isTestnet: config.isTestnet,
+                reconnect: { WebSocket: WebSocket },
+            });
+            subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+            await wsTransport.ready();
+            // Subscribe to perp clearinghouse state
+            perpSubscription = await subscriptionClient.allDexsClearinghouseState({ user: config.user }, async (state) => {
+                const clearinghouseState = state.clearinghouseStates[0]?.[1];
+                const perpBalance = clearinghouseState?.marginSummary.accountValue || "0";
+                // Refresh spot balances on each perp update
+                if (httpClient) {
+                    try {
+                        const freshSpotState = await httpClient.spotClearinghouseState({ user: config.user });
+                        currentSpotBalances = freshSpotState.balances
+                            .filter((b) => parseFloat(b.total) !== 0)
+                            .map((b) => ({
+                            token: b.coin,
+                            total: b.total,
+                            hold: b.hold,
+                            available: (parseFloat(b.total) - parseFloat(b.hold)).toString(),
+                        }));
+                    }
+                    catch {
+                        // Keep previous spot balances on error
+                    }
+                }
+                config.onUpdate({
+                    spotBalances: currentSpotBalances,
+                    perpBalance,
+                });
+            });
+        },
+        async stop() {
+            if (perpSubscription) {
+                try {
+                    await perpSubscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                perpSubscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+            subscriptionClient = null;
+            httpClient = null;
+        },
+    };
+}

package/dist/lib/book-watcher.d.ts

@@ -0,0 +1,25 @@
+export interface BookLevel {
+    px: string;
+    sz: string;
+    n: number;
+}
+export interface BookData {
+    coin: string;
+    bids: BookLevel[];
+    asks: BookLevel[];
+    time: number;
+}
+export interface BookWatcher {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface BookWatcherConfig {
+    coin: string;
+    isTestnet: boolean;
+    onUpdate: (data: BookData) => void;
+    onError: (error: Error) => void;
+}
+/**
+ * Creates a book watcher that subscribes to L2 order book updates via WebSocket
+ */
+export declare function createBookWatcher(config: BookWatcherConfig): BookWatcher;

package/dist/lib/book-watcher.js

@@ -0,0 +1,48 @@
+import { WebSocketTransport, SubscriptionClient } from "@nktkas/hyperliquid";
+import WebSocket from "ws";
+/**
+ * Creates a book watcher that subscribes to L2 order book updates via WebSocket
+ */
+export function createBookWatcher(config) {
+    let wsTransport = null;
+    let subscription = null;
+    return {
+        async start() {
+            wsTransport = new WebSocketTransport({
+                isTestnet: config.isTestnet,
+                reconnect: { WebSocket: WebSocket },
+            });
+            const subscriptionClient = new SubscriptionClient({ transport: wsTransport });
+            await wsTransport.ready();
+            subscription = await subscriptionClient.l2Book({ coin: config.coin }, (event) => {
+                const levels = event.levels;
+                config.onUpdate({
+                    coin: config.coin,
+                    bids: levels[0] || [],
+                    asks: levels[1] || [],
+                    time: event.time,
+                });
+            });
+        },
+        async stop() {
+            if (subscription) {
+                try {
+                    await subscription.unsubscribe();
+                }
+                catch {
+                    // Ignore errors during unsubscribe
+                }
+                subscription = null;
+            }
+            if (wsTransport) {
+                try {
+                    await wsTransport.close();
+                }
+                catch {
+                    // Ignore errors during close
+                }
+                wsTransport = null;
+            }
+        },
+    };
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,88 @@
+import type { Address, Hex } from "viem";
+import type { ExchangeCredentials } from "../adapters/interface.js";
+type ExchangeNetwork = "testnet" | "mainnet";
+interface HyperliquidSettings {
+    network: ExchangeNetwork;
+    privateKey?: Hex;
+    walletAddress?: Address;
+}
+export interface DecibelCredentials {
+    apiWalletPrivateKey?: Hex;
+    apiWalletAddress?: string;
+    apiBearerToken?: string;
+    subaccountAddress?: string;
+}
+export interface DecibelSettings {
+    network: "testnet" | "mainnet";
+    fullnodeUrl: string;
+    restUrl: string;
+    wsUrl: string;
+    packageAddress: string;
+    credentials?: DecibelCredentials;
+}
+interface AevoSettings {
+    network: ExchangeNetwork;
+    restUrl: string;
+    apiKey?: string;
+    apiSecret?: string;
+    signingKey?: Hex;
+}
+interface OrderlySettings {
+    network: ExchangeNetwork;
+    restUrl: string;
+    accountId?: string;
+    key?: string;
+    secret?: string;
+    tradingKey?: string;
+    tradingSecret?: string;
+}
+interface ParadexSettings {
+    network: ExchangeNetwork;
+    restUrl: string;
+    apiBearerToken?: string;
+    account?: string;
+    ethereumAccount?: string;
+    privateKey?: string;
+    chainId?: string;
+}
+export interface RiskPolicyConfig {
+    maxPositionSizeUsd: number;
+    maxTotalExposureUsd: number;
+    maxLeverage: number;
+    minSignalConfidence: number;
+    maxDrawdownPct: number;
+    defaultLeverage: number;
+}
+export interface ExecutionSafetyConfig {
+    stopLossPct: number;
+    takeProfitPct: number;
+    spreadOffset: number;
+}
+export interface Config {
+    privateKey?: Hex;
+    walletAddress?: Address;
+    testnet: boolean;
+    account?: {
+        alias: string;
+        type: "readonly" | "api_wallet";
+    };
+    risk: RiskPolicyConfig;
+    executionSafety: ExecutionSafetyConfig;
+    operator: {
+        heartbeatIntervalMs: number;
+    };
+    exchanges: {
+        hyperliquid: HyperliquidSettings;
+        decibel: DecibelSettings;
+        aevo: AevoSettings;
+        orderly: OrderlySettings;
+        paradex: ParadexSettings;
+    };
+}
+export declare function loadConfig(testnet: boolean, exchangeId?: string): Config;
+interface CredentialRequirement {
+    requireReadAccess?: boolean;
+    requireTrading?: boolean;
+}
+export declare function getExchangeCredentials(config: Config, exchangeId: string, requirement?: CredentialRequirement): ExchangeCredentials;
+export {};