# 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@2.2.2`.

Settlement note: the MCP pins `@x402/core` and `@x402/evm` to `2.11.0`. 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 |
|------|-------------|------|
| `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.

**Payment safeguards.** The server only signs for the CoinOpAI payee wallet on Base mainnet, in USDC, at or below $0.15 per call and $10 per session. It refuses any other payee, network, asset, or amount before signing. Env `X402_MAX_PRICE_USD` and `X402_SESSION_BUDGET_USD` can only lower these caps. The server talks only to `https://x402.coinopai.com` (no redirects, 60s timeout, 2 MB response cap). Use a dedicated, low-balance wallet.

> 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 set for anomaly context ($0.07)
const anomaly = await mcp.call("review_signal_anomaly", {
  symbol: "BTC",
  window: "24h",
  features: {
    price_change: 0.018,
    volume_change: 0.42,
    volatility: 0.031,
    signal_confidence: 72,
    risk_score: 31
  }
})
// review_label: "normal_review" | "review" | "elevated_review" | "critical_review"

// Step 3 — audit 1 hour later ($0.07)
const audit = await mcp.call("audit_trade_decision", {
  decision_id,
  window: "1h"
})
// verdict: "GOOD_DECISION" | "BAD_DIRECTION" | "NOISE"
console.log(audit.verdict, audit.pnl_pct + "%")
```

Every decision response includes a `next_step` field — your agent always knows when and how to audit.

**Symbol unavailable?** If a symbol isn't in the current Kronos cycle:
```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.

---

## Payment Stack

| Component | Value |
|-----------|-------|
| Protocol | [x402](https://x402.org) |
| Scheme | ExactEvmScheme (EIP-3009 `transferWithAuthorization`) |
| Network | Base mainnet (`eip155:8453`) |
| Token | USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) |
| Facilitator | Coinbase |
| Client SDK pins | `@x402/core@2.11.0`, `@x402/evm@2.11.0` |
| Receipt metadata | Successful object responses include `_payment` |

---

## Sponsored cards (Lulu Ads)

Free-tier tool responses may carry a single disclosed sponsored card from [Lulu Ads](https://getlulu.dev). It is a plain, labelled data field on the JSON result — never text the model could read as an instruction:

```json
{
  "results": [...],
  "sponsored": { "label": "Sponsored", "text": "...", "url": "https://..." }
}
```

- **Eligible tools:** `search_agent_automations`, `list_automation_categories`, `get_agent_automation`, `check_trade_preflight` — and only when the response did **not** settle an x402 payment (no `_payment` receipt). A paid response never carries a card.
- **Current state:** one tool is free — `list_tools` (a plain fetch of `/menu`, no wallet, no payment) — so that is the only tool where a card can render today. The other four allowlisted tools are still paid, so no card attaches to them; the switch is server-side: when the operator makes one of those endpoints free (a plain `200` with no `402`), cards start appearing there with no client change.
- **Paid tools never carry it:** `get_crypto_signals`, `get_crypto_risk`, `get_crypto_signal_history`, `get_crypto_decision`, `audit_trade_decision`, `get_crypto_forecast`, `review_signal_anomaly`, `get_futures_decision`, `get_perp_funding`, `check_futures_risk` never touch the ads SDK.
- **Strip it:** `delete result.sponsored`.
- **Where the card comes from:** ForgeMesh's own publisher card is attached server-side to `GET https://x402.coinopai.com/menu`, so `list_tools` simply passes it through — this package ships **no** ad credentials and makes **no** calls to the ads network on its own.
- **Operator env vars (forks only):** `LULU_ADS_PUBLISHER_ID` and `LULU_ADS_API_KEY` let a fork attach its own publisher card client-side (both required; if either is missing the package makes zero calls to the ads network and responses are unchanged). `LULU_ADS_ENABLED=false` is a kill switch.
- **Fail-open:** any SDK error or timeout (hard budget 2s) returns the original response unchanged. The only external host contacted is `ads.getlulu.dev`.

---

## Disclaimer

Decision outputs are probabilistic context and journal entries for experimental automated workflows only. Not financial advice. Directional bias alone has not been validated as a standalone trading strategy. Results will vary. Never risk capital you can't afford to lose.

---

## Part of the ForgeMesh Ecosystem

Infrastructure for monetized agent ecosystems.

| Package | What | Install |
|---------|------|---------|
| [affiliate-router-mcp](https://github.com/forgemeshlabs/affiliate-router-mcp) | Vendor-neutral monetization routing | `npm i affiliate-router-mcp` |
| **coinopai-mcp** | Paid crypto intelligence (this package) | `npm i coinopai-mcp` |
| [forgemesh-imagegen](https://github.com/forgemeshlabs/imagegen-mcp) | Paid image generation MCP | `npm i forgemesh-imagegen` |

Each package works standalone. No shared dependency required.

---

## License

MIT — see [LICENSE](LICENSE)