mofu-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mofu contributors
+
+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

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# mofu-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Robinhood Chain token and wallet checks for agents, bots and scripts, from [Mofu](https://mofu.works).
+
+- **Token Scanner:** what a contract allows (mint, pause, blacklist, fees, upgrades, owner), a simulated buy and sell with taxes, how big one sale can be before the price drops 10%, copycats, and whether the code matches known honeypots.
+- **Wallet Health:** every active approval, re-checked on chain, with risky spenders flagged.
+- **Webhooks:** a signed POST when a watched token's owner, supply, code, pause state, liquidity or verdict changes.
+- **A buy rule** you can tune, so an agent refuses what Mofu flags.
+
+No dependencies. Works wherever `fetch` and WebCrypto exist: Node.js 18+, browsers, Cloudflare Workers, Deno, Bun. The API is free: 50 calls a day per IP, shared with Mofu's MCP server and `mofu-cli`.
+
+```sh
+npm install mofu-sdk
+```
+
+## Check a token
+
+```ts
+import { Mofu } from "mofu-sdk";
+
+const mofu = new Mofu();
+const { report, url } = await mofu.scanToken("0xf76593c1c321c2a2f77775025e9677999ce7ea8c");
+
+report.verdict; // "clean" | "caution" | "risky"
+report.sellTest?.status; // "passed" | "failed"
+report.sellTest?.depth?.ethAt10Percent; // ETH one sale can take before the price drops 10%
+report.codeMatch; // same code as tokens whose sell failed, if any
+url; // the shareable report on mofu.works
+```
+
+## Gate a buy
+
+`checkBeforeBuy` scans and applies a rule. If Mofu can't be reached, the answer is no.
+
+```ts
+const d = await mofu.checkBeforeBuy(token, { maxSellTaxPercent: 5, minSellDepthEth: 0.5 });
+if (!d.allowed) return console.log("skip:", d.reasons);
+await yourBuy(token);
+```
+
+| Option              | Default      | Blocks when                                                    |
+| ------------------- | ------------ | -------------------------------------------------------------- |
+| `blockVerdicts`     | `["risky"]`  | the verdict is in the list (any single risk check also blocks) |
+| `requireSellTest`   | `true`       | no sell could be simulated                                     |
+| `maxBuyTaxPercent`  | `10`         | the simulated buy tax is higher                                |
+| `maxSellTaxPercent` | `10`         | the simulated sell tax is higher                               |
+| `blockLookalikes`   | `false`      | another token uses the same name or ticker                     |
+| `minSellDepthEth`   | `null` (off) | a sale this size would move the price more than 10%            |
+
+`decide(report, policy)` is the same rule as a pure function, for reports you already have.
+
+## Check a wallet
+
+```ts
+const { report } = await mofu.checkWallet("0x…");
+report.approvals.filter((a) => a.risk === "risk");
+```
+
+## Webhooks
+
+```ts
+const { webhook, secret } = await mofu.webhooks.create({
+  url: "https://your.domain/mofu",
+  tokens: ["0x…"],
+  events: ["owner_changed", "liquidity_dropped", "verdict_changed"], // leave out for all six
+});
+// Mofu pinged your URL first; keep `secret`, it isn't shown again.
+
+await mofu.webhooks.get(webhook.id, secret); // status, and when each token was last read
+await mofu.webhooks.test(webhook.id, secret);
+await mofu.webhooks.remove(webhook.id, secret);
+```
+
+In your handler, verify the signature against the raw body:
+
+```ts
+import { parseWebhook } from "mofu-sdk";
+
+const event = await parseWebhook(request.headers.get("Mofu-Signature"), rawBody, secret);
+if (event.type === "owner_changed") pause(event.token!.address);
+```
+
+`parseWebhook` throws when the signature is wrong or older than five minutes; `verifyWebhook` returns a boolean instead.
+
+## Errors
+
+Failures throw `MofuError` with `status` and `code`: `daily_limit` (429), `bad_address` (400), `chain_unreachable` (503), `network` (Mofu couldn't be reached).
+
+## Not advice
+
+Mofu reads what a contract's code allows and simulates trades; it can't see the future. A clean report doesn't make a token a good buy.
+
+Docs: <https://mofu.works/docs/#api> · Source: <https://github.com/dev-mofu/mofu/tree/main/packages/sdk> · MIT

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * mofu-sdk: Mofu's Robinhood Chain checks for agents, bots and scripts.
+ * No dependencies; works wherever fetch and WebCrypto exist (Node 18+, browsers, Workers, Deno, Bun).
+ */
+import type { Checked, TokenReport, Verdict, WalletReport, Webhook, WebhookEvent, WebhookEventType } from "./types.js";
+export * from "./types.js";
+export interface MofuOptions {
+    /** Defaults to https://mofu.works. */
+    baseUrl?: string;
+    /** Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Sent as User-Agent where the runtime allows it. */
+    userAgent?: string;
+    /** Per request, in milliseconds. Defaults to 90 000 (a first scan can take half a minute). */
+    timeoutMs?: number;
+}
+/** An answer from Mofu that isn't a report: a bad address, the daily limit, the chain unreachable. */
+export declare class MofuError extends Error {
+    /** HTTP status, or 0 when Mofu couldn't be reached. */
+    readonly status: number;
+    /** Mofu's error code, e.g. "daily_limit", "bad_address", "network". */
+    readonly code: string;
+    name: string;
+    constructor(message: string, 
+    /** HTTP status, or 0 when Mofu couldn't be reached. */
+    status: number, 
+    /** Mofu's error code, e.g. "daily_limit", "bad_address", "network". */
+    code: string);
+}
+export declare class Mofu {
+    private readonly base;
+    private readonly fetchFn;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor(options?: MofuOptions);
+    private call;
+    private static address;
+    /** The Token Scanner report for a token contract on Robinhood Chain. */
+    scanToken(address: string): Promise<Checked<TokenReport>>;
+    /** Wallet Health: every active approval (risky ones flagged) and the tokens a wallet holds. */
+    checkWallet(address: string): Promise<Checked<WalletReport>>;
+    /** Scans a token and applies a buy rule. Says no, with a reason, when Mofu can't be reached. */
+    checkBeforeBuy(address: string, policy?: Partial<Policy>): Promise<Decision>;
+    readonly webhooks: {
+        /**
+         * Watches up to 10 tokens. Mofu pings the URL first and saves the webhook only if it answers
+         * 2xx. The secret comes back once: keep it.
+         */
+        create: (input: {
+            url: string;
+            tokens: string[];
+            events?: WebhookEventType[];
+        }) => Promise<{
+            webhook: Webhook;
+            secret: string;
+        }>;
+        get: (id: string, secret: string) => Promise<Webhook>;
+        test: (id: string, secret: string) => Promise<{
+            delivered: boolean;
+            result: string;
+        }>;
+        remove: (id: string, secret: string) => Promise<void>;
+    };
+}
+export interface Policy {
+    /** Verdicts that block a buy. Default: ["risky"]. */
+    blockVerdicts: Verdict[];
+    /** Block when no sell could be simulated. Default: true. */
+    requireSellTest: boolean;
+    /** Default: 10. */
+    maxBuyTaxPercent: number;
+    /** Default: 10. */
+    maxSellTaxPercent: number;
+    /** Block when another token uses the same name or ticker. Default: false. */
+    blockLookalikes: boolean;
+    /** Block when one sale of this much ETH would move the price more than 10%. Default: off. */
+    minSellDepthEth: number | null;
+}
+export declare const DEFAULT_POLICY: Policy;
+export interface Decision {
+    allowed: boolean;
+    /** Why it was blocked; empty when allowed. */
+    reasons: string[];
+    report: TokenReport | null;
+}
+/** Applies a buy rule to a report. Pure: test it, tune it, log it. */
+export declare function decide(r: TokenReport, policy?: Partial<Policy>): Decision;
+/**
+ * Checks a Mofu-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">) against
+ * the raw request body. Rejects signatures older than `toleranceSeconds` (default 300).
+ */
+export declare function verifyWebhook(signatureHeader: string | null | undefined, rawBody: string, secret: string, options?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<boolean>;
+/** Verifies and parses a webhook delivery. Throws MofuError("bad_signature") when it doesn't check out. */
+export declare function parseWebhook(signatureHeader: string | null | undefined, rawBody: string, secret: string, options?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<WebhookEvent>;

package/dist/index.js

@@ -0,0 +1,172 @@
+export * from "./types.js";
+/** An answer from Mofu that isn't a report: a bad address, the daily limit, the chain unreachable. */
+export class MofuError extends Error {
+    status;
+    code;
+    name = "MofuError";
+    constructor(message, 
+    /** HTTP status, or 0 when Mofu couldn't be reached. */
+    status, 
+    /** Mofu's error code, e.g. "daily_limit", "bad_address", "network". */
+    code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+export class Mofu {
+    base;
+    fetchFn;
+    headers;
+    timeoutMs;
+    constructor(options = {}) {
+        this.base = (options.baseUrl ?? "https://mofu.works").replace(/\/+$/, "");
+        this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+        this.headers = {
+            Accept: "application/json",
+            "User-Agent": options.userAgent ?? "mofu-sdk/0.1",
+        };
+        this.timeoutMs = options.timeoutMs ?? 90_000;
+    }
+    async call(path, init = {}) {
+        let res;
+        try {
+            res = await this.fetchFn(`${this.base}${path}`, {
+                ...init,
+                headers: {
+                    ...this.headers,
+                    ...(init.body ? { "Content-Type": "application/json" } : {}),
+                    ...init.headers,
+                },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            throw new MofuError(`Couldn't reach Mofu: ${err.message}`, 0, "network");
+        }
+        const body = (await res.json().catch(() => null));
+        if (!res.ok || !body) {
+            throw new MofuError(body?.error?.message ?? `Mofu answered HTTP ${res.status}`, res.status, body?.error?.code ?? "http_error");
+        }
+        return body;
+    }
+    static address(a, what) {
+        if (!ADDRESS.test(a))
+            throw new MofuError(`${what} must be 0x followed by 40 hex characters`, 400, "bad_address");
+        return a.toLowerCase();
+    }
+    /** The Token Scanner report for a token contract on Robinhood Chain. */
+    scanToken(address) {
+        return this.call(`/api/v1/token/${Mofu.address(address, "address")}`);
+    }
+    /** Wallet Health: every active approval (risky ones flagged) and the tokens a wallet holds. */
+    checkWallet(address) {
+        return this.call(`/api/v1/wallet/${Mofu.address(address, "address")}`);
+    }
+    /** Scans a token and applies a buy rule. Says no, with a reason, when Mofu can't be reached. */
+    async checkBeforeBuy(address, policy = {}) {
+        try {
+            return decide((await this.scanToken(address)).report, policy);
+        }
+        catch (err) {
+            return {
+                allowed: false,
+                reasons: [`no answer from Mofu: ${err.message}`],
+                report: null,
+            };
+        }
+    }
+    webhooks = {
+        /**
+         * Watches up to 10 tokens. Mofu pings the URL first and saves the webhook only if it answers
+         * 2xx. The secret comes back once: keep it.
+         */
+        create: (input) => this.call("/api/v1/webhooks", {
+            method: "POST",
+            body: JSON.stringify(input),
+        }),
+        get: async (id, secret) => (await this.call(`/api/v1/webhooks/${id}`, { headers: auth(secret) }))
+            .webhook,
+        test: (id, secret) => this.call(`/api/v1/webhooks/${id}/test`, {
+            method: "POST",
+            headers: auth(secret),
+        }),
+        remove: async (id, secret) => {
+            await this.call(`/api/v1/webhooks/${id}`, { method: "DELETE", headers: auth(secret) });
+        },
+    };
+}
+const auth = (secret) => ({ Authorization: `Bearer ${secret}` });
+export const DEFAULT_POLICY = {
+    blockVerdicts: ["risky"],
+    requireSellTest: true,
+    maxBuyTaxPercent: 10,
+    maxSellTaxPercent: 10,
+    blockLookalikes: false,
+    minSellDepthEth: null,
+};
+/** Applies a buy rule to a report. Pure: test it, tune it, log it. */
+export function decide(r, policy = {}) {
+    const p = { ...DEFAULT_POLICY, ...policy };
+    const reasons = [];
+    if (!r.isContract)
+        reasons.push("not a token contract");
+    if (p.blockVerdicts.includes(r.verdict))
+        reasons.push(`Mofu's verdict is ${r.verdict}`);
+    for (const c of r.checks)
+        if (c.status === "risk")
+            reasons.push(`${c.label} ${c.detail}`);
+    const t = r.sellTest;
+    if (t?.status === "failed")
+        reasons.push("a simulated sell failed (possible honeypot)");
+    else if (!t || t.status !== "passed") {
+        if (p.requireSellTest)
+            reasons.push("Mofu couldn't test selling it");
+    }
+    else {
+        if ((t.buyTaxPercent ?? 0) > p.maxBuyTaxPercent)
+            reasons.push(`buy tax ${t.buyTaxPercent}% is over ${p.maxBuyTaxPercent}%`);
+        if ((t.sellTaxPercent ?? 0) > p.maxSellTaxPercent)
+            reasons.push(`sell tax ${t.sellTaxPercent}% is over ${p.maxSellTaxPercent}%`);
+        if (p.minSellDepthEth !== null) {
+            const d = t.depth;
+            if (!d)
+                reasons.push("sell depth couldn't be measured");
+            else if (!d.moreThan && (d.ethAt10Percent ?? 0) < p.minSellDepthEth)
+                reasons.push(`a ${p.minSellDepthEth} ETH sale would move the price more than 10% (depth about ${d.ethAt10Percent ?? 0} ETH)`);
+        }
+    }
+    if (p.blockLookalikes && r.lookalikes.length)
+        reasons.push(`${r.lookalikes.length} other token(s) use the same name or ticker`);
+    return { allowed: reasons.length === 0, reasons: [...new Set(reasons)], report: r };
+}
+// ---------------------------------------------------------------- webhooks
+/**
+ * Checks a Mofu-Signature header (t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">) against
+ * the raw request body. Rejects signatures older than `toleranceSeconds` (default 300).
+ */
+export async function verifyWebhook(signatureHeader, rawBody, secret, options = {}) {
+    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.trim().split("=", 2)));
+    const t = Number(parts.t);
+    const now = Math.floor((options.now ?? Date.now()) / 1000);
+    if (!Number.isFinite(t) || !parts.v1 || Math.abs(now - t) > (options.toleranceSeconds ?? 300))
+        return false;
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, enc.encode(`${t}.${rawBody}`)));
+    const expected = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
+    const given = parts.v1.toLowerCase();
+    if (given.length !== expected.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++)
+        diff |= expected.charCodeAt(i) ^ given.charCodeAt(i);
+    return diff === 0;
+}
+/** Verifies and parses a webhook delivery. Throws MofuError("bad_signature") when it doesn't check out. */
+export async function parseWebhook(signatureHeader, rawBody, secret, options) {
+    if (!(await verifyWebhook(signatureHeader, rawBody, secret, options)))
+        throw new MofuError("The webhook signature doesn't match", 401, "bad_signature");
+    return JSON.parse(rawBody);
+}

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+/** Report shapes returned by Mofu's API (mofu.works/api/v1). */
+export type Verdict = "clean" | "caution" | "risky";
+export interface TokenCheck {
+    id: string;
+    label: string;
+    status: "ok" | "warn" | "risk" | "info";
+    detail: string;
+}
+/** The biggest single sale before the price drops 10%. */
+export interface SellDepth {
+    method: "simulated" | "reserves";
+    /** ETH that sale returns; null when even the smallest size moved the price more than 10%. */
+    ethAt10Percent: number | null;
+    /** True when every size tried stayed under 10%: the real depth is bigger. */
+    moreThan: boolean;
+    steps: Array<{
+        supplyPercent: number | null;
+        ethOut: number;
+        impactPercent: number;
+    }>;
+    detail: string;
+}
+/** A buy and a sell simulated on Robinhood Chain; nothing is sent. */
+export interface SellTest {
+    status: "passed" | "failed" | "unknown";
+    method: "curve" | "transfer";
+    venue: string;
+    buyTaxPercent: number | null;
+    sellTaxPercent: number | null;
+    roundTripPercent: number | null;
+    depth: SellDepth | null;
+    detail: string;
+}
+/** Same code as tokens whose simulated sell failed. */
+export interface CodeMatch {
+    flagged: number;
+    passed: number;
+    examples: Array<{
+        address: string;
+        symbol: string | null;
+    }>;
+}
+export interface TokenReport {
+    address: string;
+    chainName: string;
+    isContract: boolean;
+    codeSize: number;
+    token: {
+        name: string | null;
+        symbol: string | null;
+        decimals: number | null;
+        totalSupply: string | null;
+    };
+    owner: {
+        status: "none" | "renounced" | "active";
+        address: string | null;
+        holdsPercent: number | null;
+    };
+    proxy: {
+        kind: "none" | "eip1967" | "beacon" | "minimal";
+        implementation: string | null;
+    };
+    burnedPercent: number | null;
+    checks: TokenCheck[];
+    verdict: Verdict;
+    distribution: {
+        status: "full" | "summary" | "unavailable";
+        top10Percent: number | null;
+        largestWallet: {
+            address: string;
+            percent: number;
+        } | null;
+        holders: Array<{
+            address: string;
+            balance: string;
+            percent: number;
+            kind: "wallet" | "contract" | "burn";
+        }>;
+    };
+    sellTest: SellTest | null;
+    lookalikes: Array<{
+        address: string;
+        name: string | null;
+        symbol: string | null;
+        createdAt: string | null;
+    }>;
+    fingerprint: string | null;
+    codeMatch: CodeMatch | null;
+    limits: string[];
+}
+export interface AddressInfo {
+    address: string;
+    kind: "wallet" | "burn" | "token" | "curve" | "pool" | "contract";
+    label: string | null;
+    known: boolean;
+    txCount: number | null;
+    firstSeen: string | null;
+    ageDays: number | null;
+}
+export interface WalletApproval {
+    token: string;
+    tokenName: string | null;
+    tokenSymbol: string | null;
+    balance: string | null;
+    spender: AddressInfo;
+    unlimited: boolean;
+    allowance: string;
+    approvedAt: string | null;
+    txHash: string | null;
+    risk: "ok" | "warn" | "risk";
+    reasons: string[];
+}
+export interface WalletReport {
+    address: string;
+    isContract: boolean;
+    eth: string | null;
+    holdings: Array<{
+        token: string;
+        name: string | null;
+        symbol: string | null;
+        balance: string;
+    }>;
+    holdingsTotal: number;
+    approvals: WalletApproval[];
+    status: {
+        holdings: "ok" | "unavailable";
+        approvals: "ok" | "unavailable";
+    };
+    checkedAt: string;
+    limits: string[];
+}
+/** A report plus where to see it and how many calls are left today. */
+export interface Checked<T> {
+    report: T;
+    url: string;
+    remaining: number;
+    limit: number;
+}
+export declare const WEBHOOK_EVENTS: readonly ["owner_changed", "supply_changed", "upgraded", "pause_changed", "liquidity_dropped", "verdict_changed"];
+export type WebhookEventType = (typeof WEBHOOK_EVENTS)[number];
+export interface Webhook {
+    id: string;
+    url: string;
+    tokens: string[];
+    events: WebhookEventType[];
+    createdAt: string;
+    status: "active" | "disabled";
+    disabledAt: string | null;
+    failures: number;
+    delivered: number;
+    lastDeliveryAt: string | null;
+    lastResult: string | null;
+    /** In a status lookup: when Mofu last read each token. */
+    watching?: Array<{
+        address: string;
+        symbol: string | null;
+        verdict: Verdict | null;
+        lastChecked: string | null;
+        lastScanned: string | null;
+    }>;
+}
+/** What Mofu POSTs to a webhook URL. */
+export interface WebhookEvent {
+    id: string;
+    type: WebhookEventType | "ping" | "test";
+    createdAt: string;
+    token: {
+        address: string;
+        name: string | null;
+        symbol: string | null;
+    } | null;
+    summary: string;
+    before: unknown;
+    after: unknown;
+    report: string | null;
+    webhook: string;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/** Report shapes returned by Mofu's API (mofu.works/api/v1). */
+export const WEBHOOK_EVENTS = [
+    "owner_changed",
+    "supply_changed",
+    "upgraded",
+    "pause_changed",
+    "liquidity_dropped",
+    "verdict_changed",
+];

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "mofu-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Robinhood Chain token and wallet checks for agents, bots and scripts: Mofu's Token Scanner, Wallet Health, webhooks and a buy rule.",
+  "license": "MIT",
+  "homepage": "https://mofu.works/docs/#sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-mofu/mofu.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/dev-mofu/mofu/issues"
+  },
+  "keywords": [
+    "robinhood-chain",
+    "token-scanner",
+    "honeypot",
+    "web3",
+    "trading-agent",
+    "webhooks",
+    "security"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=18.17"
+  }
+}