coinopai-mcp

# coinopai-mcp

[![M8ven Verified](https://m8ven.ai/badge/mcp/forgemeshlabs-coinopai-mcp-1xiffo?variant=verified)](https://m8ven.ai/mcp/forgemeshlabs-coinopai-mcp-1xiffo)

[![npm version](https://img.shields.io/npm/v/coinopai-mcp)](https://www.npmjs.com/package/coinopai-mcp)
[![npm downloads](https://img.shields.io/npm/dm/coinopai-mcp)](https://www.npmjs.com/package/coinopai-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![payments](https://img.shields.io/badge/payments-x402%20USDC-0052FF)](https://x402.org)
[![network](https://img.shields.io/badge/network-Base-0052FF)](https://base.org)
[![mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/forgemeshlabs/coinopai-mcp)

**Auditable market context with calibrated forecast ranges and outcome verification.**

**Source:** https://github.com/forgemeshlabs/coinopai-mcp

An MCP server that lets AI agents buy Kronos market context with [x402](https://x402.org) micropayments on Base. Kronos is not a buy/sell oracle: it gives agents calibrated ranges, risk context, decision journals, and audit records they can verify.

> This repo is the MCP client layer; paid intelligence is served from hosted CoinOpAI x402 endpoints.

> Weak calls and wrong calls are shown too. That's the point.

## Why Kronos Is Different

Most market APIs stop after returning a direction. Kronos leads with calibrated ranges and risk context, then assigns a `decision_id` so every decision can be audited against future market behavior.

The moat is the audit loop:

```
preflight -> decision -> audit
```

Trust the process less. Verify the record more.

---

## Architecture

```
┌──────────────────────────────────┐
│   Claude Code / AI Agent         │
└──────────────┬───────────────────┘
               │  MCP (stdio)
               ▼
┌──────────────────────────────────┐
│        coinopai-mcp              │
│    npx coinopai-mcp              │
└──────────────┬───────────────────┘
               │  HTTP + 402 payment header
               ▼
┌──────────────────────────────────┐
│      x402.coinopai.com           │
│   Kronos intelligence API        │
└──────────────┬───────────────────┘
               │
               ▼
┌──────────────────────────────────┐
│   Coinbase x402 Facilitator      │
│   USDC settled on Base mainnet   │
└──────────────────────────────────┘
```

The agent calls a tool → the MCP server receives an `HTTP 402` → automatically signs a USDC micropayment → retries with the payment header → data returned. Configure once, pay automatically from the configured low-balance wallet.

Current package: `coinopai-mcp@1.2.10`.

Settlement note: the MCP pins `@x402/core` and `@x402/evm` to `2.11.0` and signs EIP-3009 authorizations with a chain-aware timestamp. This avoids the Base RPC/facilitator clock-skew failure mode where a payment can be rejected as "authorization is not yet valid" or "valid before expired". Successful object responses include x402 settlement metadata under `_payment`, including the on-chain transaction hash when available.

---

## The Auditable Loop ($0.27/cycle)

```
check_trade_preflight  ──→  get_crypto_decision  ──→  [wait 1h]  ──→  audit_trade_decision
       $0.05                      $0.15                                      $0.07

   Market state?             Directional context              Outcome record
   Cooldown context?         Confidence context               Direction held?
   Regime context?           + decision_id                    Verdict
   Data freshness?           + audit hint                     + pnl_pct
```

Every decision is self-verifying. The `decision_id` links the setup to the outcome. The audit fetches real market prices and produces a verdict. Nothing is hidden.

## Current Status

**Live**
- Model context
- Risk assessment
- Decision journaling
- Outcome verification
- Forecast: conformally-calibrated 80% price range (~0.80 empirical coverage)

**Research**
- Directional edge: none demonstrated in backtest (~51% accurate) — the calibrated range is the validated product, not the direction
- Forecast vs execution agreement analysis: collecting evidence

The calibrated forecast range is live and validated (conformal, ~0.80 coverage). Directional values are supporting context, not standalone trade instructions. Use them with the calibrated range, risk state, and audit record.

## Directional Context

| Value | Meaning |
|--------|---------|
| Positive | Bullish model context |
| Negative | Bearish model context |
| 0.00-0.01 | Weak magnitude |
| 0.01-0.03 | Moderate magnitude |
| 0.03+ | Strong magnitude |

Directional values are supporting context, not guarantees, human recommendations, or standalone trade instructions. Use them with the calibrated range, risk state, and audit record.

---

## Real Output

**Step 1 — Preflight (BTC, $0.05)**
```json
{
  "allowed": true,
  "symbol": "BTC/USD",
  "market_state": "NORMAL",
  "signal_strength": "weak_or_mixed",
  "regime": "TREND",
  "cooldown_remaining_seconds": 0
}
```

**Step 2 — Decision (BTC, $0.15)**
```json
{
  "symbol": "BTC/USD",
  "directional_bias": "upward",
  "confidence": 0.514,
  "compliance_mode": "market_intelligence_only",
  "regime": "TREND",
  "decision_id": "a3f8c1d2-9472-4dfe-b459-5df17b282614",
  "directional_edge": "none_demonstrated",
  "why_not_high": [
    "Directional confidence is capped by observed historical accuracy, not boosted by signal magnitude."
  ],
  "next_step": "Call audit_trade_decision with this decision_id after 1h using window=1h"
}
```

**Step 3 — Audit (1h later, $0.07)**
```json
{
  "decision_id": "a3f8c1d2-9472-4dfe-b459-5df17b282614",
  "direction_held": true,
  "pnl_pct": 0.82,
  "verdict": "GOOD_DECISION"
}
```

Audit verdicts include `GOOD_DECISION`, `BAD_DIRECTION`, `NOISE`, `NO_ACTION_TAKEN`, and `PENDING`. Kronos gets some right, gets some wrong, and exposes both through the same record.

Fresh audits can return `pending_window` until the evaluation window matures.

---

## Tools

| Tool | What it does | Cost | Affiliate |
|------|-------------|------|-----------|
| `check_trade_preflight` | Gate check: market allowed, cooldown, regime, model context | $0.05 | ✓ |
| `get_crypto_decision` | Probabilistic decision journal + `decision_id` | $0.15 | ✓ |
| `audit_trade_decision` | Verify against real prices: verdict + PnL% | $0.07 | ✓ |
| `get_crypto_signals` | Model context for BTC, ETH, SOL, XRP, ADA | $0.05 | ✓ |
| `get_crypto_signal_history` | Up to 168h of context history for analysis | $0.05 | ✓ |
| `get_crypto_forecast` | Conformally-calibrated 80% price range (~0.80 empirical coverage) for BTC, ETH, SOL, XRP, ADA | $0.05 | ✓ |
| `get_perp_funding` | **Futures.** Live perp funding, mark/index, open interest, crowding (Kraken Futures + Hyperliquid) | $0.02 | — |
| `check_futures_risk` | **Futures.** Will this side / leverage / entry survive the calibrated range? Liquidation distance + verdict | $0.05 | — |
| `get_futures_decision` | **Futures.** LONG / SHORT / FLAT with stop and target on the calibrated range, leverage cap, liquidation, sizing, funding cost | $0.15 | — |
| `review_signal_anomaly` | Score signal features for unusual conditions; returns review labels, drivers, and component scores | $0.07 | — |
| `get_crypto_risk` | Market risk state and cooldown context | $0.02 | — |
| `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 automation categories with counts | $0.005 | — |

No API keys. No subscriptions. Pay per call in USDC.

---

## Install

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "coinopai": {
      "command": "npx",
      "args": ["-y", "coinopai-mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x<your-base-wallet-private-key>"
      }
    }
  }
}
```

Restart Claude Code. The tools appear automatically.

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "coinopai": {
      "command": "npx",
      "args": ["-y", "coinopai-mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x<your-base-wallet-private-key>"
      }
    }
  }
}
```

### Smithery

Not currently listed on Smithery. Use the `npx` install flow shown above until a verified public listing is live.

### Developer smoke-test note

When testing the published package with an MCP stdio harness, do not launch `npx coinopai-mcp@...` from inside the `coinopai-mcp` source checkout. npm can prefer the local package context and fail before the temporary bin is available. Test from another directory, or install into a temp project and launch `./node_modules/.bin/coinopai-mcp`.

### Registry status

Prepared MCP Registry identity: `io.github.forgemeshlabs/coinopai-mcp`. Refresh the public directory submission after publishing this package so old `clawdbotworker` entries stop being canonical.

---

## Get a Wallet

1. Install [Coinbase Wallet](https://wallet.coinbase.com) or any EVM wallet
2. Switch to **Base** network
3. Buy or bridge USDC ($1 = ~3 full verified cycles)
4. Use a dedicated low-balance Base wallet for agent payments and provide its private key locally via environment variable.

> Your wallet key stays local. It never leaves your machine. Each payment is a signed micropayment — not a blanket approval.

---

## Agent Code Example

```js
// Step 1 — gate check ($0.05)
const pre = await mcp.call("check_trade_preflight", { symbol: "BTC" })
if (!pre.allowed) return  // cooldown, bad regime, or stale data

// Step 2 — get decision journal ($0.15)
const dec = await mcp.call("get_crypto_decision", { symbol: "BTC" })

// Store the decision_id — you'll need it to close the loop
const { decision_id, directional_bias, confidence } = dec

// Optional — review a feature