@skylitai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skylit, Inc.
+
+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,33 @@
+# @skylitai/sdk
+
+A TypeScript client for [Skylit](https://www.skylit.ai) market data. Skylit covers options flow, volatility, dealer positioning (GEX/vanna levels and point-in-time replay) and dark pool, and is built for AI trading agents and the people who build them.
+
+It is typed, has no dependencies, and runs on Node 18+, Bun, Deno and edge runtimes. Every call is read-only: it fetches data and never places orders.
+
+```bash
+npm install @skylitai/sdk
+export SKYLIT_API_KEY=...   # create one at https://app.skylit.ai/developer
+```
+
+```ts
+import { Skylit } from "@skylitai/sdk";
+
+const skylit = new Skylit();
+
+await skylit.account();                                // balance, prices, limits (free)
+await skylit.gexLevels("SPY");                         // king node, gatekeepers, flip, walls
+await skylit.historical("SPY", "2026-09-29T15:30:00Z"); // the board at a past instant
+await skylit.vol("iv", ["SPY", "QQQ"]);                // Tempest implied volatility
+await skylit.flowTone("TSLA");                         // bull/bear pressure across the chain
+await skylit.get("/v1/vol/screener", { limit: 20 });   // any documented endpoint
+```
+
+Responses are the API's JSON, `{ data, meta }`. `meta` carries the remaining credits and the rate-limit state. Errors throw `SkylitError` with `status`, `code` and `message`. Failed calls are not charged.
+
+## Agents
+
+For Claude, ChatGPT, Cursor, the Vercel AI SDK, the OpenAI Agents SDK and other MCP clients, connect to the hosted MCP server at `MCP_URL` (`https://mcp.skylit.ai/mcp`). Setup guides for each client are at [SkylitAI/skylit-mcp](https://github.com/SkylitAI/skylit-mcp).
+
+## Pricing and terms
+
+Calls are billed in credits (1 credit = $0.001; most calls cost 1 to 5). See [the docs](https://www.skylit.ai/docs). Use of Skylit data is governed by the [API Terms](https://www.skylit.ai/api-terms), which cover personal and research use; for commercial use, contact support@skylit.ai. The MIT license covers this client's code, not Skylit data.

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Skylit market data for TypeScript and AI agents.
+ *
+ *   import { Skylit } from "@skylitai/sdk";
+ *   const skylit = new Skylit();          // reads SKYLIT_API_KEY
+ *   await skylit.gexLevels("SPY");
+ *
+ * Read-only: the API serves data and never places orders.
+ * Agents can also connect to the hosted MCP server at MCP_URL.
+ */
+export declare const API_URL = "https://api.skylit.ai";
+export declare const MCP_URL = "https://mcp.skylit.ai/mcp";
+export declare const VERSION = "0.1.0";
+export type Symbols = string | readonly string[];
+export type Params = Record<string, string | number | boolean | readonly string[] | undefined | null>;
+/** Every response is `{ data, meta }`; `meta` carries credits and rate-limit state. */
+export interface SkylitResponse<T = unknown> {
+    data: T;
+    meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface SkylitOptions {
+    /** Defaults to process.env.SKYLIT_API_KEY. Create one at https://app.skylit.ai/developer. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default 30000). */
+    timeoutMs?: number;
+    /** Custom fetch (tests, proxies). Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+/** An error answer from the API. Failed calls are not charged. */
+export declare class SkylitError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare class Skylit {
+    #private;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(options?: SkylitOptions);
+    /** GET any documented endpoint, e.g. `get("/v1/gex/levels", { symbols: "SPY" })`. */
+    get<T = unknown>(path: string, params?: Params): Promise<SkylitResponse<T>>;
+    /** Balance, prices and limits for this key. Free. */
+    account(): Promise<SkylitResponse<unknown>>;
+    /** Symbols covered by the dealer-positioning endpoints. Free. */
+    symbols(): Promise<SkylitResponse<unknown>>;
+    /** Key gamma/vanna levels (king node, gatekeepers, flip, walls) with distance from spot. */
+    gexLevels(symbols: Symbols, params?: Params): Promise<SkylitResponse<unknown>>;
+    /** The live per-strike exposure board. */
+    heatmap(symbols: Symbols, params?: Params): Promise<SkylitResponse<unknown>>;
+    /** The board as it stood at a past instant (`at` is RFC 3339). */
+    historical(symbols: Symbols, at: string, params?: Params): Promise<SkylitResponse<unknown>>;
+    /** Daily exposure statistics per symbol. */
+    statsDaily(symbols: Symbols, params?: Params): Promise<SkylitResponse<unknown>>;
+    /** A Tempest volatility module: iv, term, cones, sigma, tilt, events, surface, derived, snapshot, screener, history or market. */
+    vol(module: string, symbols?: Symbols, params?: Params): Promise<SkylitResponse<unknown>>;
+    /** Bull/bear pressure across a ticker's option chain. */
+    flowTone(ticker: string, timeframe?: string): Promise<SkylitResponse<unknown>>;
+}

package/dist/index.js

@@ -0,0 +1,122 @@
+/**
+ * Skylit market data for TypeScript and AI agents.
+ *
+ *   import { Skylit } from "@skylitai/sdk";
+ *   const skylit = new Skylit();          // reads SKYLIT_API_KEY
+ *   await skylit.gexLevels("SPY");
+ *
+ * Read-only: the API serves data and never places orders.
+ * Agents can also connect to the hosted MCP server at MCP_URL.
+ */
+export const API_URL = "https://api.skylit.ai";
+export const MCP_URL = "https://mcp.skylit.ai/mcp";
+export const VERSION = "0.1.0";
+/** An error answer from the API. Failed calls are not charged. */
+export class SkylitError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(`${status} ${code}: ${message}`);
+        this.status = status;
+        this.code = code;
+        this.name = "SkylitError";
+    }
+}
+const joinSymbols = (s) => (typeof s === "string" ? s : s.join(","));
+export class Skylit {
+    baseUrl;
+    timeoutMs;
+    #key;
+    #fetch;
+    constructor(options = {}) {
+        const env = globalThis.process?.env;
+        const key = options.apiKey ?? env?.SKYLIT_API_KEY;
+        if (!key) {
+            throw new Error("No API key: pass { apiKey } or set SKYLIT_API_KEY (create one at https://app.skylit.ai/developer).");
+        }
+        this.#key = key;
+        this.baseUrl = (options.baseUrl ?? API_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** GET any documented endpoint, e.g. `get("/v1/gex/levels", { symbols: "SPY" })`. */
+    async get(path, params = {}) {
+        const url = new URL(this.baseUrl + "/" + path.replace(/^\/+/, ""));
+        for (const [k, v] of Object.entries(params)) {
+            if (v === undefined || v === null)
+                continue;
+            url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+        }
+        const res = await this.#fetch(url, {
+            headers: { Authorization: `Bearer ${this.#key}`, Accept: "application/json" },
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : {};
+        }
+        catch {
+            body = { error: { code: "invalid_json", message: text.slice(0, 200) } };
+        }
+        if (!res.ok)
+            throw toError(res.status, res.statusText, body);
+        return body;
+    }
+    /** Balance, prices and limits for this key. Free. */
+    account() {
+        return this.get("/v1/account");
+    }
+    /** Symbols covered by the dealer-positioning endpoints. Free. */
+    symbols() {
+        return this.get("/v1/symbols");
+    }
+    /** Key gamma/vanna levels (king node, gatekeepers, flip, walls) with distance from spot. */
+    gexLevels(symbols, params = {}) {
+        return this.get("/v1/gex/levels", { ...params, symbols: joinSymbols(symbols) });
+    }
+    /** The live per-strike exposure board. */
+    heatmap(symbols, params = {}) {
+        return this.get("/v1/heatmap", { ...params, symbols: joinSymbols(symbols) });
+    }
+    /** The board as it stood at a past instant (`at` is RFC 3339). */
+    historical(symbols, at, params = {}) {
+        return this.get("/v1/historical", { ...params, symbols: joinSymbols(symbols), at });
+    }
+    /** Daily exposure statistics per symbol. */
+    statsDaily(symbols, params = {}) {
+        return this.get("/v1/stats/daily", { ...params, symbols: joinSymbols(symbols) });
+    }
+    /** A Tempest volatility module: iv, term, cones, sigma, tilt, events, surface, derived, snapshot, screener, history or market. */
+    vol(module, symbols, params = {}) {
+        return this.get(`/v1/vol/${encodeURIComponent(module)}`, {
+            ...params,
+            symbols: symbols === undefined ? undefined : joinSymbols(symbols),
+        });
+    }
+    /** Bull/bear pressure across a ticker's option chain. */
+    flowTone(ticker, timeframe = "1d") {
+        return this.get(`/v1/chain-bull-bear/${encodeURIComponent(ticker)}`, { timeframe });
+    }
+}
+function toError(status, statusText, body) {
+    let code = "http_error";
+    let message = statusText || "request failed";
+    if (body && typeof body === "object") {
+        const b = body;
+        const e = b.error;
+        if (e && typeof e === "object") {
+            const d = e;
+            if (d.code)
+                code = String(d.code);
+            if (d.message)
+                message = String(d.message);
+        }
+        else if (typeof e === "string") {
+            code = e;
+            if (b.error_description)
+                message = String(b.error_description);
+        }
+    }
+    return new SkylitError(status, code, message);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@skylitai/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript client for Skylit market data: options flow, volatility, dealer positioning (GEX) and dark pool, for AI trading agents.",
+  "license": "MIT",
+  "author": "Skylit, Inc. <support@skylit.ai>",
+  "homepage": "https://www.skylit.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SkylitAI/skylit-mcp.git",
+    "directory": "packages/typescript"
+  },
+  "bugs": "https://github.com/SkylitAI/skylit-mcp/issues",
+  "keywords": [
+    "skylit",
+    "options",
+    "options-flow",
+    "gamma-exposure",
+    "gex",
+    "volatility",
+    "dark-pool",
+    "mcp",
+    "ai-agents",
+    "trading"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/client.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}