io.github.forgemeshlabs/coinopai-mcp

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 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

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)

{
  "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)

{
  "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)

{
  "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

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

Install

Claude Code

Add to ~/.claude/settings.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):

{
  "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 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

// 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:

{
  "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

Sponsored cards (Lulu Ads)

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

{
  "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.

Each package works standalone. No shared dependency required.

License

MIT — see LICENSE