@raintree-technology/perps 0.1.0

package/dist/lib/agent/gateway.js

@@ -0,0 +1,598 @@
+import { createServer } from "node:http";
+import { getAvailableExchanges, getExchangeAdapterById } from "../exchange.js";
+import { getExchangeCredentials, loadConfig } from "../config.js";
+import { withJsonContract } from "../contracts.js";
+import { inferExitCode } from "../exit-codes.js";
+import { RiskPolicyMiddleware } from "../risk/policy-middleware.js";
+import { executeOrderWithSafety } from "../execution/safety.js";
+import { runWithExecutionJournal } from "../execution/journal.js";
+import { appendAgentAuditEvent } from "./audit.js";
+import { generateTraceId } from "../trace.js";
+import { getAgentMetricsSnapshot, getAgentReputationSummary, recordAgentRouteMetrics } from "./metrics.js";
+import { signAgentResponse } from "./signature.js";
+import { getX402Requirement, validateX402Payment } from "./x402.js";
+import { buildStateContext } from "../state-context.js";
+import { getTelemetrySnapshot, summarizeFailureRates } from "../telemetry.js";
+import { getToolDefinitions } from "./tools.js";
+import { addSignal } from "../signals.js";
+const JSON_HEADERS = {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+};
+function writeJson(res, status, data) {
+    res.statusCode = status;
+    res.setHeader("content-type", JSON_HEADERS["content-type"]);
+    res.setHeader("cache-control", JSON_HEADERS["cache-control"]);
+    res.end(`${JSON.stringify(data, null, 2)}\n`);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw) {
+        return {};
+    }
+    return JSON.parse(raw);
+}
+function toMarket(input) {
+    const raw = (input.market ?? input.symbol ?? "").trim().toUpperCase();
+    if (!raw) {
+        throw new Error("market or symbol is required");
+    }
+    if (raw.includes("-")) {
+        return raw;
+    }
+    return `${raw}-PERP`;
+}
+function toSide(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "buy" || normalized === "long") {
+        return "long";
+    }
+    if (normalized === "sell" || normalized === "short") {
+        return "short";
+    }
+    throw new Error("side must be one of: buy, sell, long, short");
+}
+function toSize(value) {
+    const num = typeof value === "number" ? value : Number.parseFloat(value);
+    if (!Number.isFinite(num) || num <= 0) {
+        throw new Error("size must be a positive number");
+    }
+    return num;
+}
+function toExchange(defaultExchange, value) {
+    const selected = (value ?? defaultExchange).trim().toLowerCase();
+    if (!getAvailableExchanges().includes(selected)) {
+        throw new Error(`unknown exchange: ${selected}`);
+    }
+    return selected;
+}
+function toTestnet(defaultTestnet, value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    return defaultTestnet;
+}
+function normalizeExchangeHint(value, fallback) {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (normalized.length > 0) {
+            return normalized;
+        }
+    }
+    return fallback;
+}
+function inferExchangeForRoute(route, requestPayload, defaultExchange) {
+    if (route === "quote" || route === "execute") {
+        const payload = requestPayload;
+        return normalizeExchangeHint(payload?.exchange, defaultExchange);
+    }
+    if (route === "acp.intent") {
+        const payload = requestPayload;
+        return normalizeExchangeHint(payload?.payload?.exchange, defaultExchange);
+    }
+    return "system";
+}
+function bindRouteMeta(route, requestPayload, responsePayload) {
+    const signature = signAgentResponse(requestPayload, responsePayload);
+    return {
+        ...responsePayload,
+        contract: {
+            route,
+            signature,
+        },
+    };
+}
+function requirePayment(req) {
+    const validated = validateX402Payment(req);
+    if (!validated.ok || !validated.receipt) {
+        const error = new Error(validated.error ?? "payment_required");
+        error.requirement =
+            validated.requirement ?? getX402Requirement();
+        throw error;
+    }
+    return validated.receipt;
+}
+async function handleQuote(req, options, requestPayload) {
+    const exchange = toExchange(options.defaultExchange, requestPayload.exchange);
+    const testnet = toTestnet(options.defaultTestnet, requestPayload.testnet);
+    const market = toMarket(requestPayload);
+    const side = toSide(requestPayload.side);
+    const size = toSize(requestPayload.size);
+    const payment = requestPayload.premium ? requirePayment(req) : undefined;
+    const config = loadConfig(testnet, exchange);
+    const credentials = getExchangeCredentials(config, exchange);
+    const adapter = getExchangeAdapterById(exchange);
+    await adapter.connect({
+        testnet: config.testnet,
+        rpcUrl: credentials.fullnodeUrl,
+        wsUrl: credentials.wsUrl,
+        credentials,
+    });
+    try {
+        const ticker = await adapter.getTicker(market);
+        const book = await adapter.getOrderBook(market, 3);
+        const bid = Number.parseFloat(book.bids[0]?.price ?? "");
+        const ask = Number.parseFloat(book.asks[0]?.price ?? "");
+        const mark = Number.parseFloat(ticker.markPrice);
+        const last = Number.parseFloat(ticker.lastPrice);
+        const reference = side === "long"
+            ? (Number.isFinite(ask) && ask > 0 ? ask : mark)
+            : (Number.isFinite(bid) && bid > 0 ? bid : mark);
+        const effective = Number.isFinite(reference) && reference > 0 ? reference : last;
+        if (!Number.isFinite(effective) || effective <= 0) {
+            throw new Error("unable to compute reference price");
+        }
+        const spread = Number.isFinite(ask) && Number.isFinite(bid) && ask > 0 && bid > 0
+            ? ask - bid
+            : undefined;
+        const payload = withJsonContract("agent.quote.result", bindRouteMeta("quote", requestPayload, {
+            status: "ok",
+            exchange,
+            testnet,
+            market,
+            side,
+            size,
+            quote: {
+                referencePrice: effective,
+                notionalUsd: effective * size,
+                spread,
+                bid: Number.isFinite(bid) ? bid : null,
+                ask: Number.isFinite(ask) ? ask : null,
+            },
+            payment: payment
+                ? {
+                    id: payment.paymentId,
+                    protocol: "x402",
+                }
+                : null,
+            generatedAt: Date.now(),
+        }));
+        return payload;
+    }
+    finally {
+        await adapter.disconnect();
+    }
+}
+async function handleExecute(req, options, requestPayload, traceId) {
+    const exchange = toExchange(options.defaultExchange, requestPayload.exchange);
+    const testnet = toTestnet(options.defaultTestnet, requestPayload.testnet);
+    const market = toMarket(requestPayload);
+    const side = toSide(requestPayload.side);
+    const size = toSize(requestPayload.size);
+    if (!testnet && !options.allowMainnetExecution) {
+        throw new Error("mainnet execution is disabled for agent gateway. set PERPS_AGENT_ALLOW_MAINNET=1 to enable");
+    }
+    const idempotencyKey = requestPayload.idempotencyKey?.trim();
+    if (!idempotencyKey) {
+        throw new Error("idempotencyKey is required");
+    }
+    const requirePaidExecution = requestPayload.requirePayment !== false;
+    const payment = requirePaidExecution ? requirePayment(req) : undefined;
+    const config = loadConfig(testnet, exchange);
+    const credentials = getExchangeCredentials(config, exchange, {
+        requireTrading: true,
+    });
+    const adapter = getExchangeAdapterById(exchange);
+    await adapter.connect({
+        testnet: config.testnet,
+        rpcUrl: credentials.fullnodeUrl,
+        wsUrl: credentials.wsUrl,
+        credentials,
+    });
+    try {
+        const riskPolicy = new RiskPolicyMiddleware(config, exchange);
+        const confidence = Number.isFinite(requestPayload.confidence) ? requestPayload.confidence : 1;
+        const riskDecision = await riskPolicy.evaluateOrder(adapter, {
+            market,
+            side,
+            requestedSizeBase: size,
+            confidence,
+            reason: "agent-gateway:execute",
+        }, traceId);
+        if (!riskDecision.allowed || riskDecision.adjustedSizeBase <= 0) {
+            throw new Error(riskDecision.reason ?? "order blocked by risk policy");
+        }
+        const finalSize = riskDecision.adjustedSizeBase;
+        const journaled = await runWithExecutionJournal({
+            idempotencyKey,
+            traceId,
+            metadata: {
+                command: "agent.execute.market",
+                exchange,
+                testnet: config.testnet,
+                market,
+                side,
+                orderType: "market",
+            },
+            request: {
+                exchange,
+                testnet: config.testnet,
+                market,
+                side,
+                requestedSize: size,
+                finalSize,
+                confidence,
+                reduceOnly: requestPayload.reduceOnly ?? false,
+                paymentId: payment?.paymentId ?? null,
+            },
+            execute: async () => {
+                const execution = await executeOrderWithSafety(adapter, {
+                    market,
+                    side,
+                    type: "market",
+                    size: finalSize.toFixed(8),
+                    reduceOnly: requestPayload.reduceOnly,
+                }, {
+                    closeThenFlip: true,
+                    spreadAwarePricing: true,
+                    spreadOffset: config.executionSafety.spreadOffset,
+                });
+                return {
+                    order: execution.order,
+                    safety: execution,
+                    risk: {
+                        requestedSize: size,
+                        adjustedSize: finalSize,
+                        adjustedNotionalUsd: riskDecision.adjustedSizeUsd,
+                        referencePrice: riskDecision.referencePriceUsd,
+                    },
+                };
+            },
+        });
+        const resultPayload = withJsonContract("agent.execute.result", bindRouteMeta("execute", requestPayload, {
+            status: journaled.replayed ? "replayed" : "executed",
+            exchange,
+            testnet: config.testnet,
+            market,
+            idempotency: {
+                key: journaled.idempotencyKey,
+                replayed: journaled.replayed,
+                autoGenerated: journaled.autoGeneratedKey,
+                journalId: journaled.journalId,
+            },
+            payment: payment
+                ? {
+                    id: payment.paymentId,
+                    protocol: "x402",
+                }
+                : null,
+            result: journaled.result,
+            generatedAt: Date.now(),
+        }));
+        appendAgentAuditEvent({
+            action: "execute",
+            status: "ok",
+            exchange,
+            market,
+            idempotencyKey: journaled.idempotencyKey,
+            paymentId: payment?.paymentId,
+            requestHash: resultPayload.data.contract.signature.requestHash,
+            traceId,
+            details: {
+                replayed: journaled.replayed,
+                testnet: config.testnet,
+            },
+        });
+        return resultPayload;
+    }
+    finally {
+        await adapter.disconnect();
+    }
+}
+async function handleAcpIntent(req, options, requestPayload, traceId) {
+    const role = requestPayload.role?.trim().toLowerCase();
+    const action = requestPayload.action?.trim().toLowerCase();
+    const correlationId = requestPayload.correlationId?.trim() || `acp-${Date.now()}`;
+    if (!role) {
+        throw new Error("role is required");
+    }
+    if (!action) {
+        throw new Error("action is required");
+    }
+    // ACP flows are treated as paid orchestration by default.
+    const payment = requirePayment(req);
+    let result;
+    if (action === "quote" || action === "price_quote") {
+        result = await handleQuote(req, options, {
+            ...requestPayload.payload,
+            premium: false,
+        });
+    }
+    else if (action === "execute" || action === "trade_execute") {
+        result = await handleExecute(req, options, requestPayload.payload, traceId);
+    }
+    else {
+        throw new Error(`unsupported ACP action: ${action}`);
+    }
+    const payload = withJsonContract("agent.acp.intent.result", bindRouteMeta("acp.intent", requestPayload, {
+        status: "accepted",
+        correlationId,
+        role,
+        action,
+        payment: {
+            id: payment.paymentId,
+            protocol: "x402",
+        },
+        ackAt: Date.now(),
+        result,
+    }));
+    appendAgentAuditEvent({
+        action: "acp.intent",
+        status: "ok",
+        traceId,
+        details: {
+            role,
+            action,
+            correlationId,
+            paymentId: payment.paymentId,
+        },
+    });
+    return payload;
+}
+function toErrorPayload(route, requestPayload, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const requirement = err.requirement;
+    if (message === "missing_payment_proof" || message === "invalid_payment_proof") {
+        return {
+            status: 402,
+            body: withJsonContract("agent.payment.required", bindRouteMeta(route, requestPayload, {
+                status: "payment_required",
+                error: message,
+                requirement: requirement ?? getX402Requirement(),
+            })),
+        };
+    }
+    const exitCode = inferExitCode(err);
+    return {
+        status: 400,
+        body: withJsonContract("agent.error", bindRouteMeta(route, requestPayload, {
+            status: "error",
+            error: {
+                message,
+                exitCode,
+            },
+        })),
+    };
+}
+export function createAgentGateway(options) {
+    const startedAt = Date.now();
+    const server = createServer(async (req, res) => {
+        const routeStart = Date.now();
+        const method = req.method ?? "GET";
+        const url = req.url ?? "/";
+        let parsedBody = {};
+        const traceId = generateTraceId();
+        res.setHeader("X-Trace-Id", traceId);
+        const finalize = (route, ok, exchange = "system") => {
+            recordAgentRouteMetrics(route, ok, Date.now() - routeStart, exchange);
+        };
+        try {
+            if (method === "GET" && url === "/status") {
+                const payload = withJsonContract("agent.status", {
+                    status: "ok",
+                    startedAt,
+                    uptimeMs: Date.now() - startedAt,
+                    defaultExchange: options.defaultExchange,
+                    defaultTestnet: options.defaultTestnet,
+                    allowMainnetExecution: options.allowMainnetExecution,
+                });
+                writeJson(res, 200, payload);
+                finalize("status", true, "system");
+                return;
+            }
+            if (method === "GET" && url === "/metrics") {
+                writeJson(res, 200, withJsonContract("agent.metrics", getAgentMetricsSnapshot()));
+                finalize("metrics", true, "system");
+                return;
+            }
+            if (method === "GET" && url === "/reputation") {
+                const telemetry = getTelemetrySnapshot();
+                writeJson(res, 200, withJsonContract("agent.reputation", {
+                    ...getAgentReputationSummary(),
+                    telemetry: summarizeFailureRates(telemetry),
+                }));
+                finalize("reputation", true, "system");
+                return;
+            }
+            if (method === "GET" && url === "/capabilities") {
+                const payload = withJsonContract("agent.capabilities", {
+                    agent: "perps-agent-gateway",
+                    schemaVersion: 1,
+                    defaults: {
+                        exchange: options.defaultExchange,
+                        testnet: options.defaultTestnet,
+                    },
+                    exchanges: getAvailableExchanges(),
+                    endpoints: [
+                        { method: "GET", path: "/capabilities", scope: "public" },
+                        { method: "GET", path: "/context", scope: "authenticated" },
+                        { method: "POST", path: "/quote", scope: "public|paid" },
+                        { method: "POST", path: "/execute", scope: "paid" },
+                        { method: "POST", path: "/acp/intent", scope: "paid|orchestrated" },
+                        { method: "POST", path: "/signal", scope: "authenticated" },
+                        { method: "GET", path: "/tools", scope: "public" },
+                        { method: "GET", path: "/status", scope: "public" },
+                        { method: "GET", path: "/metrics", scope: "operator" },
+                        { method: "GET", path: "/reputation", scope: "public" },
+                    ],
+                    x402: getX402Requirement(),
+                    observability: {
+                        metricsDimensions: ["route", "exchange"],
+                        dailyReportCommand: "corepack pnpm agent:telemetry:daily -- --json",
+                    },
+                    acp: {
+                        enabled: true,
+                        actions: ["quote", "price_quote", "execute", "trade_execute"],
+                        roles: ["buyer", "seller", "evaluator", "facilitator"],
+                    },
+                });
+                writeJson(res, 200, payload);
+                finalize("capabilities", true, "system");
+                return;
+            }
+            if (method === "GET" && url === "/tools") {
+                const tools = getToolDefinitions();
+                const payload = withJsonContract("agent.tools", { tools });
+                writeJson(res, 200, payload);
+                finalize("tools", true, "system");
+                return;
+            }
+            if (method === "GET" && url === "/context") {
+                const exchangeId = options.defaultExchange ?? "hyperliquid";
+                try {
+                    const exchange = toExchange(options.defaultExchange, exchangeId);
+                    const config = loadConfig(toTestnet(options.defaultTestnet), exchange);
+                    const credentials = getExchangeCredentials(config, exchange, {
+                        requireReadAccess: true,
+                    });
+                    const adapter = getExchangeAdapterById(exchange);
+                    await adapter.connect({
+                        testnet: config.testnet,
+                        rpcUrl: credentials.fullnodeUrl,
+                        wsUrl: credentials.wsUrl,
+                        credentials,
+                    });
+                    try {
+                        const context = await buildStateContext(adapter, exchange, config);
+                        const signed = signAgentResponse({}, context);
+                        const payload = withJsonContract("agent.context", {
+                            ...context,
+                            contract: {
+                                route: "context",
+                                signature: signed,
+                            },
+                        });
+                        writeJson(res, 200, payload);
+                        finalize("context", true, exchange);
+                    }
+                    finally {
+                        await adapter.disconnect();
+                    }
+                }
+                catch (ctxErr) {
+                    const failure = toErrorPayload("context", {}, ctxErr);
+                    writeJson(res, failure.status, failure.body);
+                    finalize("context", false, exchangeId);
+                }
+                return;
+            }
+            if (method === "POST" && url === "/quote") {
+                parsedBody = await readBody(req);
+                const body = parsedBody;
+                const payload = await handleQuote(req, options, body);
+                writeJson(res, 200, payload);
+                finalize("quote", true, inferExchangeForRoute("quote", body, options.defaultExchange));
+                return;
+            }
+            if (method === "POST" && url === "/execute") {
+                parsedBody = await readBody(req);
+                const body = parsedBody;
+                const payload = await handleExecute(req, options, body, traceId);
+                writeJson(res, 200, payload);
+                finalize("execute", true, inferExchangeForRoute("execute", body, options.defaultExchange));
+                return;
+            }
+            if (method === "POST" && url === "/acp/intent") {
+                parsedBody = await readBody(req);
+                const body = parsedBody;
+                const payload = await handleAcpIntent(req, options, body, traceId);
+                writeJson(res, 200, payload);
+                finalize("acp.intent", true, inferExchangeForRoute("acp.intent", body, options.defaultExchange));
+                return;
+            }
+            if (method === "POST" && url === "/signal") {
+                parsedBody = await readBody(req);
+                const body = parsedBody;
+                const exchange = body.exchange;
+                const signalValue = body.signal;
+                if (!exchange || typeof exchange !== "string") {
+                    throw new Error("exchange is required");
+                }
+                if (signalValue !== "up" && signalValue !== "down") {
+                    throw new Error('signal must be "up" or "down"');
+                }
+                const id = addSignal({
+                    traceId: typeof body.traceId === "string" ? body.traceId : undefined,
+                    exchange,
+                    market: typeof body.market === "string" ? body.market : undefined,
+                    strategy: typeof body.strategy === "string" ? body.strategy : undefined,
+                    signal: signalValue,
+                    reason: typeof body.reason === "string" ? body.reason : undefined,
+                    pnlUsd: typeof body.pnlUsd === "number" ? body.pnlUsd : undefined,
+                    metadata: typeof body.metadata === "object" && body.metadata !== null
+                        ? body.metadata
+                        : undefined,
+                });
+                writeJson(res, 200, withJsonContract("agent.signal.recorded", { id }));
+                finalize("signal", true, exchange);
+                return;
+            }
+            writeJson(res, 404, withJsonContract("agent.not_found", {
+                status: "not_found",
+                method,
+                path: url,
+            }));
+            finalize("not_found", false, "system");
+        }
+        catch (err) {
+            const routeName = url === "/quote" ? "quote" :
+                url === "/execute" ? "execute" :
+                    url === "/acp/intent" ? "acp.intent" :
+                        url === "/signal" ? "signal" : "unknown";
+            const requestPayload = method === "POST" ? parsedBody : {};
+            const failure = toErrorPayload(routeName, requestPayload, err);
+            writeJson(res, failure.status, failure.body);
+            appendAgentAuditEvent({
+                action: routeName,
+                status: "error",
+                traceId,
+                details: {
+                    message: err instanceof Error ? err.message : String(err),
+                    method,
+                    path: url,
+                },
+            });
+            finalize(routeName, false, inferExchangeForRoute(routeName, requestPayload, options.defaultExchange));
+        }
+    });
+    return {
+        server,
+        start: () => new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port, options.host, () => resolve());
+        }),
+        stop: () => new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve();
+            });
+        }),
+    };
+}

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

@@ -0,0 +1,33 @@
+interface RouteMetrics {
+    total: number;
+    success: number;
+    failure: number;
+    latencyMsTotal: number;
+}
+export interface AgentMetricsSnapshot {
+    startedAt: number;
+    routes: Record<string, RouteMetrics>;
+    exchanges: Record<string, RouteMetrics>;
+}
+export declare function resetAgentMetrics(): void;
+export declare function recordAgentRouteMetrics(route: string, ok: boolean, latencyMs: number, exchange?: string): void;
+export declare function getAgentMetricsSnapshot(): AgentMetricsSnapshot;
+export declare function getAgentReputationSummary(): {
+    uptimeMs: number;
+    successRate: number;
+    totalRequests: number;
+    routes: Array<{
+        route: string;
+        total: number;
+        successRate: number;
+        p50LatencyEstimateMs: number;
+        avgLatencyMs: number;
+    }>;
+    exchanges: Array<{
+        exchange: string;
+        total: number;
+        successRate: number;
+        avgLatencyMs: number;
+    }>;
+};
+export {};