k402-mcp 是一个 MCP（Model Context Protocol）服务器，为 AI 智能体提供一套可按次付费调用的 API 目录，所有支付结算在 Kaspa L1 上完成。其核心理念是将 x402 的按次付费模式引入 Kaspa 网络，让智能体无需账户、银行卡或 API 密钥即可自主发现、付费并使用服务。
用途
该服务器面向任何支持 MCP 的智能体环境，包括 Claude Code、Claude Desktop 以及各类 agent SDK。它解决的是智能体在调用外部服务时的支付与身份验证问题：传统 API 需要注册账户、绑定支付方式并管理密钥，而 k402-mcp 通过 Kaspa 链上支付实现了无账户、无密钥的按次计费。
主要能力
服务器提供以下类别的 API：
- 文本工具：摘要（summarize）、模式保证的提取（extract）、分类（classify）、改写（rewrite）。
- 网页读取：read_url。
- 嵌入与语义搜索：embed_text、search_index、search_query。
- Kaspa 链上数据：kaspa_balance、kaspa_utxos、kaspa_tx_status、kaspa_fee_estimate、kaspa_network。
- GPU 模型推理：generate，提供多个层级（chat、llama、reason、think、code、kaspa-expert）。
- 契约即服务：covenant_compile、covenant_address、covenant_utxos、covenant_build、covenant_check、covenant_broadcast，用于 Silverscript 契约的编译、派生、检查、构建与广播。
- RISC Zero 证明即服务：prove_guest_upload、prove_preflight、prove_submit、job_status、job_result、attest_verify，支持上传 guest、获取精确周期报价、生成证明并验证。
- 会话与支付管理：catalog（查看所有服务及实时 KAS/USD 价格，免费）、open_session（获取会话及专属 Kaspa 主网充值地址，免费）、session_status（查看余额消耗，免费）、payment_options、pay_per_call。
使用方式
托管端点（零安装）
同一服务器在公共网关以可流式 HTTP 方式托管运行。托管会话按连接隔离：open_session 将支付会话绑定到你的 MCP 连接并返回密钥，保存后可在重连时通过 use_session(<key>) 重新附加。连接之间不共享任何内容。
本地安装（stdio）
适用于 Claude Desktop 或通用 MCP 配置。环境变量均为可选：K402_GATEWAY（默认为公共网关）、K402_SESSION（固定一个已充值的会话密钥）、K402_STATE（自动打开会话的持久化位置，默认 ~/.k402/session.json）。
支付循环
支付流程是智能体原生的：未充值的调用会返回操作指引（“向此地址发送 KAS，本次调用费用为 X”），智能体据此可以自主发现服务、学习付费方式并使用。基本步骤为：调用 open_session 获取会话和专属 Kaspa 主网充值地址（免费），从任意钱包充值（最低 0.25 KAS，数秒内确认），然后即可调用各项服务。
无信任支付通道（kaspa-channel）
在网关支持的情况下，channel_config 和 channel_status 可暴露契约支付通道：你的 KAS 存放在 Kaspa L1 契约中（而非商户钱包），每次调用通过签名凭证支付——商户只能索取你签名的金额，其余部分你可收回。开设和充值通道需要你的 Kaspa 密钥，因此该部分在 k402 Python 客户端（k402.channel）中运行；MCP 工具仅覆盖发现和状态查询。
示例
在 Claude Code 中通过 claude mcp add 添加后，可输入：“Use the k402 tools to check the current Kaspa network status and summarize https://kaspa.org”。首次调用会返回付款指引；为提供的充值地址充值后重试即可。
适用场景
- 智能体需要调用文本处理、网页读取、嵌入搜索等能力，但希望避免账户注册和密钥管理。
- 需要实时 Kaspa 链上数据查询的智能体应用。
- 需要 GPU 推理能力但不想自行部署模型的场景。
- 需要编译、构建或广播 Silverscript 契约的开发者。
- 需要 RISC Zero 零知识证明生成与验证的场景。
- 希望以极低成本（单次调用几分之一美分）按需付费使用 API 的智能体工作流。
限制与注意事项
- 项目为原型（Prototype）。支付结算方式有两种：托管预付费（会话）或通过 kaspa-channel 契约支付通道的无信任方式（已在主网运行，但契约未经审计，通道规模有上限）。
- 建议保持小额余额：几个 KAS 即可覆盖数千次调用。
- 付费工具在未付款时返回 payment_required 及操作指引，而非模糊失败。
- 网关按 IP 进行速率限制；价格随 KAS/USD 浮动，catalog 显示当前价格。
- 需要 KAS 时，任意交易所或钱包均可，充值即普通主网转账。
- 支持的支付币种包括 KAS、BTC、LTC、DOGE、BCH、DASH、ETH、USDC。
- 项目采用 MIT 许可证，版权归 Kaspa Lab 所有。
