使用说明
MCP Dune Solana API
一个货币化内容提供商（MCP）API服务器，通过Dune Analytics实现对Solana区块链数据的SQL查询，并集成使用Solana USDC的x402支付标准。
特点/功能
- SQL查询执行在Solana区块链数据上执行自定义SQL查询
- x402 支付集成使用Solana USDC实现HTTP 402支付标准
- 安全查询验证和速率限制
- Dune Analytics 集成由Dune的全面区块链数据驱动
- TypeScript全面的类型安全性和现代开发经验
快速入门
先决条件
- Node.js 18及以上版本
- npm 或 yarn
- 沙丘分析API密钥
- 用于接收付款的Solana钱包
安装
- 克隆并安装依赖项：
git clone <repository-url>
cd mcp-dune-solana-api
npm install
- 配置环境变量：
cp env.example .env
编辑 .env 根据您的配置：
DUNE_API_KEY=your_dune_api_key_here
SOLANA_WALLET_ADDRESS=your_solana_wallet_address_here
PAYMENT_AMOUNT_USDC=0.01
PORT=3000
- 构建并运行：
npm run build
npm start
# Or for development:
npm run dev
API终端节点
自由端点
GET /API信息GET /api/health- 健康检查GET /api/info- 详细的API信息和定价GET /api/examples- Solana SQL查询示例POST /api/validate- 验证SQL查询而不执行GET /api/query/saved/:queryId/latest- 从已保存的查询中获取最新结果
付费终端（需使用x402支付）
POST /api/query- 在Solana数据上执行自定义SQL查询POST /api/query/saved/:queryId/execute- 通过ID执行预先保存的Dune查询
使用示例
1. 获取API信息
curl http://localhost:3000/api/info
2. 验证查询（免费）
curl -X POST http://localhost:3000/api/validate \
-H "Content-Type: application/json" \
-d '{
"sql": "SELECT * FROM solana.transactions LIMIT 10"
}'
3. 执行带支付的查询
步骤1：初始请求（收到402状态码，表示需付款）
curl -X POST http://localhost:3000/api/query \
-H "Content-Type: application/json" \
-d '{
"sql": "SELECT block_slot, block_time, tx_id FROM solana.transactions ORDER BY block_time DESC LIMIT 5"
}'
响应（HTTP 402）：
{
"error": "Payment required to access this resource",
"payment": {
"id": "payment-uuid-here",
"amount": "0.01",
"currency": "USDC",
"recipient": "your-solana-wallet-address",
"chain": "solana",
"expires_at": "2024-01-01T12:00:00.000Z",
"instructions": "Send 0.01 USDC to the recipient address..."
}
}
步骤2：在Solana上发送USDC支付
使用您喜欢的Solana钱包或SDK，向指定的收款地址发送确切数量的USDC。
步骤3：重新提交请求并附上付款证明
curl -X POST http://localhost:3000/api/query \
-H "Content-Type: application/json" \
-H "X-Payment-Id: payment-uuid-here" \
-H "X-Payment-Proof: transaction-hash-here" \
-d '{
"sql": "SELECT block_slot, block_time, tx_id FROM solana.transactions ORDER BY block_time DESC LIMIT 5"
}'
Solana 查询示例
最近交易
SELECT
block_slot,
block_time,
tx_id,
fee,
account_keys[1] as signer
FROM solana.transactions
ORDER BY block_time DESC
LIMIT 10
USDC转账统计
SELECT
COUNT(*) as transfer_count,
SUM(amount) / 1e6 as total_volume_usdc,
AVG(amount) / 1e6 as avg_transfer_usdc
FROM solana.token_transfers_2022
WHERE mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
AND block_time > NOW() - INTERVAL '1' HOUR
顶级SOL转账
SELECT
tx_id,
block_time,
pre_balance / 1e9 as pre_balance_sol,
post_balance / 1e9 as post_balance_sol,
(post_balance - pre_balance) / 1e9 as transfer_amount_sol
FROM solana.account_activity
WHERE block_time > NOW() - INTERVAL '24' HOUR
AND pre_balance != post_balance
ORDER BY ABS(post_balance - pre_balance) DESC
LIMIT 20
x402 支付流程
该API实现了x402微支付标准：
- 初始请求客户端向付费端点发出请求
- 402 响应服务器返回HTTP 402状态码及支付详情
- 付款客户端将USDC发送到Solana网络上的指定地址
- 重试客户端在请求中附上支付证明头信息后重试
- 验证服务器验证链上的支付
- 成功查询已执行，结果已返回
配置
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
DUNE_API_KEY 沙丘分析API密钥 |
必填 | |
SOLANA_WALLET_ADDRESS |
您的Solana钱包地址（用于接收付款） | 必填 |
SOLANA_RPC_URL |
Solana RPC 端点 | https://api.mainnet-beta.solana.com |
USDC_MINT_ADDRESS |
USDC代币铸造地址 | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
PAYMENT_AMOUNT_USDC |
每次查询的支付金额 | 0.01 |
PAYMENT_TIMEOUT_SECONDS |
支付超时时间（秒） | 300 |
PORT |
服务器端口 | 3000 |
安全特性
- 输入验证和SQL注入防护
- 查询验证（仅限Solana，仅限SELECT）
- 在Solana区块链上进行支付验证
- 速率限制和超时处理
- 使用 Helmet.js 设置安全头部
发展
脚本
npm run dev- 启动开发服务器并启用热重载npm run build- 将TypeScript编译为JavaScriptnpm start- 启动生产服务器npm test- 运行测试
项目结构
src/
├── config/ # Configuration management
├── middleware/ # x402 payment middleware
├── routes/ # API route handlers
├── services/ # Business logic (Dune, Payment)
├── types/ # TypeScript type definitions
└── server.ts # Main server file
支持
对于问题和疑问：
- 检查一下
/api/info当前配置的终端节点 - 使用（工具/方法）验证查询
/api/query/validate - 使用
/api/query/examples用于工作查询示例
许可证
麻省理工学院许可证
