solmachina-sdk 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# solmachina-sdk
+
+The official SDK for the **SolMachina Agent Financial Firewall** — the trust & decision layer an autonomous
+agent calls *before* it moves money.
+
+One call returns **EXECUTE / REVIEW / REJECT** + a risk index (SMRI 0–100) + the evidence + an Ed25519 **signed
+receipt** you can verify offline — plus a **fail-closed policy gate** (`ALLOW` / `DENY`). Paid per call in USDC
+over **x402** (Solana + Base). No account, no API key.
+
+```bash
+npm i solmachina-sdk
+```
+
+## 30-second taste (free, no wallet)
+
+```js
+import { SolMachina } from "solmachina-sdk";
+
+const sm = new SolMachina();
+console.log(await sm.sample("/v1/decision")); // free, truncated preview via the remote MCP
+```
+
+## The one call before your agent moves money
+
+```js
+import { SolMachina } from "solmachina-sdk";
+
+const sm = new SolMachina({ payFetch });      // payFetch = an x402-enabled fetch (below)
+
+const { allowed, decision, reason, failed } = await sm.guard({
+  mint: "So11111111111111111111111111111111111111112",
+  policy: "conservative",                     // conservative | bluechip | anti-rug | degen
+});
+
+if (allowed) {
+  await wallet.send(tx);                       // proceed
+} else {
+  console.warn("blocked:", decision, reason, failed);
+}
+```
+
+`allowed` is `true` **only** when the decision is `EXECUTE` **and** (there is no policy, or the policy verdict is
+`ALLOW`). SolMachina never tells your agent *what* to trade — it decides whether the action your agent already
+chose satisfies its policy, and proves it.
+
+## Enabling payments (`payFetch`)
+
+`payFetch` is any `fetch` that speaks x402 (handles `402 → pay → retry`). Wire it to your wallet with a standard
+x402 client — the SDK stays wallet-agnostic and dependency-free. Example with `x402-fetch`:
+
+```js
+import { wrapFetchWithPayment } from "x402-fetch";
+// ...create your Solana/Base signer with your wallet library of choice...
+const payFetch = wrapFetchWithPayment(fetch, signer);
+
+const sm = new SolMachina({ payFetch });
+```
+
+Without a `payFetch`, paid calls throw `SolMachinaPaymentRequired` carrying the real USDC terms (so you can pay
+them yourself) — never a silent guess.
+
+## Policies
+
+Named preset **or** inline rules (mix freely; explicit rules override a preset):
+
+```js
+await sm.guard({ mint, policy: "anti-rug" });
+await sm.guard({ mint, minSmri: 80, denyMintAuthority: true, denyFreezeAuthority: true });
+await sm.guard({ mint, denyIlliquid: true, minRoundTripRetainedPct: 90 }); // must be sellable
+```
+
+Rules: `minSmri`, `minConfidence`, `maxConcentrationPct`, `denyMintAuthority`, `denyFreezeAuthority`,
+`denyHighRiskBand`, `denyIlliquid`, `minRoundTripRetainedPct`. Every rule is **fail-closed**: if it can't be
+verified from on-chain facts, it fails (DENY) — never a false ALLOW.
+
+## Other endpoints
+
+```js
+await sm.decision(mint, { amountUsd: 5000 });  // full decision object (+ .receipt)
+await sm.smri(mint);                            // just the risk index (cheap, high-frequency)
+await sm.pretrade(mint);                        // one-call pre-trade sweep
+await sm.tokenRisk(mint);
+await sm.walletScan(address);
+await sm.dexQuote(inputMint, outputMint, amount);
+await sm.call("token-holders", { mint });      // escape hatch: any paid endpoint
+```
+
+## Errors
+
+- `SolMachinaPaymentRequired` — a paid call hit 402 and no (or a failing) `payFetch` was set. `err.terms` holds
+  the decoded USDC terms (`resource`, `accepts[]`).
+- `SolMachinaError` — validation or an upstream error; `err.code` mirrors the API (`invalid_mint`,
+  `invalid_policy`, `rpc_unavailable`, …) and `err.details` holds the server body.
+
+## Honesty
+
+Not financial advice, not a profit prediction. SolMachina is a transparent **risk gate** against *your* stated
+thresholds; it returns `REVIEW`/`unknown` instead of guessing, and every paid answer is signed and verifiable.
+
+Docs: https://api.solmachina.com/docs · MCP: `https://api.solmachina.com/mcp` · registry:
+`io.github.imnotamob/solmachina-x402`

package/index.d.ts

@@ -0,0 +1,96 @@
+// Type definitions for solmachina-sdk
+
+export type Verdict = "ALLOW" | "DENY";
+export type Decision = "EXECUTE" | "REVIEW" | "REJECT";
+export type PolicyPreset = "conservative" | "bluechip" | "anti-rug" | "degen";
+
+/** Individual firewall rules (fail-closed: a rule that can't be verified fails). */
+export interface PolicyRules {
+  minSmri?: number;
+  minConfidence?: number;
+  maxConcentrationPct?: number;
+  denyMintAuthority?: boolean;
+  denyFreezeAuthority?: boolean;
+  denyHighRiskBand?: boolean;
+  /** Deny if the token cannot be sold back (honeypot / one-sided liquidity). Requires exit-liquidity enabled. */
+  denyIlliquid?: boolean;
+  /** Deny unless a $100 round-trip retains at least this %. Requires exit-liquidity enabled. */
+  minRoundTripRetainedPct?: number;
+}
+
+export interface DecisionOptions {
+  /** A named preset OR an inline PolicyRules object. */
+  policy?: PolicyPreset | PolicyRules;
+  action?: string;
+  amountUsd?: number | string;
+}
+
+export interface GuardArgs extends PolicyRules {
+  mint: string;
+  policy?: PolicyPreset | PolicyRules;
+  action?: string;
+  amountUsd?: number | string;
+}
+
+export interface GuardResult {
+  /** true only when decision === "EXECUTE" AND (no policy, or policy verdict === "ALLOW"). */
+  allowed: boolean;
+  decision: Decision;
+  verdict: Verdict | null;
+  smri: number | null;
+  confidence: number | null;
+  reason: string;
+  failed: string[];
+  evidence: Record<string, unknown>;
+  /** Ed25519 signed receipt (X-SolMachina-Receipt), verifiable offline; null if absent. */
+  receipt: string | null;
+  raw: Record<string, unknown>;
+}
+
+export interface SolMachinaOptions {
+  baseUrl?: string;
+  /** An x402-enabled fetch for PAID calls (handles 402 -> pay -> retry). */
+  payFetch?: typeof fetch;
+  /** fetch implementation for FREE calls (default: global fetch). */
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface PaymentTerms {
+  resource?: string;
+  accepts: Array<{ network?: string; amount?: string; asset?: string; payTo?: string }>;
+}
+
+export class SolMachinaError extends Error {
+  code: string;
+  details: unknown;
+  constructor(code: string, message?: string, details?: unknown);
+}
+export class SolMachinaPaymentRequired extends SolMachinaError {
+  path: string;
+  terms: PaymentTerms | null;
+}
+
+export class SolMachina {
+  constructor(opts?: SolMachinaOptions);
+  baseUrl: string;
+
+  // free (no payment)
+  catalog(): Promise<Record<string, unknown>>;
+  status(): Promise<Record<string, unknown>>;
+  sample(endpoint?: string): Promise<Record<string, unknown>>;
+
+  // paid (x402 USDC)
+  decision(mint: string, opts?: DecisionOptions): Promise<Record<string, unknown>>;
+  smri(mint: string): Promise<Record<string, unknown>>;
+  pretrade(mint: string): Promise<Record<string, unknown>>;
+  tokenRisk(mint: string): Promise<Record<string, unknown>>;
+  walletScan(address: string): Promise<Record<string, unknown>>;
+  dexQuote(inputMint: string, outputMint: string, amount: string | number, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  call(endpoint: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+
+  /** The one call an agent makes before it moves money. */
+  guard(args: GuardArgs): Promise<GuardResult>;
+}
+
+export default SolMachina;

package/index.mjs

@@ -0,0 +1,121 @@
+// solmachina — the official SDK for the SolMachina Agent Financial Firewall.
+//
+// Turn "understand 20 endpoints + hand-roll x402 payments" into three lines:
+//
+//   import { SolMachina } from "solmachina-sdk";
+//   const sm = new SolMachina({ payFetch });              // payFetch = an x402-enabled fetch (any wallet)
+//   const { allowed } = await sm.guard({ mint, policy: "conservative" });
+//   if (allowed) await wallet.send(tx);
+//
+// Zero dependencies (uses global fetch). Payment is INJECTED: you pass a `payFetch` — an x402-capable fetch
+// that handles 402 -> pay -> retry (e.g. from `x402-fetch`/`@x402/fetch` wired to your signer). This keeps the
+// SDK wallet-agnostic and tiny. Free tools (catalog/status/sample) need no payment. Trust-first: paid calls
+// without a payer throw a clear PaymentRequired carrying the real USDC terms — never a silent guess.
+
+const DEFAULT_BASE = "https://api.solmachina.com";
+const B58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+export class SolMachinaError extends Error {
+  constructor(code, message, details) { super(message || code); this.name = "SolMachinaError"; this.code = code; this.details = details || null; }
+}
+export class SolMachinaPaymentRequired extends SolMachinaError {
+  constructor(path, terms) {
+    super("payment_required", `Paid endpoint ${path} returned HTTP 402. Provide an x402 payFetch to pay automatically (see README), or pay the returned terms manually.`, { terms });
+    this.name = "SolMachinaPaymentRequired"; this.path = path; this.terms = terms || null;
+  }
+}
+
+// Decode the base64 x402 `payment-required` header into readable terms (never throws).
+function decodeTerms(res) {
+  try {
+    const h = res.headers.get?.("payment-required"); if (!h) return null;
+    const json = typeof atob === "function" ? atob(h) : Buffer.from(h, "base64").toString("utf8");
+    const t = JSON.parse(json);
+    return { resource: t?.resource?.url, accepts: (t?.accepts || []).map(a => ({ network: a.network, amount: a.amount, asset: a.asset, payTo: a.payTo })) };
+  } catch { return null; }
+}
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== "") p.set(k, String(v)); const s = p.toString(); return s ? "?" + s : ""; };
+
+export class SolMachina {
+  /**
+   * @param {object} [opts]
+   * @param {string}   [opts.baseUrl]   default https://api.solmachina.com
+   * @param {Function} [opts.payFetch]  an x402-enabled fetch(url, init) for PAID calls (402->pay->retry)
+   * @param {Function} [opts.fetch]     fetch impl for FREE calls (default: global fetch)
+   * @param {number}   [opts.timeoutMs] per-request timeout (default 20000)
+   */
+  constructor(opts = {}) {
+    this.baseUrl = String(opts.baseUrl || DEFAULT_BASE).replace(/\/+$/, "");
+    this.payFetch = typeof opts.payFetch === "function" ? opts.payFetch : null;
+    this.fetch = opts.fetch || globalThis.fetch;
+    this.timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 20000;
+    if (typeof this.fetch !== "function") throw new SolMachinaError("no_fetch", "No fetch available. Pass opts.fetch (Node <18) or run where global fetch exists.");
+  }
+
+  async _get(path, { paid = false } = {}) {
+    const url = this.baseUrl + path;
+    const doFetch = paid ? (this.payFetch || this.fetch) : this.fetch;
+    let res;
+    try { res = await doFetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(this.timeoutMs) }); }
+    catch (e) { throw new SolMachinaError("network_error", String(e?.message || e)); }
+    if (res.status === 402) throw new SolMachinaPaymentRequired(path, decodeTerms(res));
+    let body = null; try { body = await res.json(); } catch { /* leave null */ }
+    if (!res.ok) throw new SolMachinaError(body?.error || `http_${res.status}`, body?.message || `HTTP ${res.status}`, body);
+    if (body && typeof body === "object") { const r = res.headers.get?.("x-solmachina-receipt"); if (r) Object.defineProperty(body, "receipt", { value: r, enumerable: false }); }
+    return body;
+  }
+
+  _mint(m) { if (!B58.test(String(m || ""))) throw new SolMachinaError("invalid_mint", "mint must be a base58 SPL mint address"); return m; }
+
+  // ---- FREE (no payment) ----
+  catalog() { return this._get("/.well-known/x402"); }
+  status() { return this._get("/health"); }
+  /** Free truncated taste of any endpoint via the remote MCP `solmachina_sample` tool. */
+  async sample(endpoint = "/v1/decision") {
+    const res = await this.fetch(this.baseUrl + "/mcp", {
+      method: "POST", headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "solmachina_sample", arguments: { endpoint } } }),
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    const j = await res.json().catch(() => null);
+    const text = j?.result?.content?.[0]?.text;
+    try { return JSON.parse(text); } catch { return j?.result ?? j; }
+  }
+
+  // ---- PAID (x402 USDC) ----
+  /** The flagship. EXECUTE/REVIEW/REJECT + SMRI + evidence + policy firewall (+ signed receipt). */
+  async decision(mint, { policy, action, amountUsd, ...firewall } = {}) {
+    const params = { mint: this._mint(mint), action, amountUsd };
+    if (typeof policy === "string") params.policy = policy;                 // named preset
+    else if (policy && typeof policy === "object") Object.assign(params, policy); // inline rules
+    Object.assign(params, firewall);
+    return this._get("/v1/decision" + qs(params), { paid: true });
+  }
+  async smri(mint) { return this._get("/v1/smri" + qs({ mint: this._mint(mint) }), { paid: true }); }
+  async pretrade(mint) { return this._get("/v1/pretrade" + qs({ mint: this._mint(mint) }), { paid: true }); }
+  async tokenRisk(mint) { return this._get("/v1/token-risk" + qs({ mint: this._mint(mint) }), { paid: true }); }
+  async walletScan(address) { return this._get("/v1/wallet-scan" + qs({ address }), { paid: true }); }
+  async dexQuote(inputMint, outputMint, amount, opts = {}) { return this._get("/v1/dex-quote" + qs({ inputMint, outputMint, amount, ...opts }), { paid: true }); }
+  /** Escape hatch: any paid endpoint by path + params. */
+  async call(endpoint, params = {}) { return this._get("/v1/" + String(endpoint).replace(/^\/?(v1\/)?/, "") + qs(params), { paid: true }); }
+
+  /**
+   * The one call an agent makes before it moves money.
+   * @returns {Promise<{allowed:boolean, decision:string, verdict:string|null, smri:number|null,
+   *   confidence:number|null, reason:string, failed:string[], evidence:object, receipt:string|null, raw:object}>}
+   * `allowed` is true only when the decision is EXECUTE AND (no policy, or the policy verdict is ALLOW).
+   */
+  async guard({ mint, policy, action, amountUsd, ...firewall } = {}) {
+    const d = await this.decision(mint, { policy, action, amountUsd, ...firewall });
+    const verdict = d?.policy?.verdict ?? null;
+    return {
+      allowed: d?.decision === "EXECUTE" && (verdict === null || verdict === "ALLOW"),
+      decision: d?.decision, verdict,
+      smri: d?.smri ?? null, confidence: d?.confidence ?? null,
+      reason: d?.reason || "", failed: d?.policy?.failed || [],
+      evidence: d?.evidence || {}, receipt: d?.receipt || null, raw: d,
+    };
+  }
+}
+
+export default SolMachina;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "solmachina-sdk",
+  "version": "0.1.0",
+  "description": "Official SDK for the SolMachina Agent Financial Firewall — one call returns EXECUTE/REVIEW/REJECT + risk index + evidence + a signed receipt, with a fail-closed policy gate, paid per call in USDC over x402 (Solana + Base).",
+  "type": "module",
+  "main": "index.mjs",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": ["index.mjs", "index.d.ts", "README.md"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "keywords": [
+    "solmachina", "x402", "solana", "base", "usdc", "ai-agents", "agent", "autonomous",
+    "financial-firewall", "decision", "risk", "policy", "mcp", "defi", "trading", "wallet"
+  ],
+  "homepage": "https://api.solmachina.com/docs",
+  "bugs": { "url": "https://api.solmachina.com/security" },
+  "repository": { "type": "git", "url": "git+https://github.com/imnotamob/solmachina.git" },
+  "license": "MIT",
+  "author": "SolMachina"
+}