Cronos402 (d9e341)

Cronos402 SDK和CLI

第一个专门为Cronos区块链构建的MCP支付网关。

](https://www.npmjs.com/package/cronos402) ](https://www.npmjs.com/package/cronos402)

TypeScript SDK和CLI，用于通过Cronos上的x402协议连接到具有支付功能的MCP（模型上下文协议）服务器。构建接受USDC.e和CRO支付的AI代理和MCP服务器。

包裹:

特性

• 克罗诺斯本地人：专为Cronos主网和测试网构建
• 多服务器代理：一次连接到多个MCP服务器
• USDC.e支持：通过Cronos协调员进行无气支付（EIP-3009）
• 本地CRO：使用用户控制的天然气直接支付CRO
• 402需要付款：通过x402协议自动支付处理
• MCP集成：完整的模型上下文协议服务器和客户端支持
• 程序化API：适用于客户端和服务器
• 简易SDK：简单 paidTool 用于构建付费工具的API
• 类型安全：viem完全支持TypeScript

快速开始

全局安装CLI或使用 npx:

npm i -g cronos402
# or
npx cronos402 connect -u "https://api.example.com/mcp" -a ""

向一个或多个MCP服务器启动支持支付的stdio代理：

# Using a Cronos private key (Payment transport)
cronos402 connect -u "https://api.example.com/mcp" -k 0x1234... -n cronos-testnet

# Using an API key only (HTTP transport)
cronos402 connect -u "https://api.example.com/mcp" -a "$API_KEY"

提示：您可以传递多个URL： -u "https://api1/mcp,https://api2/mcp".

安装

SDK（项目依赖性）

npm i cronos402
# or
pnpm i cronos402
# or
yarn add cronos402

CLI（全局工具）

npm i -g cronos402
# or use npx
npx cronos402 connect --help

CLI使用情况

命令

• cronos402 connect –启动具有支付功能的远程服务器的MCP stdio代理
• cronos402 version –显示版本信息

例子

# Basic (env vars)
export SERVER_URLS="https://api.example.com/mcp"
export CRONOS_PRIVATE_KEY="0x1234..."
cronos402 connect -u "$SERVER_URLS"

# Multiple servers + API key header forwarded to remotes
cronos402 connect -u "https://api1/mcp,https://api2/mcp" -a "$API_KEY"

# Using Cronos wallet with specific network
cronos402 connect -u "https://api.example.com/mcp" -k 0x1234... -n cronos-mainnet

# Set maximum payment amount
cronos402 connect -u "https://api.example.com/mcp" -k 0x1234... --max-atomic 1000000

选项

行为：

• 如果 -k 或 --private-key 代理使用支付传输（x402）并且可以自动解决402挑战。
• 要是…就好了 -a 或 --api-key 代理使用标准HTTP传输并转发承载令牌。
• API密钥可用于任何代理端点，而不仅仅是特定域。

MCP客户端集成

连接到Claude Desktop、Cursor和Windsurf等人工智能助手。

Claude桌面配置

使用API密钥（推荐）

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "Cronos Weather API": {
      "command": "npx",
      "args": [
        "cronos402",
        "connect",
        "--urls",
        "https://your-server.com/mcp",
        "--api-key",
        "your_api_key_here"
      ]
    }
  }
}

使用Cronos私钥（替代方案）

使用钱包私钥进行直接链上支付：

{
  "mcpServers": {
    "Cronos Weather API": {
      "command": "npx",
      "args": [
        "cronos402",
        "connect",
        "--urls",
        "https://your-server.com/mcp",
        "--private-key",
        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "--network",
        "cronos-testnet"
      ]
    }
  }
}

光标配置

配置格式与Claude Desktop相同。添加到光标MCP设置中：

{
  "mcpServers": {
    "Cronos AI Service": {
      "command": "npx",
      "args": [
        "cronos402",
        "connect",
        "--urls",
        "https://your-server.com/mcp",
        "--private-key",
        "0xYOUR_PRIVATE_KEY",
        "--network",
        "cronos-testnet"
      ]
    }
  }
}

直接CLI连接

# Using API Key
npx cronos402 connect --urls https://your-server.com/mcp --api-key your_api_key_here

# Using Cronos Private Key
npx cronos402 connect --urls https://your-server.com/mcp --private-key 0xYOUR_PRIVATE_KEY --network cronos-testnet

SDK使用-构建付费MCP服务器

通过支付保护您的MCP服务器

使用 createMcpHandler 在工具运行前要求有效付款。适用于无服务器/边缘兼容的运行时环境。

import { createMcpHandler } from 'cronos402';
import { z } from 'zod';

const handler = createMcpHandler(
  async (server) => {
    server.paidTool(
      'get_weather',
      'Get current weather for any city',
      '0.01', // Price in USD (1 cent per call)
      {
        city: z.string().describe('City name'),
      },
      {},
      async ({ city }) => {
        const weather = await fetchWeather(city);
        return {
          content: [{ type: 'text', text: `Weather in ${city}: ${weather}` }],
        };
      }
    );
  },
  {
    recipient: {
      'cronos-testnet': '0x1234567890abcdef1234567890abcdef12345678',
      'cronos-mainnet': '0x1234567890abcdef1234567890abcdef12345678'
    },
    facilitator: {
      url: "https://facilitator.cronoslabs.org/v2/x402"
    }
  }
);

// Use with Node.js server
import { serve } from '@hono/node-server';
serve({ fetch: handler, port: 3000 });

// Or with Next.js (route handlers)
export { handler as GET, handler as POST };

笔记：

• server.paidTool 接受不同Cronos网络的美元价格和收件人地址。
• 当没有提供有效的付款时，处理程序会返回客户（如 withX402Client)可以自动满足。
• 协调器配置连接到Cronos协调器服务，用于支付验证和结算。

程序化标准代理

import { startStdioServer, ServerType } from 'cronos402';
import { createSigner } from 'x402/types';

// Create signer for Cronos network
const cronosSigner = await createSigner('cronos-testnet', '0x123...');

const serverConnections = [{
  url: 'https://api.example.com/mcp',
  serverType: ServerType.HTTPStream
}];

const x402Config = {
  wallet: { evm: cronosSigner },
  maxPaymentValue: BigInt(1000000) // 1 USDC max payment (6 decimals)
};

await startStdioServer({
  serverConnections,
  x402ClientConfig: x402Config
});

客户：X402支付包装

使用自动402支付处理包裹任何MCP客户端：

import { withX402Client } from 'cronos402/client';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { createSigner } from 'x402/types';

// Create Cronos signer
const cronosSigner = await createSigner('cronos-testnet', '0x123...');

// Initialize MCP client
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: {} }
);

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.example.com/mcp')
);
await client.connect(transport);

// Wrap with payment capabilities
const paymentClient = withX402Client(client, {
  wallet: { evm: cronosSigner },
  maxPaymentValue: BigInt(1000000) // 1 USDC max (6 decimals)
});

// Use tools with automatic payment handling
const tools = await paymentClient.listTools();
const result = await paymentClient.callTool({
  name: 'get_weather',
  arguments: { city: 'Tokyo' }
});
// Payment is handled automatically on 402 response

API直接集成（JavaScript/TypeScript SDK）

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
import { withX402Client } from 'cronos402/client'
import { createSigner } from 'x402/types'

// Initialize signer from private key (Cronos testnet)
const cronosSigner = await createSigner('cronos-testnet', '0x1234567890abcdef...')
const url = new URL('https://your-server.com/mcp')

// Create transport
const transport = new StreamableHTTPClientTransport(url)

// Initialize MCP client
const client = new Client(
  { name: 'my-mcp-client', version: '1.0.0' },
  { capabilities: {} }
)

await client.connect(transport)

// Wrap client with X402 payment capabilities
const paymentClient = withX402Client(client, {
  wallet: { evm: cronosSigner },
  maxPaymentValue: BigInt(1000000), // 1 USDC max payment (6 decimals)
})

// Use tools with automatic payment handling
const tools = await paymentClient.listTools()
console.log('Available tools:', tools)

付款流程

USDC.e（通过协调人无气）

1. 客户端：用户签名EIP-3009 transferWithAuthorization 许可
2. 客户端：提交付款证明 X-PAYMENT 头球
3. 服务器：通过Cronos协调员验证付款
4. 引导者：执行链上转账（支付天然气）
5. 服务器：执行工具并返回结果

本地CRO（直接交易）

1. 客户端：用户将CRO交易发送到服务器地址
2. 客户端：等待2个区块确认
3. 客户端：提交交易哈希作为付款证明
4. 服务器：验证链上的交易
5. 服务器：验证后执行工具

代币支持

USDC.e（桥接USDC星门）

• 主网: 0xf951eC28187D9E5Ca673Da8FE6757E6f0Be5F77C
• 测试网: 0xc01efAaF7C5C61bEbFAeb358E1161b537b8bC0e0
• 小数: 6
• 支付方式：无气（EIP-3009，通过主持人）

CRO（原生代币）

• 地址: 0x0000000000000000000000000000000000000000 （零地址）
• 小数: 18
• 支付方式：直接交易（用户支付天然气）

网络详细信息

Cronos测试网

• 链ID: 338
• 远程过程调用: https://evm-t3.cronos.org
• 探索者: https://testnet.cronoscan.com
• 水龙头: https://cronos.org/faucet （TCRO）
• 水龙头: https://faucet.cronos.org （devUSDC.e）

Cronos主网

• 链ID: 25
• 远程过程调用: https://evm.cronos.org
• 探索者: https://cronoscan.com

API 参考

服务器： createMcpHandler(initialize, x402Config, serverOptions?)

创建具有支付支持的MCP服务器处理程序。

参数：

• initialize：注册工具和资源的功能
• x402Config：付款配置

- recipient：每个网络的付款收件人地址 - facilitator：Cronos主持人配置

• serverOptions：可选MCP服务器选项

退货： (request: Request) => Promise

服务器： server.paidTool(name, description, price, schema, annotations, handler)

注册一个需要付款的工具。

参数：

• name：工具名称
• description：工具说明
• price：美元价格（例如“0.01”）
• schema：工具参数的Zod模式
• annotations：工具注释
• handler：工具执行功能

客户： withX402Client(client, config)

用自动支付处理包裹MCP客户端。

参数：

• client：MCP客户端实例
• config：X402客户端配置

- wallet：带有EVM签名者的钱包配置 - maxPaymentValue：以原子单位表示的最大付款金额 - confirmationCallback：可选付款确认回拨

退货： 具有支付功能的包裹式客户

环境变量

CLI：

• CRONOS_PRIVATE_KEY：用于Cronos x402签名的十六进制私钥
• SERVER_URLS：逗号分隔的MCP端点
• API_KEY：可选，作为身份验证转发到远程
• X402_MAX_ATOMIC：以原子单位表示的最大付款金额
• CRONOS_NETWORK：Cronos网络（Cronos测试网、Cronos主网）

公用事业

价格转换

import { priceToAtomicAmount } from 'cronos402';

// Convert USD price to atomic units
const { maxAmountRequired, asset } = priceToAtomicAmount(
  '0.01', // $0.01
  'cronos-testnet',
  'USDC.e' // or 'CRO'
);

console.log(maxAmountRequired); // 10000n (6 decimals)
console.log(asset.symbol); // 'devUSDC.e'

网络检测

import { isCronosNetwork, getCronosNetworkFromChainId } from 'cronos402';

if (isCronosNetwork('cronos-testnet')) {
  console.log('Valid Cronos network');
}

const network = getCronosNetworkFromChainId(338);
console.log(network); // 'cronos-testnet'

主持人客户

import { createCronosFacilitator } from 'cronos402';

const facilitator = createCronosFacilitator();

// Verify payment
const verification = await facilitator.verify(paymentPayload, requirements);

// Settle payment
const settlement = await facilitator.settle(paymentPayload, requirements);

// Get supported networks
const supported = await facilitator.supported();

支付协议（x402）

在一个 402 Payment Required 响应时，Cronos402将：

1. 解析服务器提供的支付要求
2. 使用您的Cronos钱包创建并签署授权
3. 使用重试原始请求 X-PAYMENT 头球

支持的网络：

• Cronos测试网 （链ID:338）
• Cronos主网 （链ID:25）

每个网络都内置了USDC.e地址，以便通过Cronos服务商进行无气支付。

故障排除

“付款金额超过允许的最大值”

增加 maxPaymentValue 在你的 x402ClientConfig.

错误的链/网络

确保您的钱包/客户端网络符合服务器要求（cronos testnet或cronos mainnet）。

私钥无效

确保Cronos键是前缀为0x的64字符十六进制字符串。

API关键错误

API密钥可用于任何代理终结点。对于直接链上支付，请使用 --private-key 相反。

“付款要求”错误

该工具需要付款。确保您正在传递付款令牌 _meta['x402/payment'] 或者使用自动处理此问题的CLI/客户端包装器。

“Unsupport_NETWORK”错误

仅支持Cronos主网和测试网。检查您的网络配置。

“付款无效”错误

付款验证失败。常见原因：

• 授权已过期（检查 validBefore)
• 无效签名
• 收件人地址不正确
• 代币金额错误

“SETTLMENT_FAILED”错误

链上的付款结算失败。常见原因：

• USDC.e余额不足
• EIP-3009授权无效
• 网络拥塞

发展

pnpm i
pnpm run build
# Dev watch
pnpm run dev

依赖项

• @modelcontextprotocol/sdk -MCP协议实现
• x402 -支付协议实施
• x402-fetch -获取x402的集成
• viem -EVM区块链交互（Cronos）
• commander -CLI框架
• zod -架构验证

安全

• 永远不要提交私钥。更喜欢环境变量和范围化的低值键进行开发。
• 使用 maxPaymentValue 客户端中的保护和服务器中的按工具定价。
• 使用环境变量或安全密钥管理系统安全地存储私钥。

资源

• npm包:
• 文档: docs.cronos402.dev
• GitHub:
• Cronos x402引导者文档
• 模型上下文协议
• EIP-3009：授权转移
• Cronos文档

许可证

麻省理工学院

贡献

欢迎发布问题和PR。

支持

请在存储库中打开一个问题。