@pnllabs/plugin-pnllabs 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# @pnllabs/plugin-pnllabs
+
+**Trust & risk verdicts for AI trading agents on Solana** — [PnL Labs](https://pnllabs.com)
+as an ElizaOS plugin. Give your agent the truth before it copies a wallet or buys a token.
+
+> Every "smart money" score ranks wallets by *peak* gains. Peaks lie. We audited 30
+> tracked "smart money" wallets — **half are genuinely losing money on-chain.** This
+> plugin recomputes *realized* PnL and returns a conservative verdict.
+
+## What your agent gets
+
+| Action | Question | Verdicts |
+|---|---|---|
+| `CHECK_WALLET_TRUST` | Is this wallet worth copying? (real realized PnL) | TRUSTED · NEUTRAL · UNTRUSTED · UNVERIFIABLE |
+| `CHECK_WALLET_FORENSICS` | Where did its money come from? (cluster/Sybil links) | CEX_FUNDED · WALLET_FUNDED · … |
+| `CHECK_TOKEN_SAFETY` | Is this token structurally safe? | LOW_RISK … CRITICAL |
+| `CHECK_TRADE_COST` | What will this trade really cost? (real slippage) | ACCEPTABLE_COST … UNTRADEABLE |
+
+Conservative by design: when numbers can't be reconstructed reliably, it returns
+`UNVERIFIABLE` instead of guessing.
+
+## Install
+
+```bash
+elizaos plugins add @pnllabs/plugin-pnllabs
+```
+
+Then add it to your character's plugins:
+
+```json
+{
+  "name": "MyTradingAgent",
+  "plugins": ["@pnllabs/plugin-pnllabs"]
+}
+```
+
+No API key needed to start — a **daily free tier** lets your agent try every check.
+Beyond that, calls are paid per request via **x402** (USDC on Solana, no signup).
+
+## Config (optional)
+
+| Env | Default | Purpose |
+|---|---|---|
+| `PNLLABS_API_BASE` | `https://api.pnllabs.com` | override API base |
+
+## Example
+
+> **User:** should I copy 57hECCDVNmP7jCY6XX6FxP31DQuKiwQhv2g3nxGPLPmV?
+> **Agent:** *(CHECK_WALLET_TRUST)* → `UNTRUSTED`: genuinely −47 SOL realized, only 27% of coins profitable.
+
+## Links
+
+- Site: https://pnllabs.com · API docs: https://api.pnllabs.com/docs
+- MCP server (for non-Eliza agents): https://github.com/PnLlabs/pnllabs-mcp
+
+MIT © PnL Labs

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from '@elizaos/core';
+
+/**
+ * @pnllabs/plugin-pnllabs — Trust & risk verdicts for AI trading agents on Solana.
+ *
+ * Gives any ElizaOS agent four checks against the hosted PnL Labs API
+ * (https://api.pnllabs.com), paid per call via x402 (free tier to try):
+ *   CHECK_WALLET_TRUST     — proof of real realized PnL (not peak scores)
+ *   CHECK_WALLET_FORENSICS — funding origin & cluster links
+ *   CHECK_TOKEN_SAFETY     — structural token risk
+ *   CHECK_TRADE_COST       — real expected slippage for a size
+ *
+ * No API key needed to try (daily free tier). Behavior-first: verify a wallet
+ * before your agent copies it, a token before it buys.
+ */
+
+declare const pnllabsPlugin: Plugin;
+
+export { pnllabsPlugin as default, pnllabsPlugin };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/index.ts
+var API_BASE = process.env.PNLLABS_API_BASE || "https://api.pnllabs.com";
+var B58 = /[1-9A-HJ-NP-Za-km-z]{32,44}/;
+async function callApi(path) {
+  try {
+    const res = await fetch(API_BASE + path, {
+      headers: { Accept: "application/json" }
+    });
+    if (res.status === 402) {
+      return "This PnL Labs check requires payment via x402 (USDC on Solana). Your daily free tier is used up \u2014 pay-per-call with any x402 client.";
+    }
+    const data = await res.json();
+    return JSON.stringify(data);
+  } catch (e) {
+    return `PnL Labs API error: ${e.message}`;
+  }
+}
+function firstAddress(text) {
+  const m = (text || "").match(B58);
+  return m ? m[0] : null;
+}
+var checkWalletTrust = {
+  name: "CHECK_WALLET_TRUST",
+  similes: ["WALLET_TRUST", "IS_THIS_WALLET_REAL", "PROOF_OF_PNL", "SHOULD_I_COPY_WALLET"],
+  description: "Check whether a Solana wallet is worth copying: recompute REAL realized on-chain PnL (not peak/paper scores) and return a trust verdict. Use before copy-trading or trusting any wallet.",
+  validate: async (_runtime, message) => !!firstAddress(message?.content?.text || ""),
+  handler: async (_runtime, message, _state, _options, callback) => {
+    const addr = firstAddress(message?.content?.text || "");
+    if (!addr) return { success: false, text: "No Solana wallet address found in the message." };
+    const out = await callApi(`/check/wallet/${addr}`);
+    if (callback) await callback({ text: out, source: "pnllabs" });
+    return { success: true, text: out };
+  },
+  examples: [[
+    { name: "user", content: { text: "Should I copy 57hECCDVNmP7jCY6XX6FxP31DQuKiwQhv2g3nxGPLPmV?" } },
+    { name: "agent", content: { text: "Checking realized PnL...", actions: ["CHECK_WALLET_TRUST"] } }
+  ]]
+};
+var checkWalletForensics = {
+  name: "CHECK_WALLET_FORENSICS",
+  similes: ["WALLET_FORENSICS", "WALLET_ORIGIN", "IS_WALLET_FRESH", "FUNDING_SOURCE"],
+  description: "Trace a Solana wallet's funding origin and freshness: CEX-funded (real user), wallet-funded (possible cluster/Sybil), or fresh (insider/bundle risk).",
+  validate: async (_runtime, message) => !!firstAddress(message?.content?.text || ""),
+  handler: async (_runtime, message, _state, _options, callback) => {
+    const addr = firstAddress(message?.content?.text || "");
+    if (!addr) return { success: false, text: "No Solana wallet address found in the message." };
+    const out = await callApi(`/check/funder/${addr}`);
+    if (callback) await callback({ text: out, source: "pnllabs" });
+    return { success: true, text: out };
+  },
+  examples: [[
+    { name: "user", content: { text: "Where did wallet 57hECC... get its money?" } },
+    { name: "agent", content: { text: "Tracing funding origin...", actions: ["CHECK_WALLET_FORENSICS"] } }
+  ]]
+};
+var checkTokenSafety = {
+  name: "CHECK_TOKEN_SAFETY",
+  similes: ["TOKEN_SAFETY", "IS_TOKEN_SAFE", "RUG_CHECK", "TOKEN_RISK"],
+  description: "Structural risk check for a Solana token: real-holder concentration, sniper bots among early buyers, honeypot. Returns LOW_RISK\u2026CRITICAL.",
+  validate: async (_runtime, message) => !!firstAddress(message?.content?.text || ""),
+  handler: async (_runtime, message, _state, _options, callback) => {
+    const mint = firstAddress(message?.content?.text || "");
+    if (!mint) return { success: false, text: "No Solana token mint found in the message." };
+    const out = await callApi(`/check/token/${mint}`);
+    if (callback) await callback({ text: out, source: "pnllabs" });
+    return { success: true, text: out };
+  },
+  examples: [[
+    { name: "user", content: { text: "Is token So11111111111111111111111111111111111111112 safe?" } },
+    { name: "agent", content: { text: "Running token safety check...", actions: ["CHECK_TOKEN_SAFETY"] } }
+  ]]
+};
+var checkTradeCost = {
+  name: "CHECK_TRADE_COST",
+  similes: ["TRADE_COST", "EXPECTED_SLIPPAGE", "WHAT_WILL_THIS_TRADE_COST"],
+  description: "Execution cost oracle: expected slippage for a given size in the token's main pool, calibrated with real-world execution overhead, plus a recommended max size.",
+  validate: async (_runtime, message) => !!firstAddress(message?.content?.text || ""),
+  handler: async (_runtime, message, _state, _options, callback) => {
+    const mint = firstAddress(message?.content?.text || "");
+    if (!mint) return { success: false, text: "No Solana token mint found in the message." };
+    const m = (message?.content?.text || "").match(/([\d.]+)\s*sol/i);
+    const size = m ? m[1] : "0.5";
+    const out = await callApi(`/check/trade/${mint}?size_sol=${size}`);
+    if (callback) await callback({ text: out, source: "pnllabs" });
+    return { success: true, text: out };
+  },
+  examples: [[
+    { name: "user", content: { text: "What will 2 SOL into So111...112 cost me?" } },
+    { name: "agent", content: { text: "Estimating real trade cost...", actions: ["CHECK_TRADE_COST"] } }
+  ]]
+};
+var pnllabsPlugin = {
+  name: "pnllabs",
+  description: "Trust & risk verdicts for AI trading agents on Solana \u2014 realized-PnL wallet trust (not peak scores), wallet funding forensics, token safety, and trade cost. Pay-per-call via x402, free tier to try.",
+  actions: [checkWalletTrust, checkWalletForensics, checkTokenSafety, checkTradeCost]
+};
+var index_default = pnllabsPlugin;
+export {
+  index_default as default,
+  pnllabsPlugin
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pnllabs/plugin-pnllabs",
+  "version": "1.0.0",
+  "description": "Trust & risk verdicts for AI trading agents on Solana: realized-PnL wallet trust (not peak scores), wallet funding forensics, token safety, and trade cost. Pay-per-call via x402, free tier to try.",
+  "keywords": ["plugin", "elizaos", "solana", "x402", "trading", "defi", "wallet", "trust", "risk"],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "images"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "*"
+  },
+  "devDependencies": {
+    "@elizaos/core": "^1.0.0",
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "license": "MIT",
+  "homepage": "https://pnllabs.com",
+  "repository": {
+    "type": "git",
+    "url": "github:PnLlabs/plugin-pnllabs"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "PNLLABS_API_BASE": {
+        "type": "string",
+        "description": "PnL Labs API base URL (default https://api.pnllabs.com)",
+        "required": false
+      }
+    }
+  }
+}