coinopai-mcp 1.0.2 → 1.0.4

package/README.md

@@ -1,24 +1,50 @@
 # coinopai-mcp
 
-MCP server for [CoinOpAI](https://x402.coinopai.com) — agent automation prompts and crypto signals, paid per-call with USDC on Base via the x402 protocol.
+An AI that makes crypto trade decisions — then proves whether it was right.
 
-## What you get
+MCP server for [CoinOpAI](https://x402.coinopai.com). Agents get decisions, then audit them against real prices. Paid per-call with USDC on Base via the [x402 protocol](https://x402.org).
+
+> Don't trust signals. Watch what happens after.
+
+## Quickstart: Your first verified loop ($0.27)
+
+```
+1. Fund wallet with $1 USDC on Base
+2. Call check_trade_preflight("BTC")     → $0.05
+3. Call get_crypto_decision("BTC")       → $0.15
+4. Wait 1 hour
+5. Call audit_trade_decision(decision_id) → $0.07
+```
+
+You get back a verdict: `GOOD_DECISION`, `BAD_DIRECTION`, or `NOISE`.
+
+Real example from a live run:
+
+| Decision | Confidence | 1h Outcome | Verdict |
+|----------|-----------|------------|---------|
+| XRP SHORT | 1.0 | -0.54% | GOOD_DECISION |
+| ETH LONG | 0.68 | -0.32% | BAD_DIRECTION |
+| BTC LONG | 0.40 | +0.01% | NOISE |
+
+It gets some right. It gets some wrong. The difference: it checks itself after.
+
+## Tools
 
 | Tool | What it does | Cost |
 |------|-------------|------|
+| `check_trade_preflight` | Step 1 — gate check: allowed? cooldown? regime? | $0.05 |
+| `get_crypto_decision` | Step 2 — CONSIDER_LONG/SHORT/NO_ACTION + decision_id | $0.15 |
+| `audit_trade_decision` | Step 3 — verify against real prices: verdict + PnL% | $0.07 |
+| `get_crypto_signals` | Raw 15-min directional signals for BTC/ETH/SOL/XRP/ADA | $0.05 |
+| `get_crypto_risk` | Market risk state + regime detection | $0.02 |
+| `get_crypto_signal_history` | Up to 168h of signal history | $0.05 |
 | `search_agent_automations` | Search 819 agent automation prompts | $0.01 |
 | `get_agent_automation` | Full prompt + workflow steps by slug | $0.01 |
 | `list_automation_categories` | All 35 categories with counts | $0.005 |
-| `get_crypto_signals` | Latest hourly BTC/ETH/SOL/XRP/ADA signals | $0.05 |
-| `get_crypto_risk` | Current risk state + regime detection | $0.02 |
-| `get_crypto_signal_history` | Up to 168h of signal history | $0.05 |
 
 No API keys. No subscriptions. Pay only for what you use.
 
-## Requirements
-
-- A Base wallet with USDC funded (any amount — $1 goes a long way at these prices)
-- Node.js 18+
+> **All decision outputs are probabilistic signals for experimental automated workflows only. Not financial advice. Early system — small sample size. Results will vary.**
 
 ## Install in Claude Code
 
@@ -44,11 +70,43 @@ Then restart Claude Code. The tools appear automatically.
 
 1. Install [Coinbase Wallet](https://wallet.coinbase.com) or use any EVM wallet
 2. Switch to Base network
-3. Buy or bridge a small amount of USDC
+3. Buy or bridge a small amount of USDC ($1 runs ~3 full cycles)
 4. Export your private key and add it to the config above
 
 ## How payment works
 
-Each tool call makes a real HTTP request to `x402.coinopai.com`. The server returns a `402 Payment Required` response with the price. The MCP server automatically signs a USDC micropayment using your wallet and resends the request. You get the data. The fee lands on Base mainnet.
+Each tool call hits `x402.coinopai.com`. The server returns `402 Payment Required` with the price. The MCP server automatically signs a USDC micropayment using your wallet and resends the request. You get the data. The fee settles on Base mainnet.
 
 No human approval needed per call — configure once, pay automatically.
+
+## The agent trade loop ($0.27/cycle)
+
+The recommended call sequence — three paid calls, one complete verified cycle:
+
+```js
+// 1. Gate check — is now a good time? ($0.05)
+const pre = await check_trade_preflight({ symbol: "BTC" })
+if (!pre.allowed) return  // cooldown, bad regime, stale data
+
+// 2. Get interpreted decision ($0.15)
+const dec = await get_crypto_decision({ symbol: "BTC" })
+// dec.next_step tells you exactly when and how to audit
+if (dec.suggested_action === "NO_ACTION") return
+
+// 3. Execute your trade here...
+
+// 4. Verify the outcome after 1h ($0.07)
+const result = await audit_trade_decision({
+  decision_id: dec.decision_id,
+  window: "1h"
+})
+// result.outcome.verdict: GOOD_DECISION | BAD_DIRECTION | NOISE
+```
+
+Every decision response includes a `next_step` field with the exact audit endpoint and expected outcomes — so your agent always knows what to do next.
+
+If a symbol isn't in the current Kronos cycle, `check_trade_preflight` returns:
+```json
+{ "status": "UNAVAILABLE_THIS_CYCLE", "available_symbols": ["BTC/USD","ETH/USD","XRP/USD"], "retry_hint_seconds": 900 }
+```
+Route to an available symbol or wait 15 minutes for the next cycle.

package/index.js

@@ -62,7 +62,7 @@ const TOOLS = [
   },
   {
     name: "get_crypto_decision",
-    description: "Interpreted trade decision from Kronos for a crypto symbol. Returns suggested_action (CONSIDER_LONG/CONSIDER_SHORT/NO_ACTION), confidence, regime, risk level, and conservative position guidance. Probabilistic — not financial advice. Costs $0.15 USDC.",
+    description: "Get a probabilistic trade decision from Kronos — then verify it. Returns CONSIDER_LONG/SHORT/NO_ACTION with confidence, regime, and a decision_id. Call audit_trade_decision with that ID after 1h to see if the decision was right. Full loop: preflight ($0.05) → decision ($0.15) → audit ($0.07) = $0.27 per verified cycle. Costs $0.15 USDC.",
     inputSchema: {
       type: "object",
       properties: {
@@ -73,7 +73,7 @@ const TOOLS = [
   },
   {
     name: "check_trade_preflight",
-    description: "Gate check before opening any position. Returns allowed:true/false, market state, cooldown status, signal strength, and warnings. Call this before executing any trade. Costs $0.05 USDC.",
+    description: "Step 1 of the trade loop — checks if conditions allow a trade. Returns allowed:true/false, market state, cooldown, signal strength, warnings. If allowed, proceed to get_crypto_decision. Costs $0.05 USDC.",
     inputSchema: {
       type: "object",
       properties: {
@@ -81,6 +81,18 @@ const TOOLS = [
       },
       required: ["symbol"]
     }
+  },
+  {
+    name: "audit_trade_decision",
+    description: "The accountability step — verify any decision against real prices. Pass the decision_id from get_crypto_decision and a window (1h/4h/24h). Returns: did the direction hold? What was the PnL%? Verdict: GOOD_DECISION, BAD_DIRECTION, or NOISE. Every decision should be audited. Costs $0.07 USDC.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        decision_id: { type: "string", description: "UUID from a previous get_crypto_decision call" },
+        window: { type: "string", description: "Evaluation window: 1h, 4h, or 24h (default: 4h)" }
+      },
+      required: ["decision_id"]
+    }
   }
 ];
 
@@ -134,7 +146,7 @@ async function main() {
   }
 
   const server = new Server(
-    { name: "coinopai-mcp", version: "1.0.2" },
+    { name: "coinopai-mcp", version: "1.0.4" },
     { capabilities: { tools: {} } }
   );
 
@@ -169,6 +181,9 @@ async function main() {
         case "check_trade_preflight":
           data = await call(httpClient, `/api/kronos/preflight?symbol=${encodeURIComponent(args.symbol || "BTC")}`);
           break;
+        case "audit_trade_decision":
+          data = await call(httpClient, `/api/kronos/audit?decision_id=${encodeURIComponent(args.decision_id)}&window=${encodeURIComponent(args.window || "4h")}`);
+          break;
         default:
           throw new Error("Unknown tool: " + name);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coinopai-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "MCP server for CoinOpAI — agent automation prompts and crypto signals via x402 micropayments on Base",
   "main": "index.js",
   "bin": {