deltazero-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akanbi Labs
+
+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,49 @@
+# DeltaZero TypeScript SDK
+
+Typed SDK package for the live DeltaZero API.
+
+This package is a thin client around the deployed DeltaZero API. It does not duplicate backend logic and does not add authentication.
+
+## Installation
+
+```bash
+npm install deltazero-core
+```
+
+## Development from the repository
+
+From the repository root:
+
+```bash
+cd sdk/typescript
+npm test
+```
+
+To use the package in another local project, point your package manager at this folder while the repository is checked out locally.
+
+## API
+
+```ts
+import { DeltaZeroClient } from "deltazero-core";
+
+const client = new DeltaZeroClient({
+  baseUrl: "https://deltazero-production.up.railway.app",
+});
+
+const report = await client.buildStrategy({
+  asset: "SOL",
+  capital_usd: 5000,
+  risk_tolerance: "medium",
+  target_style: "neutral_yield",
+  long_yield_apy: 14,
+  short_funding_apy: 3,
+  fee_drag_apy: 1,
+});
+```
+
+Supported methods:
+
+- `buildStrategy()`
+- `auditPosition()`
+- `stressTest()`
+- `auditWallet()`

package/dist/src/client.d.ts

@@ -0,0 +1,28 @@
+import type { AuditRequest, AuditResponse, BuildRequest, BuildResponse, DeltaZeroClientOptions, StressTestRequest, StressTestResponse, WalletAnalyzeRequest, WalletPortfolioResponse } from "./types.js";
+export declare class DeltaZeroError extends Error {
+    constructor(message: string);
+}
+export declare class DeltaZeroApiError extends DeltaZeroError {
+    readonly status: number;
+    readonly url: string;
+    readonly body: unknown;
+    constructor(message: string, options: {
+        status: number;
+        url: string;
+        body: unknown;
+    });
+}
+export declare class DeltaZeroTimeoutError extends DeltaZeroError {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+export declare class DeltaZeroClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: DeltaZeroClientOptions);
+    private request;
+    buildStrategy(body: BuildRequest): Promise<BuildResponse>;
+    auditPosition(body: AuditRequest): Promise<AuditResponse>;
+    stressTest(body: StressTestRequest): Promise<StressTestResponse>;
+    auditWallet(body: WalletAnalyzeRequest): Promise<WalletPortfolioResponse>;
+}

package/dist/src/client.js

@@ -0,0 +1,114 @@
+export class DeltaZeroError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeltaZeroError";
+    }
+}
+export class DeltaZeroApiError extends DeltaZeroError {
+    status;
+    url;
+    body;
+    constructor(message, options) {
+        super(message);
+        this.name = "DeltaZeroApiError";
+        this.status = options.status;
+        this.url = options.url;
+        this.body = options.body;
+    }
+}
+export class DeltaZeroTimeoutError extends DeltaZeroError {
+    url;
+    constructor(message, url) {
+        super(message);
+        this.name = "DeltaZeroTimeoutError";
+        this.url = url;
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+function describeErrorBody(body, fallback) {
+    if (typeof body === "string" && body.trim())
+        return body;
+    if (body && typeof body === "object" && "detail" in body) {
+        const detail = body.detail;
+        if (typeof detail === "string")
+            return detail;
+        if (Array.isArray(detail))
+            return JSON.stringify(detail);
+        if (detail && typeof detail === "object")
+            return JSON.stringify(detail);
+    }
+    return fallback;
+}
+async function parseJsonBody(response, url) {
+    const text = await response.text();
+    if (!text.trim())
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new DeltaZeroError(`Invalid JSON returned from ${url}.`);
+    }
+}
+export class DeltaZeroClient {
+    baseUrl;
+    timeoutMs;
+    constructor(options) {
+        if (!options.baseUrl?.trim()) {
+            throw new DeltaZeroError("A baseUrl is required.");
+        }
+        this.baseUrl = normalizeBaseUrl(options.baseUrl.trim());
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    async request(path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeout = globalThis.setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const parsed = await parseJsonBody(response, url);
+            if (!response.ok) {
+                const detail = describeErrorBody(parsed, response.statusText || "Request failed.");
+                throw new DeltaZeroApiError(`API ${response.status}: ${detail}`, {
+                    status: response.status,
+                    url,
+                    body: parsed,
+                });
+            }
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new DeltaZeroError(`Invalid response body returned from ${url}.`);
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof DeltaZeroError)
+                throw error;
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw new DeltaZeroTimeoutError(`Request to ${url} timed out after ${this.timeoutMs}ms.`, url);
+            }
+            throw new DeltaZeroError(error instanceof Error ? error.message : `Request to ${url} failed.`);
+        }
+        finally {
+            globalThis.clearTimeout(timeout);
+        }
+    }
+    buildStrategy(body) {
+        return this.request("/strategy/build", body);
+    }
+    auditPosition(body) {
+        return this.request("/strategy/audit", body);
+    }
+    stressTest(body) {
+        return this.request("/strategy/stress-test", body);
+    }
+    auditWallet(body) {
+        return this.request("/wallet/analyze", body);
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { DeltaZeroClient, DeltaZeroApiError, DeltaZeroError, DeltaZeroTimeoutError } from "./client.js";
+export type { Asset, AuditRequest, AuditResponse, BuildRequest, BuildResponse, DeltaZeroClientOptions, ImpairmentBreakdown, Metrics, NormalizedPosition, PositionType, ProtocolError, RecommendedStructure, Recommendation, RiskTolerance, Scenario, ScenarioResult, ScenarioType, StrategyAction, StrategyHealth, StressTestRequest, StressTestResponse, TargetStyle, WalletAction, WalletAnalyzeRequest, WalletAssessmentStatus, WalletDataQuality, WalletNetwork, WalletPortfolioResponse, WalletPortfolioSummary, WalletProtocol, WalletRecommendation, WalletRiskMetrics, WalletStressProfile, WalletStrategyHealth, } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1 @@
+export { DeltaZeroClient, DeltaZeroApiError, DeltaZeroError, DeltaZeroTimeoutError } from "./client.js";

package/dist/src/types.d.ts

@@ -0,0 +1,318 @@
+export type Asset = "SOL" | "ETH";
+export type RiskTolerance = "low" | "medium" | "high";
+export type TargetStyle = "neutral_yield" | "conservative_income" | "aggressive_carry" | "capital_preservation";
+export type StrategyAction = "OPEN" | "WAIT" | "HOLD" | "REBALANCE" | "REDUCE" | "CLOSE";
+export type StrategyHealth = "healthy" | "warning" | "critical";
+export type ScenarioType = "funding_worsens" | "price_drop" | "price_rise" | "yield_drops";
+export type WalletNetwork = "ethereum" | "arbitrum" | "hyperliquid";
+export type WalletProtocol = "hyperliquid" | "aave" | "morpho";
+export type WalletStressProfile = "standard" | "elevated" | "strict";
+export type WalletAction = "HOLD" | "REBALANCE" | "REDUCE" | "CLOSE";
+export type WalletStrategyHealth = "healthy" | "warning" | "fragile" | "critical";
+export type WalletDataQuality = "complete" | "partial" | "insufficient";
+export type WalletAssessmentStatus = "positions_found" | "no_supported_positions" | "partial_data" | "insufficient_data";
+export type PositionType = "spot" | "lending_supply" | "lending_borrow" | "vault_deposit" | "perpetual_long" | "perpetual_short" | "collateral" | "unknown";
+export interface Metrics {
+    hedge_ratio: number;
+    hedge_drift_pct: number;
+    net_delta_estimate: number;
+    estimated_net_carry_apy: number;
+    carry_efficiency_score: number;
+    safety_buffer_score: number;
+    capital_at_risk_proxy: number;
+}
+export interface Recommendation {
+    action: StrategyAction;
+    summary: string;
+}
+export interface RecommendedStructure {
+    long_notional_usd: number;
+    short_notional_usd: number;
+    collateral_usd: number;
+    target_hedge_ratio: number;
+}
+export interface Scenario {
+    type: ScenarioType;
+    magnitude_pct: number;
+    asset_price_change_pct?: number | null;
+    collateral_haircut_pct?: number | null;
+    exit_slippage_pct?: number | null;
+    liquidation_penalty_pct?: number | null;
+    protocol_loss_pct?: number | null;
+}
+export interface ImpairmentBreakdown {
+    asset_value_impact_usd: number;
+    hedge_pnl_impact_usd: number;
+    collateral_haircut_usd: number;
+    exit_slippage_usd: number;
+    liquidation_penalty_usd: number;
+    protocol_loss_assumption_usd: number;
+}
+export interface ScenarioResult {
+    scenario_type: ScenarioType;
+    magnitude_pct: number;
+    stressed_long_notional_usd: number;
+    stressed_short_notional_usd: number;
+    stressed_collateral_usd: number;
+    stressed_long_yield_apy: number;
+    stressed_short_funding_apy: number;
+    stressed_metrics: Metrics;
+    health_after_stress: StrategyHealth;
+    pre_stress_equity_usd: number;
+    stressed_liabilities_usd: number;
+    estimated_impairment_loss_usd: number;
+    estimated_impairment_loss_pct: number;
+    post_impairment_equity_usd: number;
+    impairment_breakdown: ImpairmentBreakdown;
+}
+export interface BuildRequest {
+    asset: Asset;
+    capital_usd: number;
+    risk_tolerance: RiskTolerance;
+    target_style: TargetStyle;
+    long_yield_apy: number;
+    short_funding_apy: number;
+    fee_drag_apy: number;
+    market_data_mode?: "manual" | "hyperliquid";
+    funding_lookback_hours?: number;
+    override_live_funding?: boolean;
+    market_dex?: string | null;
+    wallet_exposure?: WalletExposureImport | null;
+}
+export interface WalletExposureImport {
+    source: "wallet_auditor";
+    wallet_address: string;
+    asset: string | null;
+    gross_long_exposure_usd: number | null;
+    gross_short_exposure_usd: number | null;
+    net_delta_usd: number | null;
+    net_delta_pct: number | null;
+    current_hedge_ratio: number | null;
+    portfolio_equity_usd: number | null;
+    largest_risk_asset: string | null;
+    recommended_action: WalletAction;
+    data_quality: "complete" | "partial";
+    data_timestamp: string | null;
+}
+export interface HedgeAdjustment {
+    current_long_notional_usd: number | null;
+    current_short_notional_usd: number | null;
+    target_short_notional_usd: number | null;
+    short_adjustment_usd: number | null;
+    target_hedge_ratio: number;
+    projected_hedge_ratio: number | null;
+    projected_net_delta_usd: number | null;
+    projected_net_delta_pct: number | null;
+    projected_hedge_drift_pct: number | null;
+    adjustment_direction: "increase_short" | "reduce_short" | "no_change" | null;
+    limitation: string | null;
+}
+export interface AuditRequest {
+    asset: Asset;
+    long_notional_usd: number;
+    short_notional_usd: number;
+    collateral_usd: number;
+    risk_tolerance: RiskTolerance;
+    long_yield_apy: number;
+    short_funding_apy: number;
+    fee_drag_apy: number;
+}
+export interface StressTestRequest {
+    asset: Asset;
+    long_notional_usd: number;
+    short_notional_usd: number;
+    collateral_usd: number;
+    risk_tolerance: RiskTolerance;
+    long_yield_apy: number;
+    short_funding_apy: number;
+    fee_drag_apy: number;
+    existing_unrealized_pnl_usd?: number;
+    liabilities_usd?: number;
+    scenario: Scenario;
+}
+export interface StrategyResponseBase {
+    service: string;
+    strategy_name: string;
+    asset: Asset;
+    strategy_health: StrategyHealth;
+    decision_confidence: number;
+    metrics: Metrics;
+    recommendation: Recommendation;
+    risk_notes: string[];
+}
+export interface BuildResponse extends StrategyResponseBase {
+    recommended_structure: RecommendedStructure;
+    market_data_source?: "hyperliquid";
+    market_data_timestamp?: string;
+    funding_rate_apy?: number;
+    funding_contribution_apy?: number;
+    market_data_quality?: "complete" | "partial" | "unavailable";
+    market_context?: Record<string, unknown>;
+    hedge_adjustment?: HedgeAdjustment;
+}
+export interface AuditResponse extends StrategyResponseBase {
+    actions: StrategyAction[];
+}
+export interface StressTestResponse extends StrategyResponseBase {
+    actions: StrategyAction[];
+    scenario_result: ScenarioResult;
+    pre_stress_equity_usd: number;
+    stressed_liabilities_usd: number;
+    estimated_impairment_loss_usd: number;
+    estimated_impairment_loss_pct: number;
+    post_impairment_equity_usd: number;
+    impairment_breakdown: ImpairmentBreakdown;
+}
+export interface NormalizedPosition {
+    protocol: WalletProtocol;
+    network: WalletNetwork;
+    position_type: PositionType;
+    asset: string;
+    quantity: number | null;
+    notional_usd: number | null;
+    current_value_usd: number | null;
+    entry_value_usd: number | null;
+    unrealized_pnl_usd: number | null;
+    collateral_usd: number | null;
+    debt_usd: number | null;
+    funding_apy: number | null;
+    liquidation_price: number | null;
+    health_factor: number | null;
+    data_timestamp: string | null;
+    data_quality: WalletDataQuality;
+    side?: "long" | "short" | null;
+    subaccount_name?: string | null;
+    subaccount_address?: string | null;
+    market_context?: Record<string, unknown> | null;
+}
+export interface WalletExecutiveSummary {
+    headline: string;
+    body: string;
+    position_count: number;
+    protocol_count: number;
+    risk_level: WalletStrategyHealth;
+}
+export interface WalletPrimaryDriver {
+    metric: string;
+    label: string;
+    state: "positive" | "warning" | "critical" | "unavailable";
+    value: number | null;
+    unit: string | null;
+    explanation: string;
+}
+export interface WalletPlanStep {
+    priority: number;
+    action: string;
+    reason: string;
+    target: string | null;
+}
+export interface WalletExposureAnalysis {
+    gross_exposure_usd: number;
+    gross_long_exposure_usd: number;
+    gross_short_exposure_usd: number;
+    net_delta_usd: number;
+    net_delta_pct: number;
+    portfolio_equity_usd: number | null;
+    leverage_ratio: number | null;
+    position_count: number;
+}
+export interface WalletAllocationItem {
+    asset: string;
+    exposure_usd: number;
+    allocation_pct: number;
+}
+export interface WalletStressSummary {
+    stress_profile: WalletStressProfile;
+    estimated_impairment_loss_usd: number;
+    estimated_impairment_loss_pct: number;
+    post_impairment_equity_usd: number;
+    dominant_risk: string;
+    summary: string;
+    impairment_level: "LOW" | "MEDIUM" | "HIGH";
+    impairment_label: "Contained" | "Elevated" | "Critical";
+}
+export interface WalletRiskContributor {
+    asset: string;
+    protocol: WalletProtocol;
+    exposure_usd: number;
+    risk_contribution_pct: number;
+    primary_risk: string;
+}
+export interface WalletRiskTimelineItem {
+    metric: string;
+    state: "healthy" | "warning" | "critical" | "unavailable";
+    explanation: string;
+}
+export interface WalletAnalyzeRequest {
+    wallet_address: string;
+    networks: WalletNetwork[];
+    protocols: WalletProtocol[];
+    stress_profile: WalletStressProfile;
+}
+export interface WalletPortfolioSummary {
+    current_position_value_usd: number;
+    gross_long_exposure_usd: number;
+    gross_short_exposure_usd: number;
+    net_delta_usd: number;
+    net_delta_pct: number;
+    unrealized_pnl_usd: number | null;
+    collateral_value_usd: number;
+    debt_value_usd: number;
+    estimated_funding_exposure_apy: number | null;
+}
+export interface WalletRiskMetrics {
+    hedge_ratio: number | null;
+    hedge_drift_pct: number | null;
+    collateral_health_score: number | null;
+    minimum_health_factor: number | null;
+    liquidation_proximity_pct: number | null;
+    safety_buffer_score: number | null;
+    capital_at_risk_proxy: number | null;
+    estimated_impairment_loss_usd: number | null;
+    estimated_impairment_loss_pct: number | null;
+    post_impairment_equity_usd: number | null;
+}
+export interface WalletRecommendation {
+    action: WalletAction;
+    summary: string;
+    confidence: number;
+}
+export interface ProtocolError {
+    protocol: WalletProtocol;
+    network: WalletNetwork;
+    message: string;
+    error_type: string;
+    retryable: boolean;
+}
+export interface WalletPortfolioResponse {
+    service: string;
+    wallet_address: string;
+    assessment_status: WalletAssessmentStatus;
+    supported_positions_found: number;
+    unsupported_positions_found: number;
+    data_timestamp: string | null;
+    data_quality: WalletDataQuality;
+    portfolio_summary: WalletPortfolioSummary;
+    risk_metrics: WalletRiskMetrics;
+    strategy_health: WalletStrategyHealth | null;
+    decision_confidence: number | null;
+    recommendation: WalletRecommendation | null;
+    executive_summary: WalletExecutiveSummary | null;
+    primary_drivers: WalletPrimaryDriver[];
+    recommended_plan: WalletPlanStep[];
+    exposure_analysis: WalletExposureAnalysis | null;
+    portfolio_allocation: WalletAllocationItem[];
+    stress_summary: WalletStressSummary | null;
+    largest_risk_contributors: WalletRiskContributor[];
+    portfolio_observations: string[];
+    risk_timeline: WalletRiskTimelineItem[];
+    risk_notes: string[];
+    corrective_actions: string[];
+    positions: NormalizedPosition[];
+    protocol_errors: ProtocolError[];
+    warnings: string[];
+}
+export interface DeltaZeroClientOptions {
+    baseUrl: string;
+    timeoutMs?: number;
+}

package/dist/src/types.js

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "deltazero-core",
+  "version": "0.1.0",
+  "description": "Typed TypeScript client for the DeltaZero deterministic DeFi risk API",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "author": "Akanbi Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Teecash96/DeltaZero.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://delta-zero-alpha.vercel.app",
+  "bugs": {
+    "url": "https://github.com/Teecash96/DeltaZero/issues"
+  },
+  "keywords": [
+    "defi",
+    "risk",
+    "delta-neutral",
+    "okx",
+    "x402"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../frontend/node_modules/typescript/bin/tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.js",
+    "prepack": "npm test"
+  }
+}