{
  "markdown": "# Satoshkin AML/KYT MCP Server\n\n[![CI](https://github.com/satoshkin-dev/satoshkin-aml-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/satoshkin-dev/satoshkin-aml-mcp/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Status: v0.2](https://img.shields.io/badge/status-v0.2%20real%20screening-brightgreen.svg)]()\n\nMCP server for AML/KYT crypto wallet screening. It is designed to connect AI clients such as Claude Desktop, Claude Code, ChatGPT MCP clients, and internal agent tools to Satoshkin wallet risk checks.\n\nThis MCP server provides AI assistants with crypto compliance tools for AML (Anti-Money Laundering) and KYT (Know Your Transaction) screening. Compatible with Claude Desktop, Claude Code, and any MCP-compatible client.\n\nWith an API key configured, checks return real BitOK-backed data: risk score 0-100, risk level, source-of-funds tags, activity dates, and volume totals. Without a key the server runs in clearly-labeled mock mode.\n\n## Status\n\nv0.2.0 performs real AML/KYT screening through the Satoshkin backend\n(`POST /api-accounts/aml-check`, BitOK data) when `SATOSHKIN_API_KEY` is set.\n\nWithout an API key the server runs in mock mode: deterministic, clearly-labeled\nplaceholder responses that can never be mistaken for a real verdict.\n\nThis repository does not contain BitOK credentials, production AML/KYT business logic, user data, or paid-tier enforcement. Those belong in the private backend service.\n\n## Available Tool\n\n### `check_wallet_aml`\n\nChecks a crypto wallet address for AML/KYT risk. Addresses are validated\nagainst per-chain formats client-side before any quota is spent.\n\nInput:\n\n```json\n{\n  \"address\": \"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa\",\n  \"chain\": \"BTC\"\n}\n```\n\nSupported `chain` values:\n\n- `BTC`\n- `ETH`\n- `TRON`\n- `USDT-ERC20`\n- `USDT-TRC20`\n\nReal output (with `SATOSHKIN_API_KEY`):\n\n```json\n{\n  \"address\": \"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa\",\n  \"chain\": \"BTC\",\n  \"checked_at\": \"2026-06-10T12:00:00.000Z\",\n  \"risk_score\": 17,\n  \"risk_level\": \"low\",\n  \"tags\": [\"exchange\"],\n  \"first_activity\": \"2021-01-01\",\n  \"last_activity\": \"2026-06-01\",\n  \"total_volume_in_usd\": \"1000.00\",\n  \"total_volume_out_usd\": \"900.00\",\n  \"source\": \"bitok\",\n  \"cache_hit\": false,\n  \"rate_limit\": { \"remaining\": 999, \"resets_at\": \"2026-06-10T13:00:00.000Z\" },\n  \"balance\": { \"charged_usd\": \"0.55\", \"after_usd\": \"9.45\" }\n}\n```\n\nErrors come back as structured `isError` payloads with machine-readable codes:\n`unauthorized`, `insufficient_balance`, `rate_limited`, `validation_error`,\n`bitok_upstream_error`, `bitok_timeout`, `upstream_unreachable`,\n`invalid_response`, `internal_error`, and `http_<status>` (fallback when a\nbackend error body has no `error` field). Every error payload also carries\nan `http_status` field.\n\nResults are informational risk indicators, not legal or compliance advice.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `SATOSHKIN_API_KEY` | _(unset = mock mode)_ | API key `sk_live_*` / `sk_test_*` issued by Satoshkin |\n| `SATOSHKIN_API_BASE_URL` | `https://satoshkin.com` | Backend base URL (staging override) |\n| `SATOSHKIN_TIMEOUT_MS` | `30000` | Request timeout; first-time checks may take several seconds |\n\n## Claude Desktop / Claude Code\n\nThis package is not published to npm yet. Use the public GitHub repository through `npx`.\n\nAdd this to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"satoshkin-aml\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:satoshkin-dev/satoshkin-aml-mcp\"],\n      \"env\": {\n        \"SATOSHKIN_API_KEY\": \"sk_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nOmit the `env` block to run in mock mode.\n\nFor local development, use the built entrypoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"satoshkin-aml\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/satoshkin-aml-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Local Development\n\n```bash\ngit clone https://github.com/satoshkin-dev/satoshkin-aml-mcp.git\ncd satoshkin-aml-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nRun the server locally:\n\n```bash\nnpm run dev\n```\n\nRun the built server:\n\n```bash\nnpm run build\nnode dist/index.js\n```\n\n## Check Scope\n\nShipped in v0.2:\n\n- Risk score `0-100` + risk level (low / medium / high)\n- Source-of-funds tags\n- First and last activity dates\n- Total volume in and out (USD)\n- Per-key rate limiting and billing through Satoshkin backend authentication\n\nPlanned next: counterparty and cluster analysis, allow/review/block decisions.\n\n## Monetization Model\n\nThe MCP server is a free open-source connector.\n\nReal checks require a Satoshkin API key. Billing is per successful check\n($0.55, debited from a prepaid key balance), the first real check per key is\nfree, and cached repeat checks within 60 seconds are not charged. Keys are\ncurrently issued by [Satoshkin support](https://t.me/satoshkin_support);\na self-service dashboard is in development. Mock mode is free and unlimited.\n\n## Related Satoshkin Products\n\n- P2P bot: https://satoshkin.com\n- AML/KYT Telegram bot: https://t.me/SatoshkinKYTbot\n- AML/KYT web app: planned\n\n## Use Cases\n\n- **OTC desks**: Screen counterparty wallets before settling P2P trades\n- **Compliance officers**: Quick wallet risk checks during AI-assisted workflows\n- **Crypto fund managers**: Vet wallet addresses for sanctions/mixer exposure via AI agent\n- **Web3 builders**: Add AML screening to Claude/ChatGPT-powered dApps\n- **Crypto journalists**: Investigate wallet history with AI assistance\n\n## Why MCP Instead of REST API?\n\nTraditional AML APIs (Chainalysis, Elliptic, TRM Labs) require:\n\n- Custom integrations per AI client\n- Backend infrastructure to broker calls\n- Manual prompt engineering for context\n\nThis MCP server lets any AI assistant call AML checks **natively**, with structured input/output that the LLM understands. Install once, use across all your AI tools.\n\n## Roadmap\n\n- [x] v0.1: Scaffold with mock checks\n- [x] v0.2: Real BitOK integration via Satoshkin backend (per-check billing, free first check, mock mode without key)\n- [ ] v0.3: Self-service key dashboard + top-up\n- [ ] v0.4: Additional chains (Solana, BNB, Polygon)\n- [ ] v0.5: Richer tag taxonomy and sanctions-specific flags\n- [ ] v0.6: Cluster analysis and entity attribution\n\n## License\n\nMIT\n",
  "bytes": 6486,
  "sha": "5f97b57d701492d9c922d1b6d12f898f9bc3ebde5d6cf6808da37a21c5478801",
  "repo_slug": "satoshkin-dev/satoshkin-aml-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_satoshkin_dev_satoshkin_aml_mc_3cc26c51/readme"
}