defade 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeFade Ltd
+
+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,105 @@
+# DeFade SDK
+
+[![npm](https://img.shields.io/npm/v/defade)](https://www.npmjs.com/package/defade)
+[![CI](https://github.com/DeFadeLtd/defade-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/DeFadeLtd/defade-sdk/actions)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Official JavaScript/TypeScript client for the [DeFade API](https://defade.org/api-docs) — rug pull risk scores and on-chain behavioral forensics for tokens on **Solana, Ethereum, Base and Robinhood Chain**: launch-block bundle detection, multi-hop funding-origin tracing, deployer history, insider networks, sniper bots, smart-money flow, liquidity verification.
+
+DeFade answers a different question than contract scanners. Not "does this token's code look wrong?" but "did the wallets behind this launch behave like ruggers?" — [99.9% of confirmed Solana rugs had mint authority revoked and 72.9% had locked LP](https://defade.org/blog/state-of-solana-rugs-2026), so token state alone no longer separates safe from staged.
+
+- **Zero dependencies.** Node 18+ (uses global `fetch`). CJS and ESM.
+- **Thin by design.** Responses are the API's JSON, unmodified. `client.get()` reaches any endpoint the SDK hasn't wrapped yet.
+- **Also an MCP server** — Claude and ChatGPT can run real scans through the same API. [See below](#mcp-connector-scan-from-claude--chatgpt).
+
+## Install
+
+```bash
+npm install defade
+```
+
+Get an API key at **[defade.org/developers](https://defade.org/developers)** (keys start with `df_`).
+
+## Quickstart
+
+```js
+import DeFade from 'defade';
+
+const client = new DeFade({ apiKey: process.env.DEFADE_API_KEY });
+
+// Full multi-module scan — returns a SAFETY score (100 = clean)
+const scan = await client.analyze('6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN');
+
+// Rug pull probability (100 = dangerous) with the evidence behind it
+const risk = await client.rugScore('6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN');
+
+// Any endpoint takes ?chain= — omitted means solana
+const eth = await client.holders('0x6982508145454ce325ddbe47a25d4ec3d2311933', { chain: 'ethereum' });
+```
+
+> [!WARNING]
+> **The two scores point in opposite directions.** `analyze()` returns a **safety score** — 100 is clean. `rugScore()` returns a **rug pull probability** — 100 is dangerous. Reading a 90 safety score as "90% chance of rug" produces exactly the wrong answer. Every method's JSDoc restates this.
+
+## Endpoints
+
+All token methods take `(address, { chain? })` and return the API's parsed JSON.
+
+| Group | Methods |
+|---|---|
+| Scan & scores | `analyze`, `rugScore` |
+| Token state | `tokenPrice`, `holders`, `liquidity`, `socials` |
+| Launch forensics | `bundles`, `bundlesPro`, `historicalBundles`, `snipers`, `devTracker`, `feeFingerprint` |
+| Wallet networks | `insiderNetwork`, `fundingOrigin`, `fundingGraph`, `sybilCluster` |
+| Money flow | `whales`, `smartMoney`, `copyTraders`, `kol` |
+| Cross-token | `holderOverlap(mints[])`, `trending` |
+| Account | `usage` |
+| Escape hatch | `get(path, params)` — any `/v1` path |
+
+The API describes itself at [`GET https://api.defade.org/v1`](https://api.defade.org/v1) — endpoint list, plans, unit costs, rate limits and supported chains, always current. From code: `await DeFade.discover()`.
+
+## Chains
+
+`solana` (default), `ethereum`, `base`, `robinhood`. Pass `{ chain: 'base' }` on any token method. EVM chains require an All-Chains plan; a few EVM modules that walk funding graphs cost more units than a standard request — [the discovery document](https://api.defade.org/v1) lists which, and [defade.org/developers](https://defade.org/developers) has current pricing.
+
+## Errors
+
+Every failure throws `DeFadeError` with `.status` (HTTP status, `0` for network/timeout) and `.body` (the API's error JSON when present). Rate-limited calls throw with status `429`; `client.usage()` shows your remaining units and limits. Full scans can take tens of seconds on fresh tokens — the default timeout is 120s, configurable via `timeoutMs`.
+
+```js
+import DeFade, { DeFadeError } from 'defade';
+
+try {
+  await client.analyze(mint);
+} catch (e) {
+  if (e instanceof DeFadeError && e.status === 429) {
+    // back off; e.body has details
+  }
+}
+```
+
+## MCP connector: scan from Claude & ChatGPT
+
+The same API is exposed as a remote [MCP](https://modelcontextprotocol.io) server, so AI assistants can run real scans in-conversation instead of recalling stale training data:
+
+- **URL:** `https://api.defade.org/mcp` (transport: `streamable-http`)
+- **Auth:** `x-api-key` header, or `?api_key=YOUR_KEY` for clients that can't set headers
+- **Registry:** published as [`org.defade/defade`](https://registry.modelcontextprotocol.io/v0/servers?search=defade) in the official MCP Registry
+
+Add it to **Claude Code**:
+
+```bash
+claude mcp add --transport http defade "https://api.defade.org/mcp?api_key=YOUR_KEY"
+```
+
+In **Claude** or **ChatGPT**, add a custom connector with the URL above. Tool calls are metered against your key exactly like REST calls. Full instructions: [defade.org/api-docs#mcp](https://defade.org/api-docs#mcp).
+
+## Links
+
+- [API docs](https://defade.org/api-docs) · [get a key](https://defade.org/developers) · [live API self-description](https://api.defade.org/v1)
+- [The State of Solana Rugs, 2026](https://defade.org/blog/state-of-solana-rugs-2026) — what 18,884 flagged tokens reveal
+- [Why tokens with perfect safety scores still rug](https://defade.org/blog/why-tokens-with-good-scores-still-rug)
+- [defade.org](https://defade.org) — the web scanner (free tier, no key needed)
+
+## License
+
+MIT © DeFade Ltd. This SDK is open source; the DeFade API it talks to is a hosted commercial service with a free tier.

package/index.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+// Thin client for the DeFade API (https://defade.org) — multi-chain memecoin
+// risk analysis. Zero dependencies; Node 18+ (global fetch).
+//
+// The hosted API is the product; this file only shapes requests. Endpoint
+// list, plans and limits are served live at https://api.defade.org/v1 —
+// call DeFade.discover() to read them rather than trusting anything baked
+// into an SDK release.
+
+const DEFAULT_BASE_URL = 'https://api.defade.org';
+const DEFAULT_TIMEOUT_MS = 120_000; // full scans walk funding graphs; they are not instant
+
+class DeFadeError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'DeFadeError';
+    this.status = status; // HTTP status, or 0 for network/timeout failures
+    this.body = body;     // parsed JSON error body when the API sent one
+  }
+}
+
+class DeFade {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiKey  DeFade API key (df_…) — https://defade.org/developers
+   * @param {string} [opts.baseUrl]  Override the API origin (testing/proxies).
+   * @param {number} [opts.timeoutMs]  Per-request timeout. Default 120000.
+   * @param {typeof fetch} [opts.fetch]  Injectable fetch (testing).
+   */
+  constructor(opts = {}) {
+    if (!opts.apiKey || typeof opts.apiKey !== 'string') {
+      throw new DeFadeError('apiKey is required — get one at https://defade.org/developers', 0, null);
+    }
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+    this._fetch = opts.fetch || globalThis.fetch;
+    if (!this._fetch) {
+      throw new DeFadeError('global fetch not found — Node 18+ required, or pass {fetch}', 0, null);
+    }
+  }
+
+  /**
+   * Raw GET against any /v1 path. The typed methods below all route through
+   * here, so an endpoint added server-side is reachable before an SDK update.
+   * @param {string} path  e.g. '/v1/analyze/So11111111111111111111111111111111111111112'
+   * @param {object} [params]  Query parameters (chain, mints, …).
+   */
+  async get(path, params) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(params || {})) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    }
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this._fetch(url, {
+        headers: { 'x-api-key': this.apiKey, accept: 'application/json' },
+        signal: ctrl.signal,
+      });
+    } catch (e) {
+      throw new DeFadeError(
+        e.name === 'AbortError'
+          ? `request timed out after ${this.timeoutMs}ms (full scans can be slow — raise timeoutMs)`
+          : `network error: ${e.message}`,
+        0, null);
+    } finally {
+      clearTimeout(timer);
+    }
+    let body = null;
+    try { body = await res.json(); } catch { /* non-JSON body; keep null */ }
+    if (!res.ok) {
+      const msg = (body && (body.error || body.message)) || `HTTP ${res.status}`;
+      throw new DeFadeError(
+        res.status === 429 ? `${msg} — rate limited; check client.usage() for your plan's limits` : msg,
+        res.status, body);
+    }
+    return body;
+  }
+
+  _token(endpoint, mint, opts) {
+    // Validation failures reject rather than throw, so every failure mode of
+    // an SDK call arrives through the same promise channel.
+    if (!mint) return Promise.reject(new DeFadeError(`${endpoint}: token address is required`, 0, null));
+    return this.get(`/v1/${endpoint}/${encodeURIComponent(mint)}`,
+      opts && opts.chain ? { chain: opts.chain } : undefined);
+  }
+
+  // --- full scan + scores -------------------------------------------------
+
+  /**
+   * Full token analysis. NOTE: analyze() returns a SAFETY score (100 = clean).
+   * rugScore() returns a rug pull PROBABILITY (100 = dangerous). The two
+   * scales point in opposite directions — do not mix them up.
+   */
+  analyze(mint, opts) { return this._token('analyze', mint, opts); }
+
+  /** Rug pull probability 0–100 — HIGHER IS MORE DANGEROUS (see analyze()). */
+  rugScore(mint, opts) { return this._token('rug-score', mint, opts); }
+
+  // --- token state --------------------------------------------------------
+
+  tokenPrice(mint, opts) { return this._token('token-price', mint, opts); }
+  holders(mint, opts) { return this._token('holders', mint, opts); }
+  liquidity(mint, opts) { return this._token('liquidity', mint, opts); }
+  socials(mint, opts) { return this._token('socials', mint, opts); }
+
+  // --- behavioral forensics ----------------------------------------------
+
+  whales(mint, opts) { return this._token('whales', mint, opts); }
+  bundles(mint, opts) { return this._token('bundles', mint, opts); }
+  bundlesPro(mint, opts) { return this._token('bundles-pro', mint, opts); }
+  historicalBundles(mint, opts) { return this._token('historical-bundles', mint, opts); }
+  insiderNetwork(mint, opts) { return this._token('insider-network', mint, opts); }
+  smartMoney(mint, opts) { return this._token('smart-money', mint, opts); }
+  snipers(mint, opts) { return this._token('snipers', mint, opts); }
+  devTracker(mint, opts) { return this._token('dev-tracker', mint, opts); }
+  copyTraders(mint, opts) { return this._token('copy-traders', mint, opts); }
+  fundingOrigin(mint, opts) { return this._token('funding-origin', mint, opts); }
+  fundingGraph(mint, opts) { return this._token('funding-graph', mint, opts); }
+  sybilCluster(mint, opts) { return this._token('sybil-cluster', mint, opts); }
+  feeFingerprint(mint, opts) { return this._token('fee-fingerprint', mint, opts); }
+  kol(mint, opts) { return this._token('kol', mint, opts); }
+
+  // --- cross-token + account ----------------------------------------------
+
+  /** Shared holders across 2+ tokens. @param {string[]} mints */
+  holderOverlap(mints, opts) {
+    if (!Array.isArray(mints) || mints.length < 2) {
+      return Promise.reject(new DeFadeError('holderOverlap: pass an array of 2+ token addresses', 0, null));
+    }
+    const params = { mints: mints.join(',') };
+    if (opts && opts.chain) params.chain = opts.chain;
+    return this.get('/v1/holder-overlap', params);
+  }
+
+  trending(opts) { return this.get('/v1/trending', opts && opts.chain ? { chain: opts.chain } : undefined); }
+
+  /** Remaining units, rate limits and plan for this key. Free to call. */
+  usage() { return this.get('/v1/usage'); }
+
+  /**
+   * The live API self-description: endpoint list, plans, unit costs, chains,
+   * MCP connector details. No API key required.
+   */
+  static async discover(baseUrl) {
+    const res = await fetch((baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '') + '/v1');
+    if (!res.ok) throw new DeFadeError(`discovery failed: HTTP ${res.status}`, res.status, null);
+    return res.json();
+  }
+}
+
+module.exports = { DeFade, DeFadeError };

package/index.d.ts

@@ -0,0 +1,77 @@
+/** Chain id accepted by every token endpoint. Omitted means "solana". */
+export type Chain = 'solana' | 'ethereum' | 'base' | 'robinhood' | (string & {});
+
+export interface DeFadeOptions {
+  /** DeFade API key (df_…) — https://defade.org/developers */
+  apiKey: string;
+  /** Override the API origin. Default: https://api.defade.org */
+  baseUrl?: string;
+  /** Per-request timeout in ms. Default 120000 — full scans are not instant. */
+  timeoutMs?: number;
+  /** Injectable fetch implementation (testing). */
+  fetch?: typeof fetch;
+}
+
+export interface TokenCallOptions {
+  /** Target chain. EVM chains require an All-Chains API plan. */
+  chain?: Chain;
+}
+
+export declare class DeFadeError extends Error {
+  name: 'DeFadeError';
+  /** HTTP status, or 0 for network/timeout/client-side failures. */
+  status: number;
+  /** Parsed JSON error body when the API returned one. */
+  body: unknown;
+}
+
+/**
+ * Thin client for the DeFade API. Responses are returned as parsed JSON
+ * exactly as the API sends them — the API's own /v1 discovery document
+ * (DeFade.discover()) is the source of truth for shapes and limits.
+ */
+export declare class DeFade {
+  constructor(opts: DeFadeOptions);
+
+  /** Raw GET against any /v1 path — escape hatch for endpoints newer than the SDK. */
+  get(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<any>;
+
+  /**
+   * Full token analysis. Returns a SAFETY score where 100 = clean.
+   * Opposite direction from rugScore() — do not mix the two scales.
+   */
+  analyze(mint: string, opts?: TokenCallOptions): Promise<any>;
+  /** Rug pull probability 0–100 where HIGHER = MORE DANGEROUS. */
+  rugScore(mint: string, opts?: TokenCallOptions): Promise<any>;
+
+  tokenPrice(mint: string, opts?: TokenCallOptions): Promise<any>;
+  holders(mint: string, opts?: TokenCallOptions): Promise<any>;
+  liquidity(mint: string, opts?: TokenCallOptions): Promise<any>;
+  socials(mint: string, opts?: TokenCallOptions): Promise<any>;
+
+  whales(mint: string, opts?: TokenCallOptions): Promise<any>;
+  bundles(mint: string, opts?: TokenCallOptions): Promise<any>;
+  bundlesPro(mint: string, opts?: TokenCallOptions): Promise<any>;
+  historicalBundles(mint: string, opts?: TokenCallOptions): Promise<any>;
+  insiderNetwork(mint: string, opts?: TokenCallOptions): Promise<any>;
+  smartMoney(mint: string, opts?: TokenCallOptions): Promise<any>;
+  snipers(mint: string, opts?: TokenCallOptions): Promise<any>;
+  devTracker(mint: string, opts?: TokenCallOptions): Promise<any>;
+  copyTraders(mint: string, opts?: TokenCallOptions): Promise<any>;
+  fundingOrigin(mint: string, opts?: TokenCallOptions): Promise<any>;
+  fundingGraph(mint: string, opts?: TokenCallOptions): Promise<any>;
+  sybilCluster(mint: string, opts?: TokenCallOptions): Promise<any>;
+  feeFingerprint(mint: string, opts?: TokenCallOptions): Promise<any>;
+  kol(mint: string, opts?: TokenCallOptions): Promise<any>;
+
+  /** Shared holders across 2 or more tokens. */
+  holderOverlap(mints: string[], opts?: TokenCallOptions): Promise<any>;
+  trending(opts?: TokenCallOptions): Promise<any>;
+  /** Remaining units, rate limits and plan for this key. */
+  usage(): Promise<any>;
+
+  /** Live API self-description (endpoints, plans, chains, MCP). No key needed. */
+  static discover(baseUrl?: string): Promise<any>;
+}
+
+export default DeFade;

package/index.mjs

@@ -0,0 +1,4 @@
+import cjs from './index.cjs';
+export const DeFade = cjs.DeFade;
+export const DeFadeError = cjs.DeFadeError;
+export default cjs.DeFade;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "defade",
+  "version": "0.1.0",
+  "description": "Official SDK for the DeFade API — rug pull risk scores and on-chain forensics (bundles, funding traces, deployer history) for tokens on Solana, Ethereum, Base and Robinhood Chain.",
+  "license": "MIT",
+  "author": "DeFade Ltd (https://defade.org)",
+  "homepage": "https://defade.org/api-docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DeFadeLtd/defade-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DeFadeLtd/defade-sdk/issues"
+  },
+  "main": "./index.cjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "index.cjs",
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/client.test.js"
+  },
+  "keywords": [
+    "defade",
+    "rug pull",
+    "rug checker",
+    "solana",
+    "ethereum",
+    "base",
+    "memecoin",
+    "token security",
+    "rug score",
+    "bundle detection",
+    "insider detection",
+    "wallet forensics",
+    "mcp",
+    "crypto security api"
+  ]
+}