@raintree-technology/perps 0.1.0

package/dist/commands/arb/basis-execute.js

@@ -0,0 +1,332 @@
+/**
+ * Arb Basis Execute Command
+ * Execute basis trades (cash-and-carry arbitrage) on a single exchange
+ */
+import { createHash } from "node:crypto";
+import { confirm } from "@inquirer/prompts";
+import { getContext, getOutputOptions, getSelectedExchange } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+import { getExchangeAdapterById } from "../../lib/exchange.js";
+import { DEFAULT_ARB_SIZE_USD } from "../../lib/constants.js";
+import { validateAsset, validateSize } from "../../lib/validate.js";
+import { getExchangeCredentials } from "../../lib/config.js";
+import { RiskPolicyMiddleware } from "../../lib/risk/policy-middleware.js";
+import { executeOrderWithSafety } from "../../lib/execution/safety.js";
+import { runWithExecutionJournal } from "../../lib/execution/journal.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { CLIError, EXIT_CODES, inferExitCode } from "../../lib/exit-codes.js";
+export function registerArbBasisExecuteCommand(arb) {
+    arb
+        .command("basis-execute [asset]")
+        .description("Execute basis trade (cash-and-carry arbitrage)")
+        .option("-s, --size <usd>", "Position size in USD (required)")
+        .option("--confidence <0-1>", "Signal confidence for risk evaluation (default: 0.5)")
+        .option("--exchange <id>", "Exchange to trade on (overrides default)")
+        .option("--min-basis <pct>", "Minimum basis to consider actionable (default: 0.1)")
+        .option("--tp <pct>", "Take-profit basis convergence threshold")
+        .option("--sl <pct>", "Stop-loss basis divergence threshold")
+        .option("--dry-run", "Show what would happen without executing")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--idempotency-key <key>", "Explicit idempotency key")
+        .action(async function (asset) {
+        const ctx = getContext(this);
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const emitJson = (data) => {
+            output(withJsonContract("arb.basis-execute.result", data), outputOpts);
+        };
+        const isJson = outputOpts.json;
+        try {
+            if (isJson && !opts.yes && !opts.dryRun) {
+                throw new CLIError("Use --yes with --json for non-interactive basis execution", EXIT_CODES.VALIDATION_ERROR);
+            }
+            const assetName = validateAsset(asset);
+            const market = `${assetName}-PERP`;
+            if (!opts.size) {
+                throw new CLIError("Position size is required. Use --size <usd>", EXIT_CODES.VALIDATION_ERROR);
+            }
+            const requestedSizeUsd = validateSize(opts.size, DEFAULT_ARB_SIZE_USD);
+            const confidence = opts.confidence ? parseFloat(opts.confidence) : 0.5;
+            if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+                throw new CLIError("Confidence must be a number between 0 and 1", EXIT_CODES.VALIDATION_ERROR);
+            }
+            const minBasis = opts.minBasis ? parseFloat(opts.minBasis) : 0.1;
+            if (!Number.isFinite(minBasis) || minBasis < 0) {
+                throw new CLIError("Min basis must be a non-negative number", EXIT_CODES.VALIDATION_ERROR);
+            }
+            const exchangeId = opts.exchange ?? getSelectedExchange(this);
+            const adapter = getExchangeAdapterById(exchangeId);
+            const credentials = getExchangeCredentials(ctx.config, exchangeId, {
+                requireTrading: true,
+            });
+            await adapter.connect({
+                testnet: ctx.config.testnet,
+                rpcUrl: credentials.fullnodeUrl,
+                wsUrl: credentials.wsUrl,
+                credentials,
+            });
+            try {
+                const ticker = await adapter.getTicker(market);
+                const markPrice = parseFloat(ticker.markPrice);
+                const indexPrice = parseFloat(ticker.indexPrice);
+                if (!Number.isFinite(markPrice) || markPrice <= 0) {
+                    throw new CLIError("Unable to fetch reliable mark price for basis calculation", EXIT_CODES.DATA_UNAVAILABLE);
+                }
+                if (!Number.isFinite(indexPrice) || indexPrice <= 0) {
+                    if (isJson) {
+                        emitJson({
+                            status: "no_data",
+                            reason: "no_index_price",
+                            market,
+                            exchange: exchangeId,
+                        });
+                    }
+                    else {
+                        console.log("\n  No index price available for this market on this exchange.\n");
+                    }
+                    process.exitCode = EXIT_CODES.DATA_UNAVAILABLE;
+                    return;
+                }
+                // Compute basis: (markPrice - indexPrice) / indexPrice * 100
+                const basisPct = ((markPrice - indexPrice) / indexPrice) * 100;
+                // Guard: basis too small
+                if (Math.abs(basisPct) < minBasis) {
+                    if (isJson) {
+                        emitJson({
+                            status: "no_opportunity",
+                            reason: "basis_too_small",
+                            market,
+                            exchange: exchangeId,
+                            basisPct,
+                            minBasis,
+                        });
+                    }
+                    else {
+                        console.log(`\n  Basis spread ${basisPct >= 0 ? "+" : ""}${basisPct.toFixed(4)}% is below minimum threshold of ${minBasis}%.`);
+                        console.log("  No actionable opportunity.\n");
+                    }
+                    process.exitCode = EXIT_CODES.NO_OPPORTUNITY;
+                    return;
+                }
+                // Determine side: basis > 0 (premium) -> short, basis < 0 (discount) -> long
+                const side = basisPct > 0 ? "short" : "long";
+                const direction = basisPct > 0 ? "premium" : "discount";
+                // Risk evaluation
+                const risk = new RiskPolicyMiddleware(ctx.config, exchangeId);
+                const evaluation = await risk.evaluateUsdSignal(adapter, { market, side, confidence, reason: "basis-trade", timestamp: Date.now() }, requestedSizeUsd);
+                if (!evaluation.allowed) {
+                    throw new CLIError(`Trade blocked by risk policy: ${evaluation.reason ?? "unknown"}`, EXIT_CODES.EXECUTION_ERROR);
+                }
+                const sizeUsd = Math.min(requestedSizeUsd, evaluation.sizeUsd);
+                if (!Number.isFinite(sizeUsd) || sizeUsd <= 0) {
+                    throw new CLIError("Risk policy reduced trade size to zero", EXIT_CODES.EXECUTION_ERROR);
+                }
+                // Build execution plan
+                const annualizedPct = Math.abs(basisPct) * 365;
+                const dailyProfit = (Math.abs(basisPct) / 100) * sizeUsd;
+                const plan = {
+                    asset: assetName,
+                    exchange: exchangeId,
+                    size: sizeUsd,
+                    side,
+                    markPrice,
+                    indexPrice,
+                    basisPct,
+                    direction,
+                    annualizedPct,
+                    dailyProfit,
+                };
+                if (!isJson) {
+                    console.log("\n  \x1b[1m━━━ Basis Trade Execution Plan ━━━\x1b[0m\n");
+                    console.log(`  Asset:          ${assetName}`);
+                    console.log(`  Exchange:       ${exchangeId}`);
+                    console.log(`  Position Size:  $${sizeUsd.toLocaleString()}`);
+                    if (Math.abs(sizeUsd - requestedSizeUsd) > 1e-9) {
+                        console.log(`  Risk Adjusted:  from $${requestedSizeUsd.toLocaleString()}`);
+                    }
+                    console.log("");
+                    console.log(`  Mark Price:     $${markPrice.toLocaleString()}`);
+                    console.log(`  Index Price:    $${indexPrice.toLocaleString()}`);
+                    console.log(`  Basis:          ${basisPct >= 0 ? "+" : ""}${basisPct.toFixed(4)}% (${direction})`);
+                    console.log("");
+                    const sideColor = side === "short" ? "\x1b[31m" : "\x1b[32m";
+                    const sideArrow = side === "short" ? "▼" : "▲";
+                    console.log(`  ${sideColor}${sideArrow} ${side.toUpperCase()}\x1b[0m ${assetName}-PERP`);
+                    console.log(`    Rationale:    ${direction === "premium" ? "Sell premium — basis converges to zero" : "Buy discount — basis converges to zero"}`);
+                    console.log("");
+                    console.log("  " + "─".repeat(45));
+                    console.log(`  Annualized:     \x1b[32m${annualizedPct.toFixed(2)}%\x1b[0m`);
+                    console.log(`  Est. Daily:     \x1b[32m$${dailyProfit.toFixed(2)}\x1b[0m`);
+                    console.log("  " + "─".repeat(45));
+                    console.log("");
+                }
+                if (opts.dryRun) {
+                    if (isJson) {
+                        emitJson({
+                            status: "dry_run",
+                            market,
+                            asset: assetName,
+                            exchange: exchangeId,
+                            testnet: ctx.config.testnet,
+                            requestedSizeUsd,
+                            plan,
+                        });
+                    }
+                    else {
+                        console.log("  \x1b[33m[DRY RUN]\x1b[0m Execution skipped.\n");
+                    }
+                    return;
+                }
+                if (!opts.yes) {
+                    const confirmed = await confirm({
+                        message: "Execute this basis trade?",
+                        default: false,
+                    });
+                    if (!confirmed) {
+                        if (isJson) {
+                            emitJson({
+                                status: "cancelled",
+                                reason: "user_declined_confirmation",
+                                market,
+                                asset: assetName,
+                                plan,
+                            });
+                        }
+                        else {
+                            console.log("\n  Execution cancelled.\n");
+                        }
+                        process.exitCode = EXIT_CODES.CANCELLED;
+                        return;
+                    }
+                }
+                const orderSize = (sizeUsd / markPrice).toFixed(8);
+                const shouldAttachTpSl = opts.tp !== undefined || opts.sl !== undefined;
+                const tp = opts.tp !== undefined ? parseFloat(opts.tp) : ctx.config.executionSafety.takeProfitPct;
+                const sl = opts.sl !== undefined ? parseFloat(opts.sl) : ctx.config.executionSafety.stopLossPct;
+                if (shouldAttachTpSl) {
+                    if (!Number.isFinite(tp) || tp <= 0) {
+                        throw new CLIError("TP must be a positive number", EXIT_CODES.VALIDATION_ERROR);
+                    }
+                    if (!Number.isFinite(sl) || sl <= 0) {
+                        throw new CLIError("SL must be a positive number", EXIT_CODES.VALIDATION_ERROR);
+                    }
+                }
+                // Build idempotency key
+                const idempotencyKey = opts.idempotencyKey?.trim() || undefined;
+                const autoKeyHash = createHash("sha256")
+                    .update(`basis:${exchangeId}:${market}:${side}:${sizeUsd}`)
+                    .digest("hex")
+                    .slice(0, 16);
+                const timeBucket = Math.floor(Date.now() / 30_000);
+                const resolvedIdempotencyKey = idempotencyKey ?? `basis:${autoKeyHash}:${timeBucket}`;
+                if (!isJson) {
+                    console.log(`\n  \x1b[36mExecuting ${side.toUpperCase()} on ${exchangeId}...\x1b[0m\n`);
+                }
+                const journal = await runWithExecutionJournal({
+                    idempotencyKey: resolvedIdempotencyKey,
+                    metadata: {
+                        command: "arb.basis-execute",
+                        exchange: exchangeId,
+                        testnet: ctx.config.testnet,
+                        market,
+                        side,
+                        orderType: "market",
+                    },
+                    request: {
+                        market,
+                        side,
+                        size: orderSize,
+                        spreadAware: true,
+                        spreadOffset: ctx.config.executionSafety.spreadOffset,
+                        tp: shouldAttachTpSl ? tp : null,
+                        sl: shouldAttachTpSl ? sl : null,
+                        requestedSizeUsd,
+                        adjustedSizeUsd: sizeUsd,
+                        confidence,
+                        basisPct,
+                    },
+                    execute: async () => {
+                        const result = await executeOrderWithSafety(adapter, {
+                            market,
+                            side,
+                            type: "market",
+                            size: orderSize,
+                        }, {
+                            closeThenFlip: true,
+                            spreadAwarePricing: true,
+                            spreadOffset: ctx.config.executionSafety.spreadOffset,
+                            attachTpSl: shouldAttachTpSl,
+                            tpSlConfig: shouldAttachTpSl
+                                ? { stopLossPct: sl, takeProfitPct: tp }
+                                : undefined,
+                        });
+                        return {
+                            order: {
+                                id: result.order.id,
+                                market: result.order.market,
+                                side: result.order.side,
+                                size: result.order.size,
+                                status: result.order.status,
+                                price: result.order.price,
+                            },
+                            safety: {
+                                closedOppositePosition: result.closedOppositePosition,
+                                tpSlOrderIds: result.tpSlOrderIds,
+                                pricing: result.pricing,
+                            },
+                        };
+                    },
+                });
+                if (!isJson) {
+                    console.log(`  ✓ ${side.toUpperCase()} ${journal.replayed ? "replayed" : "opened"}: ${journal.result.order.id}`);
+                    console.log("\n  \x1b[32m━━━ Basis Trade Executed ━━━\x1b[0m");
+                    if (journal.result.safety.tpSlOrderIds.length > 0) {
+                        console.log("  TP/SL attached");
+                    }
+                    console.log(`  Monitor position with: perps -e ${exchangeId} account positions`);
+                    console.log("");
+                }
+                else {
+                    emitJson({
+                        status: "executed",
+                        market,
+                        asset: assetName,
+                        exchange: exchangeId,
+                        testnet: ctx.config.testnet,
+                        requestedSizeUsd,
+                        plan,
+                        execution: {
+                            ...journal.result,
+                            idempotency: {
+                                key: journal.idempotencyKey,
+                                replayed: journal.replayed,
+                                autoGenerated: journal.autoGeneratedKey,
+                                journalId: journal.journalId,
+                            },
+                        },
+                    });
+                }
+            }
+            finally {
+                await adapter.disconnect().catch(() => undefined);
+            }
+        }
+        catch (err) {
+            const code = inferExitCode(err);
+            const message = err instanceof Error ? err.message : String(err);
+            if (isJson) {
+                emitJson({
+                    status: "error",
+                    error: {
+                        message,
+                        exitCode: code,
+                    },
+                });
+            }
+            else {
+                outputError(message);
+            }
+            process.exit(code);
+        }
+    });
+}

package/dist/commands/arb/basis.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Arb Basis Command
+ * Fetch perp and spot/index prices to show basis spread opportunities
+ */
+import { Command } from "commander";
+export declare function registerArbBasisCommand(arb: Command): void;

package/dist/commands/arb/basis.js

@@ -0,0 +1,181 @@
+/**
+ * Arb Basis Command
+ * Fetch perp and spot/index prices to show basis spread opportunities
+ */
+import { getContext, getOutputOptions } from "../../cli/program.js";
+import { output, outputError } from "../../cli/output.js";
+import { getExchangeAdapterById, getAvailableExchanges } from "../../lib/exchange.js";
+import { withJsonContract } from "../../lib/contracts.js";
+export function registerArbBasisCommand(arb) {
+    arb
+        .command("basis [asset]")
+        .description("Show basis spread between perp and index prices")
+        .option("--min-basis <pct>", "Minimum basis spread to show", "0.05")
+        .option("-w, --watch", "Watch mode - refresh every 10s")
+        .option("--json", "JSON output")
+        .action(async function (asset) {
+        const ctx = getContext(this);
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const isTestnet = ctx.config.testnet;
+        const resolvedAsset = asset ? asset.toUpperCase() : "BTC";
+        const minBasis = parseFloat(opts.minBasis ?? "0.05");
+        try {
+            const exchanges = getAvailableExchanges();
+            if (outputOpts.json && opts.watch) {
+                throw new Error("Watch mode is not supported with --json");
+            }
+            if (opts.watch) {
+                await watchBasis(resolvedAsset, exchanges, minBasis, isTestnet);
+            }
+            else {
+                await showBasis(resolvedAsset, exchanges, minBasis, outputOpts.json, isTestnet);
+            }
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+async function fetchBasis(asset, exchanges, isTestnet) {
+    const results = [];
+    const promises = exchanges.map(async (exchangeId) => {
+        const adapter = getExchangeAdapterById(exchangeId);
+        let connected = false;
+        try {
+            await adapter.connect({ testnet: isTestnet });
+            connected = true;
+            const symbol = `${asset}-PERP`;
+            const ticker = await adapter.getTicker(symbol);
+            const markPrice = parseFloat(ticker.markPrice);
+            const indexPrice = parseFloat(ticker.indexPrice);
+            if (!indexPrice || indexPrice === 0) {
+                return null;
+            }
+            const basisPct = ((markPrice - indexPrice) / indexPrice) * 100;
+            const annualizedPct = Math.abs(basisPct) * 365;
+            return {
+                exchange: adapter.info.name,
+                markPrice,
+                indexPrice,
+                basisPct,
+                direction: (basisPct >= 0 ? "premium" : "discount"),
+                annualizedPct,
+            };
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (connected) {
+                await adapter.disconnect().catch(() => undefined);
+            }
+        }
+    });
+    const settled = await Promise.allSettled(promises);
+    for (const result of settled) {
+        if (result.status === "fulfilled" && result.value !== null) {
+            results.push(result.value);
+        }
+    }
+    return results;
+}
+function formatUsd(value) {
+    return `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+async function showBasis(asset, exchanges, minBasis, json, isTestnet) {
+    if (!json) {
+        console.log(`\nFetching ${asset} basis across ${exchanges.length} exchanges...\n`);
+    }
+    const opportunities = await fetchBasis(asset, exchanges, isTestnet);
+    // Filter by minimum basis
+    const filtered = opportunities.filter((o) => Math.abs(o.basisPct) >= minBasis);
+    // Sort by absolute basis descending
+    filtered.sort((a, b) => Math.abs(b.basisPct) - Math.abs(a.basisPct));
+    if (json) {
+        output(withJsonContract("arb.basis.result", {
+            asset,
+            opportunities: filtered,
+            timestamp: Date.now(),
+        }), { json: true });
+        return;
+    }
+    if (filtered.length === 0) {
+        console.log(`  No basis opportunities found for ${asset} above ${minBasis}%`);
+        console.log("");
+        return;
+    }
+    console.log(`  Basis Spread: ${asset}\n`);
+    console.log("  Exchange".padEnd(18) +
+        "Mark Price".padEnd(16) +
+        "Index Price".padEnd(16) +
+        "Basis (%)".padEnd(14) +
+        "Direction");
+    console.log("  " + "\u2500".repeat(76));
+    for (const o of filtered) {
+        const basisColor = o.direction === "premium" ? "\x1b[32m" : "\x1b[31m";
+        const basisSign = o.basisPct >= 0 ? "+" : "";
+        const dirLabel = o.direction === "premium"
+            ? "Premium (short perp opportunity)"
+            : "Discount";
+        console.log(`  ${o.exchange.padEnd(16)}` +
+            `${formatUsd(o.markPrice).padEnd(16)}` +
+            `${formatUsd(o.indexPrice).padEnd(16)}` +
+            `${basisColor}${basisSign}${o.basisPct.toFixed(2)}%\x1b[0m`.padEnd(14 + 9) +
+            dirLabel);
+    }
+    // Best opportunity
+    const best = filtered[0];
+    console.log("\n  " + "\u2500".repeat(76));
+    console.log(`\n  Best opportunity: ${best.exchange} at ${best.basisPct >= 0 ? "+" : ""}${best.basisPct.toFixed(2)}% basis`);
+    console.log(`  Annualized (if persistent): ~${best.annualizedPct.toFixed(1)}%`);
+    console.log("");
+}
+async function watchBasis(asset, exchanges, minBasis, isTestnet) {
+    console.log(`\nWatching ${asset} basis (Ctrl+C to exit)...\n`);
+    const refresh = async () => {
+        process.stdout.write("\x1B[2J\x1B[0f");
+        console.log(`\n  ${asset} Basis Monitor (${new Date().toLocaleTimeString()})\n`);
+        const opportunities = await fetchBasis(asset, exchanges, isTestnet);
+        const filtered = opportunities.filter((o) => Math.abs(o.basisPct) >= minBasis);
+        filtered.sort((a, b) => Math.abs(b.basisPct) - Math.abs(a.basisPct));
+        if (filtered.length === 0) {
+            console.log(`  No basis opportunities above ${minBasis}%`);
+            console.log("\n  Press Ctrl+C to exit");
+            return;
+        }
+        console.log("  Exchange".padEnd(18) +
+            "Mark Price".padEnd(16) +
+            "Index Price".padEnd(16) +
+            "Basis (%)".padEnd(14) +
+            "Direction");
+        console.log("  " + "\u2500".repeat(76));
+        for (const o of filtered) {
+            const basisColor = o.direction === "premium" ? "\x1b[32m" : "\x1b[31m";
+            const basisSign = o.basisPct >= 0 ? "+" : "";
+            const dirLabel = o.direction === "premium"
+                ? "Premium (short perp opportunity)"
+                : "Discount";
+            console.log(`  ${o.exchange.padEnd(16)}` +
+                `${formatUsd(o.markPrice).padEnd(16)}` +
+                `${formatUsd(o.indexPrice).padEnd(16)}` +
+                `${basisColor}${basisSign}${o.basisPct.toFixed(2)}%\x1b[0m`.padEnd(14 + 9) +
+                dirLabel);
+        }
+        if (filtered.length > 0) {
+            const best = filtered[0];
+            console.log("\n  " + "\u2500".repeat(76));
+            console.log(`\n  Best: ${best.exchange} at ${best.basisPct >= 0 ? "+" : ""}${best.basisPct.toFixed(2)}% (annualized ~${best.annualizedPct.toFixed(1)}%)`);
+        }
+        console.log("\n  Press Ctrl+C to exit");
+    };
+    await refresh();
+    const interval = setInterval(refresh, 10000);
+    process.once("SIGINT", () => {
+        clearInterval(interval);
+        console.log("\n");
+        process.exit(0);
+    });
+    await new Promise(() => { });
+}

package/dist/commands/arb/compare.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Arb Compare Command
+ * Compare arbitrage opportunities across all assets
+ */
+import { Command } from "commander";
+export declare function registerArbCompareCommand(arb: Command): void;