@rakshasar/xsignal 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xsignal
+
+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,53 @@
+# ⚡ xsignal
+
+**Pay-per-call data ingredients for AI agents on Base**, via x402 (USDC). The flagship is the one thing no other x402
+signal does: **`get_intent` abstains** — it returns *"no verdict"* (and says so) when it isn't confident enough, instead
+of always answering and always charging. **3 free calls per wallet** to try, then from **$0.01**. Verify-only: never
+signs or moves funds.
+
+## The tools (flagship first)
+| Tool / route | Price | What you get |
+|---|---|---|
+| **`get_intent`** · `GET /intent?addr=0x…&min_confidence=0.7` | $0.01 | An outcome-priced momentum verdict (`gaining`/`fading`) **only if** confidence clears your bar, else a calibrated `abstain`. Paid answers carry a keyless tamper-evidence receipt. |
+| `get_token_brief` · `GET /brief?addr=0x…` | $0.05 | A **meal**: fuses market intel + cited social signal into a "what is happening with $TOKEN now" brief. |
+| `get_signal` · `GET /signal?q=<topic>` | $0.01 | A scored (virality + freshness) and **cited** real-time X/social signal. |
+| `get_token_intel` · `GET /token?addr=0x…` | $0.01 | Base token market data (liquidity/volume/price/age/flow + flags). Best as an input to the brief. |
+| `POST /mcp` | — | MCP (streamable-http): `tools/list` discovers the 4 tools; a `tools/call` returns an x402 **payment pointer**. |
+| `GET /health` · `/.well-known/mcp.json` · `/.well-known/agent-card.json` · `/skill.md` | free | health + agent discovery + the installable skill (no data). |
+
+## Try it free (3 calls per wallet)
+Add `?wallet=0xYourAddress` to any route for **3 free full results**, so you can evaluate quality before paying. After 3,
+that wallet pays via x402.
+```bash
+curl "https://xsignal-production.up.railway.app/intent?addr=0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed&min_confidence=0.5&wallet=0xYourAddr"
+```
+Then run the example — a **watchlist alerter** that surfaces only the tokens confidently moving (and stays quiet on the rest):
+```bash
+WALLET=0xYourAddr node examples/watchlist-alerter.js
+```
+
+## Pay with x402 (beyond the free probe)
+The first post-probe request returns **HTTP 402** with an `accepts` array (price in USDC, network `base`, `payTo`). Pay
+with `x402-fetch`/`x402-axios` and a funded Base wallet, resubmit with the `X-PAYMENT` header, get the result. `/intent`
+is pay-first: you pay, then get a verdict **or** an honest abstain.
+
+## Safety
+**We never sign or move funds.** x402 means we *receive* USDC to `payTo`; payment is **verify-only** via a facilitator.
+Signals are scored from public X posts + public DEX data — *verify before acting; not financial advice.* Confidence is a
+mechanical heuristic, not a calibrated probability or a prediction.
+
+## Config (env)
+| Var | Purpose |
+|---|---|
+| `XSIGNAL_PAYTO` | address that receives USDC (public; no key). Default = the operator address. |
+| `XSIGNAL_PRICE_USD` / `XSIGNAL_BRIEF_PRICE_USD` / `XSIGNAL_INTENT_PRICE_USD` | per-call prices (default `0.01` / `0.05` / `0.01`) |
+| `XSIGNAL_PROBE_FREE` | free probe calls per wallet (default `3`) |
+| `X402_NETWORK` / `FACILITATOR_URL` | `base` (mainnet CDP, needs `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET`) or `base-sepolia` (keyless x402.org) |
+| `X_BEARER_TOKEN` **or** `XAI_API_KEY` | live X/Grok source for `get_signal` (token intel + intent are keyless via DexScreener). No key → a labelled DEMO seed. |
+
+## Run
+```bash
+npm start      # :4520
+npm test       # full self-test suite (signal · tokenintel · brief · intent · x402 · sources · server)
+```
+Zero **runtime** deps for the core (plain Node >=18); `@coinbase/x402` is used only for CDP-facilitator auth on mainnet.

package/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: xsignal
+description: Pay-per-call data ingredients for agents on Base. Flagship get_intent is the only x402 signal that ABSTAINS below your confidence bar (it refuses to answer, honestly, when it is not sure) instead of always returning a guess. Also: a fused token brief, a scored + CITED real-time X/social signal, and Base token market intel. 3 free calls per wallet to try, then micro-paid via x402 (USDC on Base) from $0.01.
+homepage: https://xsignal-production.up.railway.app
+license: MIT
+---
+
+# xsignal — data ingredients that know when to shut up
+
+xsignal sells **paid data ingredients for agents** on Base, priced per call in **USDC via x402**. What makes it different
+from every other x402 data feed: the flagship tool **abstains** — it returns "no verdict" (and says so) when the signal
+isn't strong enough, instead of always answering and always charging. **3 free calls per wallet** to try, then from
+**$0.01**. Verify-only: it never signs or moves your funds.
+
+## The tools (flagship first)
+- **get_intent** ($0.01) — an **outcome-priced momentum verdict that ABSTAINS**. Post `{addr, min_confidence}` → get a
+  mechanical `gaining`/`fading` verdict **only if** the signal agreement clears your bar, else a calibrated `abstain`.
+  This is the one thing no other x402 signal does (the protocol norm is "always answer, always charge"). Paid answers
+  carry a keyless tamper-evidence receipt `{inputHash, outputHash, settlementTx}`. Confidence is a transparent heuristic,
+  **not** a prediction.
+- **get_token_brief** ($0.05, a MEAL) — one call fuses token market intel + real-time social signal into a
+  "what is happening with $TOKEN right now" brief: market flags + top **cited** posts + a plain-language summary.
+- **get_signal** ($0.01) — a scored (virality + freshness) and **cited** real-time X/social signal for any topic.
+- **get_token_intel** ($0.01) — Base token market data (liquidity, volume, price, pool age, buy/sell flow, flags) from
+  public DEX pools. Market data, **not** a trust rating. Best used as an input to the brief.
+
+## How to call it
+
+### Try it free (3 calls per wallet)
+Add `?wallet=0xYourAddress` to any route to get 3 free FULL results, so you can evaluate quality before paying:
+`GET /intent?addr=0x…&min_confidence=0.7&wallet=0xYourAddr`. After 3, that wallet pays via x402.
+
+### x402 (pay-per-call) — where the data is served
+Every route is paid after the free probe: `GET /intent?addr=0x…&min_confidence=0.7` ($0.01) ·
+`GET /brief?addr=0x…` ($0.05) · `GET /signal?q=<topic>` ($0.01) · `GET /token?addr=0x…` ($0.01).
+Flow: the first (post-probe) request returns **HTTP 402** with an `accepts` array (price in USDC, network `base`, `payTo`).
+Pay with `x402-axios`/`x402-fetch` and a funded Base wallet, resubmit with the `X-PAYMENT` header, receive the result.
+`/intent` is pay-first: you pay, then get a verdict **or** an honest abstain.
+
+### MCP (discovery)
+`POST /mcp` (JSON-RPC 2.0). `tools/list` discovers the four tools; a `tools/call` returns an **x402 payment pointer**
+(price + `accepts` + the HTTP endpoint) — MCP has no payment rail, so data is served from the paid HTTP route.
+Discovery (free, no data): `GET /health`, `/.well-known/mcp.json`, `/.well-known/agent-card.json`, `/skill.md`.
+
+## Cost & safety
+- **3 free calls per wallet**, then from **$0.01 USDC** on Base. A funded agent pays in one hop.
+- Honest by design: signals are scored from **public X posts** + **public DEX data**; all are inputs, not decisions —
+  *verify before acting; not financial advice.* Confidence is a mechanical heuristic, not a calibrated probability.
+- Verify-only; holds no keys/funds.
+
+## Example (buyer agent)
+```js
+// 3 free probe calls first (?wallet=you), then x402fetch pays automatically once the probe is used up
+const res = await x402fetch(
+  'https://xsignal-production.up.railway.app/intent?addr=' + addr + '&min_confidence=0.7&wallet=' + myWallet
+).then(r => r.json());
+if (res.served) act(res.verdict, res.evidence, res.receipt); // 'gaining' | 'fading' + cited evidence + receipt
+else skip(res.reason);                                       // abstained: confidence below your bar
+```

package/examples/watchlist-alerter.js

@@ -0,0 +1,46 @@
+'use strict';
+/**
+ * xsignal example — watchlist momentum alerter  (the "reusable workflow" agents pay for)
+ * =====================================================================================
+ * Scan a watchlist of Base tokens and surface ONLY the ones that are confidently moving. This is the
+ * abstention flagship (get_intent) doing what incumbents can't: it stays QUIET on the tokens it isn't
+ * sure about, so your agent acts on signal, not noise.
+ *
+ * Runs FREE out of the box: set WALLET to your 0x address and each token spends one of your 3 free
+ * probe calls per wallet. Beyond 3, wrap fetch with x402 (x402-fetch / x402-axios + a funded Base
+ * wallet) and drop the ?wallet= param — the SAME code then pays $0.01/call automatically.
+ *
+ *   WALLET=0xYourAddr node examples/watchlist-alerter.js
+ */
+const BASE = process.env.XSIGNAL_URL || 'https://xsignal-production.up.railway.app';
+const WALLET = process.env.WALLET || '0x0000000000000000000000000000000000000000'; // your addr → 3 free calls, then pay via x402
+const MIN_CONFIDENCE = Number(process.env.MIN_CONFIDENCE || 0.25); // raise it (e.g. 0.7) to watch xsignal abstain on weak movers
+
+// A Base token watchlist (add your own 0x addresses; xsignal reads the on-chain symbol).
+const WATCHLIST = [
+  '0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed', // DEGEN
+  // '0x...your token...',
+];
+
+async function readIntent(addr) {
+  const url = `${BASE}/intent?addr=${addr}&min_confidence=${MIN_CONFIDENCE}&wallet=${WALLET}`;
+  const r = await fetch(url);
+  if (r.status === 402) return { addr, paywalled: true }; // free probe used up → pay via x402 to continue
+  if (!r.ok) return { addr, error: 'HTTP ' + r.status };
+  return { addr, ...(await r.json()) };
+}
+
+(async () => {
+  console.log(`xsignal watchlist alerter — surfacing only what is confidently moving (min_confidence ${MIN_CONFIDENCE})\n`);
+  const results = await Promise.all(WATCHLIST.map(readIntent));
+  for (const r of results) {
+    const sym = (r.evidence && r.evidence.market && r.evidence.market.symbol) || r.addr.slice(0, 8);
+    if (r.paywalled) console.log(`…  ${r.addr}  free probe used up — add x402 payment to continue`);
+    else if (r.error) console.log(`…  ${r.addr}  (${r.error})`);
+    else if (r.served) console.log(`${r.verdict === 'gaining' ? '🟢' : '🔴'}  $${sym}  ${r.verdict}  (confidence ${r.confidence})`);
+    else console.log(`·   $${sym}  abstain — not confident enough (${r.confidence}); xsignal stays quiet`);
+  }
+  const movers = results.filter((r) => r.served);
+  console.log(`\n${movers.length}/${WATCHLIST.length} confidently moving. The rest: xsignal abstained rather than guess.`);
+  console.log('Not financial advice. Confidence is a mechanical heuristic, not a prediction.');
+})();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@rakshasar/xsignal",
+  "version": "0.2.0",
+  "mcpName": "io.github.philpof102-svg/xsignal",
+  "description": "Pay-per-call data ingredients for AI agents on Base (x402/USDC). Flagship get_intent: the only x402 signal that ABSTAINS below your confidence bar instead of guessing. Also a fused token brief, cited X/social signal, and Base token market intel. 3 free calls per wallet, then from $0.01. Verify-only, never signs.",
+  "main": "sdk/index.js",
+  "exports": {
+    ".": "./sdk/index.js",
+    "./tools": "./sdk/tools.js"
+  },
+  "bin": {
+    "xsignal-mcp": "scripts/mcp-server.js"
+  },
+  "files": [
+    "sdk/",
+    "scripts/mcp-server.js",
+    "examples/",
+    "README.md",
+    "SKILL.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node app.js",
+    "example": "node examples/watchlist-alerter.js",
+    "mcp": "node scripts/mcp-server.js",
+    "test": "node signal.js && node tokenintel.js && node brief.js && node intent.js && node x402.js && node sources.js && node sdk/tools.test.js && node app.js --selftest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "base",
+    "base-mainnet",
+    "ai-agents",
+    "crypto-signal",
+    "token-intel",
+    "abstention",
+    "momentum",
+    "onchain",
+    "usdc",
+    "dexscreener",
+    "agent-tools"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/philpof102-svg/xsignal"
+  },
+  "homepage": "https://xsignal-production.up.railway.app",
+  "bugs": {
+    "url": "https://github.com/philpof102-svg/xsignal/issues"
+  },
+  "dependencies": {
+    "@coinbase/x402": "^2.1.0"
+  }
+}

package/scripts/mcp-server.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * xsignal MCP server (stdio transport).
+ *
+ * Exposes xsignal's pay-per-call data ingredients as a Model Context Protocol server so any
+ * Claude Desktop / Claude Code / Cursor / agent SDK that speaks MCP can attach it as a tool.
+ * Flagship: get_intent — the only x402 signal that ABSTAINS below your confidence bar.
+ *
+ * Install (Claude Desktop / Cursor mcp config):
+ *   {
+ *     "mcpServers": {
+ *       "xsignal": {
+ *         "command": "npx",
+ *         "args": ["-y", "@rakshasar/xsignal", "xsignal-mcp"],
+ *         "env": { "XSIGNAL_WALLET": "0xYourAddress" }
+ *       }
+ *     }
+ *   }
+ *
+ * Set XSIGNAL_WALLET for 3 free calls per wallet; beyond that the tools return an x402 pay pointer.
+ * No deps beyond Node 18+ (native JSON-RPC over stdio; global fetch).
+ */
+const ORIGIN = (process.env.XSIGNAL_ORIGIN || 'https://xsignal-production.up.railway.app').replace(/\/$/, '');
+const WALLET = process.env.XSIGNAL_WALLET || '';
+const SERVER_NAME = 'xsignal';
+const SERVER_VERSION = require('../package.json').version;
+const w = () => (WALLET ? '&wallet=' + WALLET : '');
+
+const TOOLS = [
+  {
+    name: 'get_intent',
+    description: 'FLAGSHIP. An outcome-priced Base-token momentum verdict that ABSTAINS below your confidence bar - the only x402 signal that refuses to answer (honestly) when it is not sure, instead of always guessing. Returns "gaining"/"fading" if confidence clears min_confidence, else "abstain". Confidence is a transparent heuristic, not a prediction; not financial advice.',
+    inputSchema: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' }, min_confidence: { type: 'number', description: '0-1, default 0.6; abstain below this' } } },
+  },
+  {
+    name: 'get_token_brief',
+    description: 'A fused MEAL: Base token market intel + real-time social signal in one "what is happening with $TOKEN now" brief (market flags + cited top posts + a non-advisory summary).',
+    inputSchema: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' }, query: { type: 'string', description: 'optional topic/symbol for the social half' } } },
+  },
+  {
+    name: 'get_signal',
+    description: 'Real-time X/social signal for a topic: scored (virality + freshness) and CITED (source urls), deduped and ranked.',
+    inputSchema: { type: 'object', required: ['query'], properties: { query: { type: 'string', description: 'topic/keywords' } } },
+  },
+  {
+    name: 'get_token_intel',
+    description: 'Base token market data (liquidity, 24h volume, price + change, pool age, buy/sell flow, mechanical flags) from public DEX pools. Market data, NOT a trust rating.',
+    inputSchema: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' } } },
+  },
+  {
+    name: 'get_track_record',
+    description: 'Live transparency for the abstaining flagship: abstention rate + coverage since restart (descriptive activity, not a win-rate).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+async function callApi(path) {
+  const r = await fetch(ORIGIN + path);
+  const j = await r.json().catch(() => ({}));
+  if (r.status === 402) return { paymentRequired: true, ...j, hint: WALLET ? 'Free probe used up for this wallet - pay via x402 (x402-fetch/axios) to continue.' : 'Set XSIGNAL_WALLET env for 3 free calls per wallet, or pay via x402.' };
+  return j;
+}
+
+async function execTool(name, a) {
+  switch (name) {
+    case 'get_intent': return callApi(`/intent?addr=${a.addr}&min_confidence=${a.min_confidence != null ? a.min_confidence : 0.6}` + w());
+    case 'get_token_brief': return callApi(`/brief?addr=${a.addr}` + (a.query ? `&q=${encodeURIComponent(a.query)}` : '') + w());
+    case 'get_signal': return callApi(`/signal?q=${encodeURIComponent(a.query || '')}` + w());
+    case 'get_token_intel': return callApi(`/token?addr=${a.addr}` + w());
+    case 'get_track_record': return callApi('/track-record');
+    default: throw new Error('unknown tool: ' + name);
+  }
+}
+
+function send(msg) { process.stdout.write(JSON.stringify(msg) + '\n'); }
+
+// Minimal JSON-RPC 2.0 over stdio (MCP spec)
+async function handle(req) {
+  const { id, method, params } = req;
+  try {
+    if (method === 'initialize') return { jsonrpc: '2.0', id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: SERVER_NAME, version: SERVER_VERSION } } };
+    if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+    if (method === 'tools/call') { const result = await execTool(params.name, params.arguments || {}); return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } }; }
+    if (method === 'notifications/initialized') return null;
+    return { jsonrpc: '2.0', id, error: { code: -32601, message: 'method not found: ' + method } };
+  } catch (e) { return { jsonrpc: '2.0', id, error: { code: -32000, message: e.message } }; }
+}
+
+let buffer = '';
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk.toString('utf8');
+  let idx;
+  while ((idx = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (!line) continue;
+    let req; try { req = JSON.parse(line); } catch { continue; }
+    const resp = await handle(req);
+    if (resp) send(resp);
+  }
+});
+process.stderr.write(`[xsignal MCP] ready, ${TOOLS.length} tools, origin=${ORIGIN}${WALLET ? ', probe wallet set' : ' (no XSIGNAL_WALLET - tools return pay pointers)'}\n`);

package/sdk/index.js

@@ -0,0 +1,41 @@
+'use strict';
+/**
+ * xsignal SDK — a tiny client for the hosted x402 data ingredients on Base.
+ *
+ *   const xsignal = require('@rakshasar/xsignal');
+ *   const x = xsignal.client({ wallet: '0xYourAddr' });   // wallet → 3 free calls, then x402
+ *   const verdict = await x.intent('0x4ed4…', { minConfidence: 0.7 });
+ *
+ * Every method returns the parsed JSON (a served verdict, an abstain, or an x402 pay pointer with `.paymentRequired`).
+ * `fetch` and `origin` are injectable for tests. Flagship: intent() = the abstaining momentum verdict.
+ */
+const ORIGIN = (process.env.XSIGNAL_ORIGIN || 'https://xsignal-production.up.railway.app').replace(/\/$/, '');
+
+function client(opts = {}) {
+  const base = (opts.origin || ORIGIN).replace(/\/$/, '');
+  const wallet = opts.wallet || process.env.XSIGNAL_WALLET || '';
+  const f = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+  const w = wallet ? '&wallet=' + wallet : '';
+  async function call(path) {
+    if (!f) throw new Error('no fetch available (Node 18+ or pass opts.fetch)');
+    const r = await f(base + path);
+    const j = await r.json().catch(() => ({}));
+    return r.status === 402 ? { paymentRequired: true, ...j } : j;
+  }
+  return {
+    /** FLAGSHIP: momentum verdict that abstains below minConfidence. */
+    intent: (addr, o = {}) => call(`/intent?addr=${addr}&min_confidence=${o.minConfidence != null ? o.minConfidence : 0.6}` + w),
+    /** fused brief (market intel + social signal). */
+    brief: (addr, o = {}) => call(`/brief?addr=${addr}` + (o.query ? `&q=${encodeURIComponent(o.query)}` : '') + w),
+    /** scored + cited real-time X/social signal for a topic. */
+    signal: (query, o = {}) => call(`/signal?q=${encodeURIComponent(query || '')}` + w),
+    /** Base token market data from public DEX pools. */
+    tokenIntel: (addr) => call(`/token?addr=${addr}` + w),
+    /** live abstention transparency (not a win-rate). */
+    trackRecord: () => call('/track-record'),
+    origin: base, wallet,
+  };
+}
+
+module.exports = { client, ORIGIN };
+module.exports.default = module.exports;

package/sdk/tools.js

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * xsignal SDK — LLM tool definitions. One import, plug into any framework:
+ *   OpenAI / Anthropic / Vercel AI SDK / LangChain / Mastra.
+ *
+ *   import { vercelAiSdk } from '@rakshasar/xsignal/tools';
+ *   const result = await generateText({ model, tools: vercelAiSdk({ wallet: '0xYourAddr' }) });
+ *
+ * Each tool's execute() calls the hosted xsignal endpoint (3 free calls per wallet, then an x402 pay pointer)
+ * and returns plain JSON the LLM ingests directly. Flagship: get_intent = the abstaining momentum verdict.
+ */
+const { client } = require('./index.js');
+
+const intentSpec = {
+  name: 'get_intent',
+  description: 'FLAGSHIP. An outcome-priced Base-token momentum verdict that ABSTAINS below your confidence bar - the only x402 signal that refuses to answer (honestly) when it is not sure. Returns gaining/fading if confidence clears min_confidence, else abstain. Confidence is a transparent heuristic, not a prediction; not financial advice.',
+  parameters: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' }, min_confidence: { type: 'number', description: '0-1, default 0.6; abstain below this', minimum: 0, maximum: 1 } } },
+  execute: (a) => client().intent(a.addr, { minConfidence: a.min_confidence }),
+};
+const briefSpec = {
+  name: 'get_token_brief',
+  description: 'A fused MEAL: Base token market intel + real-time social signal in one "what is happening with $TOKEN now" brief (market flags + cited top posts + a non-advisory summary).',
+  parameters: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' }, query: { type: 'string', description: 'optional topic/symbol for the social half' } } },
+  execute: (a) => client().brief(a.addr, { query: a.query }),
+};
+const signalSpec = {
+  name: 'get_signal',
+  description: 'Real-time X/social signal for a topic: scored (virality + freshness) and CITED (source urls), deduped and ranked.',
+  parameters: { type: 'object', required: ['query'], properties: { query: { type: 'string', description: 'topic/keywords' } } },
+  execute: (a) => client().signal(a.query),
+};
+const tokenIntelSpec = {
+  name: 'get_token_intel',
+  description: 'Base token market data (liquidity, 24h volume, price + change, pool age, buy/sell flow, mechanical flags) from public DEX pools. Market data, NOT a trust rating. Best as an input to get_token_brief.',
+  parameters: { type: 'object', required: ['addr'], properties: { addr: { type: 'string', description: '0x Base token address' } } },
+  execute: (a) => client().tokenIntel(a.addr),
+};
+
+const ALL = [intentSpec, briefSpec, signalSpec, tokenIntelSpec];
+
+// Build tool objects whose execute() is bound to a client with per-call opts ({ wallet, origin, fetch }).
+function withOpts(opts = {}) {
+  const c = client(opts);
+  const call = { get_intent: (a) => c.intent(a.addr, { minConfidence: a.min_confidence }), get_token_brief: (a) => c.brief(a.addr, { query: a.query }), get_signal: (a) => c.signal(a.query), get_token_intel: (a) => c.tokenIntel(a.addr) };
+  return ALL.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters, execute: call[t.name] }));
+}
+
+/** OpenAI function-calling shape. */
+function openai() { return ALL.map((t) => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.parameters } })); }
+/** Anthropic Claude tools shape. */
+function anthropic() { return ALL.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters })); }
+/** Vercel AI SDK tools object (keyed by name, with execute bound to your wallet/origin). */
+function vercelAiSdk(opts = {}) { const out = {}; for (const t of withOpts(opts)) out[t.name] = { description: t.description, parameters: t.parameters, execute: t.execute }; return out; }
+/** LangChain DynamicStructuredTool plain-object shape. Wrap with `new DynamicStructuredTool(...)`. */
+function langchain(opts = {}) { return withOpts(opts).map((t) => ({ name: t.name, description: t.description, schema: t.parameters, func: t.execute })); }
+/** Mastra createTool() compatible spec. */
+function mastra(opts = {}) { return withOpts(opts).map((t) => ({ id: t.name, description: t.description, inputSchema: t.parameters, execute: ({ context }) => t.execute(context) })); }
+/** Generic JSON Schema dump. */
+function specs() { return ALL.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })); }
+/** Direct execute by tool name (opts: { wallet, origin, fetch }). */
+async function execute(name, args, opts = {}) { const t = withOpts(opts).find((x) => x.name === name); if (!t) throw new Error('unknown xsignal tool: ' + name); return t.execute(args || {}); }
+
+module.exports = { openai, anthropic, vercelAiSdk, langchain, mastra, specs, execute, intentSpec, briefSpec, signalSpec, tokenIntelSpec };
+module.exports.default = module.exports;

package/sdk/tools.test.js

@@ -0,0 +1,30 @@
+'use strict';
+// xsignal SDK self-test: the framework adapters produce the right shapes + execute() hits the right hosted path
+// (injected fetch → fully offline). Mirrors MainStreet's proven tool-adapter pattern.
+const T = require('./tools.js');
+const calls = [];
+const mockFetch = async (url) => { calls.push(url); return { status: 200, json: async () => ({ ok: true, url }) }; };
+const opts = { fetch: mockFetch, wallet: '0xabc', origin: 'https://x.test' };
+
+(async () => {
+  const oa = T.openai(), an = T.anthropic(), specs = T.specs();
+  const vc = T.vercelAiSdk(opts), lc = T.langchain(opts), ms = T.mastra(opts);
+  const intentRes = await T.execute('get_intent', { addr: '0xTOKEN', min_confidence: 0.7 }, opts);
+  const vcIntent = await vc.get_intent.execute({ addr: '0xTOKEN', min_confidence: 0.7 });
+
+  const checks = [
+    ['4 tools, flagship get_intent first', specs.length === 4 && specs[0].name === 'get_intent'],
+    ['openai shape {type:function, function:{name,parameters}}', oa[0].type === 'function' && oa[0].function.name === 'get_intent' && !!oa[0].function.parameters],
+    ['anthropic shape {name, input_schema}', an[0].name === 'get_intent' && !!an[0].input_schema],
+    ['vercel shape: record keyed by name with execute + parameters', typeof vc.get_intent.execute === 'function' && !!vc.get_intent.parameters],
+    ['langchain shape {name, schema, func}', lc[0].name === 'get_intent' && !!lc[0].schema && typeof lc[0].func === 'function'],
+    ['mastra shape {id, inputSchema, execute}', ms[0].id === 'get_intent' && !!ms[0].inputSchema && typeof ms[0].execute === 'function'],
+    ['execute get_intent → GET /intent with addr + min_confidence + wallet', /\/intent\?addr=0xTOKEN&min_confidence=0\.7&wallet=0xabc/.test(calls.join(' ')) && intentRes.ok === true],
+    ['vercel execute also hits the hosted endpoint', vcIntent.ok === true],
+    ['origin is injectable (all calls hit https://x.test)', calls.length > 0 && calls.every((u) => u.startsWith('https://x.test'))],
+    ['NO fund-moving executor in the surface', !Object.keys(T).some((k) => typeof T[k] === 'function' && /^(sign|send|swap|deploy|transfer|withdraw)/i.test(k))],
+  ];
+  let pass = 0; for (const [n, ok] of checks) { console.log(ok ? 'PASS' : 'FAIL', '·', n); if (ok) pass++; }
+  console.log(`\n${pass}/${checks.length} checks passed`);
+  process.exit(pass === checks.length ? 0 : 1);
+})();