{
  "markdown": "# coinopai-mcp\n\n[![M8ven Verified](https://m8ven.ai/badge/mcp/forgemeshlabs-coinopai-mcp-1xiffo?variant=verified)](https://m8ven.ai/mcp/forgemeshlabs-coinopai-mcp-1xiffo)\n\n[![npm version](https://img.shields.io/npm/v/coinopai-mcp)](https://www.npmjs.com/package/coinopai-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/coinopai-mcp)](https://www.npmjs.com/package/coinopai-mcp)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n[![payments](https://img.shields.io/badge/payments-x402%20USDC-0052FF)](https://x402.org)\n[![network](https://img.shields.io/badge/network-Base-0052FF)](https://base.org)\n\n**Auditable market context with calibrated forecast ranges and outcome verification.**\n\n**Source:** https://github.com/forgemeshlabs/coinopai-mcp\n\nAn 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.\n\n> This repo is the MCP client layer; paid intelligence is served from hosted CoinOpAI x402 endpoints.\n\n> Weak calls and wrong calls are shown too. That's the point.\n\n## Why Kronos Is Different\n\nMost 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.\n\nThe moat is the audit loop:\n\n```\npreflight -> decision -> audit\n```\n\nTrust the process less. Verify the record more.\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────┐\n│   Claude Code / AI Agent         │\n└──────────────┬───────────────────┘\n               │  MCP (stdio)\n               ▼\n┌──────────────────────────────────┐\n│        coinopai-mcp              │\n│    npx coinopai-mcp              │\n└──────────────┬───────────────────┘\n               │  HTTP + 402 payment header\n               ▼\n┌──────────────────────────────────┐\n│      x402.coinopai.com           │\n│   Kronos intelligence API        │\n└──────────────┬───────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│   Coinbase x402 Facilitator      │\n│   USDC settled on Base mainnet   │\n└──────────────────────────────────┘\n```\n\nThe 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.\n\nCurrent package: `coinopai-mcp@1.2.10`.\n\nSettlement 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.\n\n---\n\n## The Auditable Loop ($0.27/cycle)\n\n```\ncheck_trade_preflight  ──→  get_crypto_decision  ──→  [wait 1h]  ──→  audit_trade_decision\n       $0.05                      $0.15                                      $0.07\n\n   Market state?             Directional context              Outcome record\n   Cooldown context?         Confidence context               Direction held?\n   Regime context?           + decision_id                    Verdict\n   Data freshness?           + audit hint                     + pnl_pct\n```\n\nEvery 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.\n\n## Current Status\n\n**Live**\n- Model context\n- Risk assessment\n- Decision journaling\n- Outcome verification\n- Forecast: conformally-calibrated 80% price range (~0.80 empirical coverage)\n\n**Research**\n- Directional edge: none demonstrated in backtest (~51% accurate) — the calibrated range is the validated product, not the direction\n- Forecast vs execution agreement analysis: collecting evidence\n\nThe 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.\n\n## Directional Context\n\n| Value | Meaning |\n|--------|---------|\n| Positive | Bullish model context |\n| Negative | Bearish model context |\n| 0.00-0.01 | Weak magnitude |\n| 0.01-0.03 | Moderate magnitude |\n| 0.03+ | Strong magnitude |\n\nDirectional values are supporting context, not guarantees, human recommendations, or standalone trade instructions. Use them with the calibrated range, risk state, and audit record.\n\n---\n\n## Real Output\n\n**Step 1 — Preflight (BTC, $0.05)**\n```json\n{\n  \"allowed\": true,\n  \"symbol\": \"BTC/USD\",\n  \"market_state\": \"NORMAL\",\n  \"signal_strength\": \"weak_or_mixed\",\n  \"regime\": \"TREND\",\n  \"cooldown_remaining_seconds\": 0\n}\n```\n\n**Step 2 — Decision (BTC, $0.15)**\n```json\n{\n  \"symbol\": \"BTC/USD\",\n  \"directional_bias\": \"upward\",\n  \"confidence\": 0.514,\n  \"compliance_mode\": \"market_intelligence_only\",\n  \"regime\": \"TREND\",\n  \"decision_id\": \"a3f8c1d2-9472-4dfe-b459-5df17b282614\",\n  \"directional_edge\": \"none_demonstrated\",\n  \"why_not_high\": [\n    \"Directional confidence is capped by observed historical accuracy, not boosted by signal magnitude.\"\n  ],\n  \"next_step\": \"Call audit_trade_decision with this decision_id after 1h using window=1h\"\n}\n```\n\n**Step 3 — Audit (1h later, $0.07)**\n```json\n{\n  \"decision_id\": \"a3f8c1d2-9472-4dfe-b459-5df17b282614\",\n  \"direction_held\": true,\n  \"pnl_pct\": 0.82,\n  \"verdict\": \"GOOD_DECISION\"\n}\n```\n\nAudit 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.\n\nFresh audits can return `pending_window` until the evaluation window matures.\n\n---\n\n## Tools\n\n| Tool | What it does | Cost | Affiliate |\n|------|-------------|------|-----------|\n| `check_trade_preflight` | Gate check: market allowed, cooldown, regime, model context | $0.05 | ✓ |\n| `get_crypto_decision` | Probabilistic decision journal + `decision_id` | $0.15 | ✓ |\n| `audit_trade_decision` | Verify against real prices: verdict + PnL% | $0.07 | ✓ |\n| `get_crypto_signals` | Model context for BTC, ETH, SOL, XRP, ADA | $0.05 | ✓ |\n| `get_crypto_signal_history` | Up to 168h of context history for analysis | $0.05 | ✓ |\n| `get_crypto_forecast` | Conformally-calibrated 80% price range (~0.80 empirical coverage) for BTC, ETH, SOL, XRP, ADA | $0.05 | ✓ |\n| `review_signal_anomaly` | Score signal features for unusual conditions; returns review labels, drivers, and component scores | $0.07 | — |\n| `get_crypto_risk` | Market risk state and cooldown context | $0.02 | — |\n| `search_agent_automations` | Search 819 agent automation prompts | $0.01 | — |\n| `get_agent_automation` | Full prompt + workflow steps by slug | $0.01 | — |\n| `list_automation_categories` | All 35 automation categories with counts | $0.005 | — |\n\nNo API keys. No subscriptions. Pay per call in USDC.\n\n---\n\n## Install\n\n### Claude Code\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"coinopai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"coinopai-mcp\"],\n      \"env\": {\n        \"WALLET_PRIVATE_KEY\": \"0x<your-base-wallet-private-key>\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code. The tools appear automatically.\n\n### Claude Desktop\n\nAdd to your Claude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"coinopai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"coinopai-mcp\"],\n      \"env\": {\n        \"WALLET_PRIVATE_KEY\": \"0x<your-base-wallet-private-key>\"\n      }\n    }\n  }\n}\n```\n\n### Smithery\n\nNot currently listed on Smithery. Use the `npx` install flow shown above until a verified public listing is live.\n\n### Developer smoke-test note\n\nWhen 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`.\n\n### Registry status\n\nPrepared MCP Registry identity: `io.github.forgemeshlabs/coinopai-mcp`. Refresh the public directory submission after publishing this package so old `clawdbotworker` entries stop being canonical.\n\n---\n\n## Get a Wallet\n\n1. Install [Coinbase Wallet](https://wallet.coinbase.com) or any EVM wallet\n2. Switch to **Base** network\n3. Buy or bridge USDC ($1 = ~3 full verified cycles)\n4. Use a dedicated low-balance Base wallet for agent payments and provide its private key locally via environment variable.\n\n> Your wallet key stays local. It never leaves your machine. Each payment is a signed micropayment — not a blanket approval.\n\n---\n\n## Agent Code Example\n\n```js\n// Step 1 — gate check ($0.05)\nconst pre = await mcp.call(\"check_trade_preflight\", { symbol: \"BTC\" })\nif (!pre.allowed) return  // cooldown, bad regime, or stale data\n\n// Step 2 — get decision journal ($0.15)\nconst dec = await mcp.call(\"get_crypto_decision\", { symbol: \"BTC\" })\n\n// Store the decision_id — you'll need it to close the loop\nconst { decision_id, directional_bias, confidence } = dec\n\n// Optional — review a feature set for anomaly context ($0.07)\nconst anomaly = await mcp.call(\"review_signal_anomaly\", {\n  symbol: \"BTC\",\n  window: \"24h\",\n  features: {\n    price_change: 0.018,\n    volume_change: 0.42,\n    volatility: 0.031,\n    signal_confidence: 72,\n    risk_score: 31\n  }\n})\n// review_label: \"normal_review\" | \"review\" | \"elevated_review\" | \"critical_review\"\n\n// Step 3 — audit 1 hour later ($0.07)\nconst audit = await mcp.call(\"audit_trade_decision\", {\n  decision_id,\n  window: \"1h\"\n})\n// verdict: \"GOOD_DECISION\" | \"BAD_DIRECTION\" | \"NOISE\"\nconsole.log(audit.verdict, audit.pnl_pct + \"%\")\n```\n\nEvery decision response includes a `next_step` field — your agent always knows when and how to audit.\n\n**Symbol unavailable?** If a symbol isn't in the current Kronos cycle:\n```json\n{\n  \"status\": \"UNAVAILABLE_THIS_CYCLE\",\n  \"available_symbols\": [\"BTC/USD\", \"ETH/USD\", \"XRP/USD\"],\n  \"retry_hint_seconds\": 900\n}\n```\nRoute to an available symbol or wait 15 minutes for the next cycle.\n\n---\n\n## Payment Stack\n\n| Component | Value |\n|-----------|-------|\n| Protocol | [x402](https://x402.org) |\n| Scheme | ExactEvmScheme (EIP-3009 `transferWithAuthorization`) |\n| Network | Base mainnet (`eip155:8453`) |\n| Token | USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) |\n| Facilitator | Coinbase |\n| Client SDK pins | `@x402/core@2.11.0`, `@x402/evm@2.11.0` |\n| Receipt metadata | Successful object responses include `_payment` |\n\n---\n\n## Affiliate Attribution (via Pyrimid)\n\nHigh-value tools accept an optional `affiliate_id` parameter. When provided, payment routes through the [Pyrimid](https://pyrimid.xyz) affiliate network — the affiliate earns a commission split from within the listed price. **No extra cost to the caller.**\n\n### How the split works\n\n```\nDirect call (no affiliate_id):\n  Caller pays $0.15  →  CoinOpAI receives $0.15\n\nAffiliate call (affiliate_id present):\n  Caller pays $0.15  →  CoinOpAI: 79.2% ($0.1188)\n                      →  Affiliate: 19.8% ($0.0297)\n                      →  Protocol:   1.0% ($0.0015)\n```\n\nThe buyer always pays the listed price. The split comes out of the vendor's portion.\n\n### Usage\n\nPass `affiliate_id` in any supporting tool call:\n\n```js\n// As an agent or user\nawait mcp.call(\"get_crypto_decision\", {\n  symbol: \"BTC\",\n  affiliate_id: \"af_youraffiliateID\"\n})\n```\n\n### Building a wrapper? Set it once via env\n\nIf you're building an agent framework, MCP wrapper, or automation that embeds CoinOpAI tools, set your affiliate ID as an environment variable. Every call through your wrapper earns you a commission automatically.\n\n```json\n{\n  \"mcpServers\": {\n    \"coinopai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"coinopai-mcp\"],\n      \"env\": {\n        \"WALLET_PRIVATE_KEY\": \"0x<agent-wallet-key>\",\n        \"PYRIMID_AFFILIATE_ID\": \"af_<your-affiliate-id>\"\n      }\n    }\n  }\n}\n```\n\nThe tool-level `affiliate_id` argument takes precedence over the env var. Callers can always override.\n\n### Without an affiliate_id\n\nNormal x402 flow — CoinOpAI receives 100% of the listed price. Nothing changes for the caller.\n\n---\n\n## Disclaimer\n\nDecision 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.\n\n---\n\n## Part of the ForgeMesh Ecosystem\n\nInfrastructure for monetized agent ecosystems.\n\n| Package | What | Install |\n|---------|------|---------|\n| [affiliate-router-mcp](https://github.com/forgemeshlabs/affiliate-router-mcp) | Vendor-neutral monetization routing | `npm i affiliate-router-mcp` |\n| **coinopai-mcp** | Paid crypto intelligence (this package) | `npm i coinopai-mcp` |\n| [forgemesh-imagegen](https://github.com/forgemeshlabs/imagegen-mcp) | Paid image generation MCP | `npm i forgemesh-imagegen` |\n\nEach package works standalone. No shared dependency required.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 13398,
  "sha": "d59b17d91f1cabd597d5fd71db1b69107305a06556d2e4fc08833dc6c09d03cf",
  "repo_slug": "forgemeshlabs/coinopai-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_forgemeshlabs_coinopai_mcp_457f5fd0/readme"
}