coinopai-mcp
README.md
# coinopai-mcp
[](https://m8ven.ai/mcp/forgemeshlabs-coinopai-mcp-1xiffo)
[](https://www.npmjs.com/package/coinopai-mcp)
[](https://www.npmjs.com/package/coinopai-mcp)
[](LICENSE)
[](https://nodejs.org)
[](https://x402.org)
[](https://base.org)
[](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)
TDQS
A4.1/5.0
Scored across 11 tools
Disambiguation5/5
All tools have clearly distinct purposes within two coherent groups (trading analysis workflow and automation catalog). Descriptions explicitly differentiate each tool's role, e.g., check_trade_preflight vs get_crypto_decision vs audit_trade_decision, eliminating ambiguity.
Naming Consistency5/5
Tools follow a consistent snake_case convention with action-based prefixes (get_, audit_, check_, list_, review_, search_). The naming pattern is predictable and transparent, making it easy for an agent to infer functionality.
Tool Count5/5
11 tools is well-scoped for the server's dual purpose of crypto trading analysis and automation prompt retrieval. Each tool has a specific function without unnecessary duplication, and the count falls comfortably in the optimal range.
Completeness5/5
The trading tools cover the full auditable decision loop: preflight check, decision, forecast, risk, signal history, anomaly review, and post-trade audit. The automation tools provide listing, searching, and retrieval. No obvious gaps within the stated domain.
Maintenance
ActivityMaintained
ResponsivenessSlow