重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
ranger-finance by sendaifun/skills
npx skills add https://github.com/sendaifun/skills --skill ranger-finance使用 Ranger Finance 构建 Solana 应用程序的综合指南——Solana 上首个永续期货聚合器。
Ranger Finance 是一个智能订单路由器(SOR),聚合了多个 Solana 协议的永续期货交易:
# 克隆 SDK 演示项目
git clone https://github.com/ranger-finance/sor-ts-demo.git
cd sor-ts-demo
npm install
创建一个 .env 文件:
RANGER_API_KEY=your_api_key_here
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
WALLET_PRIVATE_KEY=your_base58_private_key # 可选,用于签名
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
import { SorApi, TradeSide } from 'ranger-sor-sdk';
import dotenv from 'dotenv';
dotenv.config();
// 初始化 SOR API 客户端
const sorApi = new SorApi({
apiKey: process.env.RANGER_API_KEY!,
solanaRpcUrl: process.env.SOLANA_RPC_URL,
});
// 您的钱包公钥
const walletAddress = 'YOUR_WALLET_PUBLIC_KEY';
type TradeSide = 'Long' | 'Short';
type AdjustmentType =
| 'Quote' // 仅获取报价
| 'Increase' // 开仓或增加头寸
| 'DecreaseFlash' // 通过 Flash 减少头寸
| 'DecreaseJupiter' // 通过 Jupiter 减少头寸
| 'DecreaseDrift' // 通过 Drift 减少头寸
| 'DecreaseAdrena' // 通过 Adrena 减少头寸
| 'CloseFlash' // 通过 Flash 平仓
| 'CloseJupiter' // 通过 Jupiter 平仓
| 'CloseDrift' // 通过 Drift 平仓
| 'CloseAdrena' // 通过 Adrena 平仓
| 'CloseAll'; // 平掉全部头寸
interface Position {
id: string;
symbol: string;
side: TradeSide;
quantity: number;
entry_price: number;
liquidation_price: number;
position_leverage: number;
real_collateral: number;
unrealized_pnl: number;
borrow_fee: number;
funding_fee: number;
open_fee: number;
close_fee: number;
created_at: string;
opened_at: string;
platform: string; // 'DRIFT', 'FLASH', 'ADRENA', 'JUPITER'
}
interface Quote {
base: number;
fee: number;
total: number;
fee_breakdown: {
base_fee: number;
spread_fee: number;
volatility_fee: number;
margin_fee: number;
close_fee: number;
other_fees: number;
};
}
interface VenueAllocation {
venue_name: string;
collateral: number;
size: number;
quote: Quote;
order_available_liquidity: number;
venue_available_liquidity: number;
}
interface OrderMetadataResponse {
venues: VenueAllocation[];
total_collateral: number;
total_size: number;
}
在执行交易前,获取报价以查看各交易场所的定价:
import { SorApi, OrderMetadataRequest, TradeSide } from 'ranger-sor-sdk';
const sorApi = new SorApi({ apiKey: process.env.RANGER_API_KEY! });
async function getQuote() {
const request: OrderMetadataRequest = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 1.0, // 1 SOL 头寸规模
collateral: 10.0, // 10 USDC 保证金(10倍杠杆)
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Quote',
};
const quote = await sorApi.getOrderMetadata(request);
console.log('可用交易场所:');
quote.venues.forEach(venue => {
console.log(` ${venue.venue_name}: ${venue.quote.total} USDC`);
});
return quote;
}
async function openLongPosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 1.0,
collateral: 10.0,
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Increase' as const,
};
// 获取交易指令
const response = await sorApi.increasePosition(request);
console.log('交易消息(base64):', response.message);
if (response.meta) {
console.log('执行价格:', response.meta.executed_price);
console.log('使用的交易场所:', response.meta.venues_used);
}
return response;
}
// 开空仓
async function openShortPosition() {
const request = {
fee_payer: walletAddress,
symbol: 'ETH',
side: 'Short' as TradeSide,
size: 0.5,
collateral: 100.0,
size_denomination: 'ETH',
collateral_denomination: 'USDC',
adjustment_type: 'Increase' as const,
};
return await sorApi.increasePosition(request);
}
async function decreasePosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 0.5, // 减少 0.5 SOL
collateral: 5.0, // 提取 5 USDC 保证金
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'DecreaseFlash' as const, // 通过 Flash 路由
};
return await sorApi.decreasePosition(request);
}
// 在特定交易场所平掉全部头寸
async function closePosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
adjustment_type: 'CloseFlash' as const,
};
return await sorApi.closePosition(request);
}
// 平掉所有交易场所的全部头寸
async function closeAllPositions() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
adjustment_type: 'CloseAll' as const,
};
return await sorApi.closePosition(request);
}
import { Keypair, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
async function executeTradeWithSigning() {
// 获取交易指令
const txResponse = await sorApi.increasePosition({
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long',
size: 1.0,
collateral: 10.0,
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Increase',
});
// 从私钥创建密钥对
const privateKeyBytes = bs58.decode(process.env.WALLET_PRIVATE_KEY!);
const keypair = Keypair.fromSecretKey(privateKeyBytes);
// 定义签名函数
const signTransaction = async (tx: VersionedTransaction) => {
tx.sign([keypair]);
return tx;
};
// 执行交易
const result = await sorApi.executeTransaction(txResponse, signTransaction);
console.log('交易签名:', result.signature);
return result;
}
async function getAllPositions() {
const positions = await sorApi.getPositions(walletAddress);
positions.positions.forEach(pos => {
console.log(`${pos.symbol} ${pos.side}: ${pos.quantity} @ ${pos.entry_price}`);
console.log(` 平台:${pos.platform}`);
console.log(` 盈亏:${pos.unrealized_pnl}`);
console.log(` 清算价:${pos.liquidation_price}`);
});
return positions;
}
async function getDriftPositions() {
const positions = await sorApi.getPositions(walletAddress, {
platforms: ['DRIFT'],
});
return positions;
}
async function getFlashAndAdrenaPositions() {
const positions = await sorApi.getPositions(walletAddress, {
platforms: ['FLASH', 'ADRENA'],
});
return positions;
}
async function getSolPositions() {
const positions = await sorApi.getPositions(walletAddress, {
symbols: ['SOL-PERP'],
});
return positions;
}
Ranger 提供了一个用于 AI 代理集成的 MCP(模型上下文协议)服务器。
pip install mcp-agent numpy
Ranger MCP 服务器暴露了以下工具:
SOR 工具:
sor_get_trade_quote - 获取定价报价sor_increase_position - 开仓/增加头寸sor_decrease_position - 减少头寸sor_close_position - 平仓数据 API 工具:
data_get_positions - 获取当前头寸data_get_trade_history - 交易历史data_get_liquidations - 清算数据和信号data_get_funding_rates - 资金费率分析import asyncio
from ranger_mcp_agent.examples.mean_reversion_agent import run_mean_reversion_agent
async def main():
# 运行均值回归交易策略
await run_mean_reversion_agent()
if __name__ == "__main__":
asyncio.run(main())
cd ranger-agent-kit/perps-mcp
cp .env.example .env
# 使用您的 API 凭据编辑 .env 文件
python -m ranger_mcp
class SorApi {
constructor(config: SorSdkConfig);
// 获取交易报价
getOrderMetadata(request: OrderMetadataRequest): Promise<OrderMetadataResponse>;
// 开仓或增加头寸
increasePosition(request: IncreasePositionRequest): Promise<TransactionResponse>;
// 减少头寸
decreasePosition(request: DecreasePositionRequest): Promise<TransactionResponse>;
// 平仓
closePosition(request: ClosePositionRequest): Promise<TransactionResponse>;
// 获取钱包的头寸
getPositions(
publicKey: string,
options?: {
platforms?: string[];
symbols?: string[];
startDate?: string;
endDate?: string;
}
): Promise<PositionsResponse>;
// 执行已签名的交易
executeTransaction(
transactionResponse: TransactionResponse,
signTransaction: (tx: VersionedTransaction) => Promise<VersionedTransaction>
): Promise<{ signature: string }>;
// 获取 Solana 连接
getConnection(): Connection;
}
interface SorSdkConfig {
apiKey: string;
sorApiBaseUrl?: string; // 默认:Ranger SOR API
dataApiBaseUrl?: string; // 默认:Ranger Data API
solanaRpcUrl?: string; // 默认:主网 RPC
}
interface BaseRequest {
fee_payer: string;
symbol: string;
side: TradeSide;
size_denomination?: string;
collateral_denomination?: string;
}
interface IncreasePositionRequest extends BaseRequest {
size: number;
collateral: number;
size_denomination: string;
collateral_denomination: string;
adjustment_type: 'Increase';
}
interface DecreasePositionRequest extends BaseRequest {
size: number;
collateral: number;
size_denomination: string;
collateral_denomination: string;
adjustment_type: 'DecreaseFlash' | 'DecreaseJupiter' | 'DecreaseDrift' | 'DecreaseAdrena';
}
interface ClosePositionRequest extends BaseRequest {
adjustment_type: 'CloseFlash' | 'CloseJupiter' | 'CloseDrift' | 'CloseAdrena' | 'CloseAll';
}
interface TransactionResponse {
message: string; // Base64 编码的交易
meta?: {
executed_price?: number;
executed_size?: number;
executed_collateral?: number;
venues_used?: string[];
};
}
interface PositionsResponse {
positions: Position[];
}
Ranger 聚合了以下协议的永续市场:
| 协议 | 市场 |
|---|---|
| Drift | SOL, BTC, ETH, 以及 20+ 种资产 |
| Flash | SOL, BTC, ETH |
| Adrena | SOL, BTC, ETH |
| Jupiter | SOL, BTC, ETH |
try {
const response = await sorApi.increasePosition(request);
} catch (error) {
if (error.error_code) {
// API 错误
console.error('API 错误:', error.message);
console.error('错误代码:', error.error_code);
} else {
// 网络或其他错误
throw error;
}
}
getOrderMetadata 比较各交易场所的定价。ranger-finance/
├── SKILL.md # 本文件
├── resources/
│ ├── api-reference.md # API 端点参考
│ └── types-reference.md # 完整的 TypeScript 类型定义
├── examples/
│ ├── basic/
│ │ └── example.ts # 基础交易操作
│ ├── positions/
│ │ └── example.ts # 头寸查询和管理
│ └── transactions/
│ └── example.ts # 交易签名流程
├── templates/
│ └── setup.ts # 即用型设置模板
└── docs/
├── troubleshooting.md # 常见问题及解决方案
└── ai-agent-integration.md # AI 代理设置指南
每周安装量
47
代码仓库
GitHub 星标数
68
首次出现
2026年1月24日
安全审计
安装于
gemini-cli43
opencode43
codex43
github-copilot41
cursor40
kimi-cli39
A comprehensive guide for building Solana applications with Ranger Finance - the first perpetual futures aggregator on Solana.
Ranger Finance is a Smart Order Router (SOR) that aggregates perpetual futures trading across multiple Solana protocols:
# Clone the SDK demo
git clone https://github.com/ranger-finance/sor-ts-demo.git
cd sor-ts-demo
npm install
Create a .env file:
RANGER_API_KEY=your_api_key_here
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
WALLET_PRIVATE_KEY=your_base58_private_key # Optional, for signing
import { SorApi, TradeSide } from 'ranger-sor-sdk';
import dotenv from 'dotenv';
dotenv.config();
// Initialize the SOR API client
const sorApi = new SorApi({
apiKey: process.env.RANGER_API_KEY!,
solanaRpcUrl: process.env.SOLANA_RPC_URL,
});
// Your wallet public key
const walletAddress = 'YOUR_WALLET_PUBLIC_KEY';
type TradeSide = 'Long' | 'Short';
type AdjustmentType =
| 'Quote' // Get a quote only
| 'Increase' // Open or increase position
| 'DecreaseFlash' // Decrease via Flash
| 'DecreaseJupiter' // Decrease via Jupiter
| 'DecreaseDrift' // Decrease via Drift
| 'DecreaseAdrena' // Decrease via Adrena
| 'CloseFlash' // Close via Flash
| 'CloseJupiter' // Close via Jupiter
| 'CloseDrift' // Close via Drift
| 'CloseAdrena' // Close via Adrena
| 'CloseAll'; // Close entire position
interface Position {
id: string;
symbol: string;
side: TradeSide;
quantity: number;
entry_price: number;
liquidation_price: number;
position_leverage: number;
real_collateral: number;
unrealized_pnl: number;
borrow_fee: number;
funding_fee: number;
open_fee: number;
close_fee: number;
created_at: string;
opened_at: string;
platform: string; // 'DRIFT', 'FLASH', 'ADRENA', 'JUPITER'
}
interface Quote {
base: number;
fee: number;
total: number;
fee_breakdown: {
base_fee: number;
spread_fee: number;
volatility_fee: number;
margin_fee: number;
close_fee: number;
other_fees: number;
};
}
interface VenueAllocation {
venue_name: string;
collateral: number;
size: number;
quote: Quote;
order_available_liquidity: number;
venue_available_liquidity: number;
}
interface OrderMetadataResponse {
venues: VenueAllocation[];
total_collateral: number;
total_size: number;
}
Before executing a trade, get a quote to see pricing across venues:
import { SorApi, OrderMetadataRequest, TradeSide } from 'ranger-sor-sdk';
const sorApi = new SorApi({ apiKey: process.env.RANGER_API_KEY! });
async function getQuote() {
const request: OrderMetadataRequest = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 1.0, // 1 SOL position size
collateral: 10.0, // 10 USDC collateral (10x leverage)
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Quote',
};
const quote = await sorApi.getOrderMetadata(request);
console.log('Available venues:');
quote.venues.forEach(venue => {
console.log(` ${venue.venue_name}: ${venue.quote.total} USDC`);
});
return quote;
}
async function openLongPosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 1.0,
collateral: 10.0,
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Increase' as const,
};
// Get transaction instructions
const response = await sorApi.increasePosition(request);
console.log('Transaction message (base64):', response.message);
if (response.meta) {
console.log('Executed price:', response.meta.executed_price);
console.log('Venues used:', response.meta.venues_used);
}
return response;
}
// Open a short position
async function openShortPosition() {
const request = {
fee_payer: walletAddress,
symbol: 'ETH',
side: 'Short' as TradeSide,
size: 0.5,
collateral: 100.0,
size_denomination: 'ETH',
collateral_denomination: 'USDC',
adjustment_type: 'Increase' as const,
};
return await sorApi.increasePosition(request);
}
async function decreasePosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
size: 0.5, // Decrease by 0.5 SOL
collateral: 5.0, // Withdraw 5 USDC collateral
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'DecreaseFlash' as const, // Route through Flash
};
return await sorApi.decreasePosition(request);
}
// Close entire position on a specific venue
async function closePosition() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
adjustment_type: 'CloseFlash' as const,
};
return await sorApi.closePosition(request);
}
// Close all positions across all venues
async function closeAllPositions() {
const request = {
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long' as TradeSide,
adjustment_type: 'CloseAll' as const,
};
return await sorApi.closePosition(request);
}
import { Keypair, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
async function executeTradeWithSigning() {
// Get transaction instructions
const txResponse = await sorApi.increasePosition({
fee_payer: walletAddress,
symbol: 'SOL',
side: 'Long',
size: 1.0,
collateral: 10.0,
size_denomination: 'SOL',
collateral_denomination: 'USDC',
adjustment_type: 'Increase',
});
// Create keypair from private key
const privateKeyBytes = bs58.decode(process.env.WALLET_PRIVATE_KEY!);
const keypair = Keypair.fromSecretKey(privateKeyBytes);
// Define signing function
const signTransaction = async (tx: VersionedTransaction) => {
tx.sign([keypair]);
return tx;
};
// Execute the transaction
const result = await sorApi.executeTransaction(txResponse, signTransaction);
console.log('Transaction signature:', result.signature);
return result;
}
async function getAllPositions() {
const positions = await sorApi.getPositions(walletAddress);
positions.positions.forEach(pos => {
console.log(`${pos.symbol} ${pos.side}: ${pos.quantity} @ ${pos.entry_price}`);
console.log(` Platform: ${pos.platform}`);
console.log(` PnL: ${pos.unrealized_pnl}`);
console.log(` Liquidation: ${pos.liquidation_price}`);
});
return positions;
}
async function getDriftPositions() {
const positions = await sorApi.getPositions(walletAddress, {
platforms: ['DRIFT'],
});
return positions;
}
async function getFlashAndAdrenaPositions() {
const positions = await sorApi.getPositions(walletAddress, {
platforms: ['FLASH', 'ADRENA'],
});
return positions;
}
async function getSolPositions() {
const positions = await sorApi.getPositions(walletAddress, {
symbols: ['SOL-PERP'],
});
return positions;
}
Ranger provides an MCP (Model Context Protocol) server for AI agent integration.
pip install mcp-agent numpy
The Ranger MCP server exposes these tools:
SOR Tools:
sor_get_trade_quote - Get pricing quotessor_increase_position - Open/increase positionssor_decrease_position - Reduce positionssor_close_position - Close positionsData API Tools:
data_get_positions - Fetch current positionsdata_get_trade_history - Trading historydata_get_liquidations - Liquidation data and signalsdata_get_funding_rates - Funding rate analyticsimport asyncio
from ranger_mcp_agent.examples.mean_reversion_agent import run_mean_reversion_agent
async def main():
# Run a mean reversion trading strategy
await run_mean_reversion_agent()
if __name__ == "__main__":
asyncio.run(main())
cd ranger-agent-kit/perps-mcp
cp .env.example .env
# Edit .env with your API credentials
python -m ranger_mcp
class SorApi {
constructor(config: SorSdkConfig);
// Get quote for a trade
getOrderMetadata(request: OrderMetadataRequest): Promise<OrderMetadataResponse>;
// Open or increase a position
increasePosition(request: IncreasePositionRequest): Promise<TransactionResponse>;
// Reduce a position
decreasePosition(request: DecreasePositionRequest): Promise<TransactionResponse>;
// Close a position
closePosition(request: ClosePositionRequest): Promise<TransactionResponse>;
// Get positions for a wallet
getPositions(
publicKey: string,
options?: {
platforms?: string[];
symbols?: string[];
startDate?: string;
endDate?: string;
}
): Promise<PositionsResponse>;
// Execute a signed transaction
executeTransaction(
transactionResponse: TransactionResponse,
signTransaction: (tx: VersionedTransaction) => Promise<VersionedTransaction>
): Promise<{ signature: string }>;
// Get Solana connection
getConnection(): Connection;
}
interface SorSdkConfig {
apiKey: string;
sorApiBaseUrl?: string; // Default: Ranger SOR API
dataApiBaseUrl?: string; // Default: Ranger Data API
solanaRpcUrl?: string; // Default: Mainnet RPC
}
interface BaseRequest {
fee_payer: string;
symbol: string;
side: TradeSide;
size_denomination?: string;
collateral_denomination?: string;
}
interface IncreasePositionRequest extends BaseRequest {
size: number;
collateral: number;
size_denomination: string;
collateral_denomination: string;
adjustment_type: 'Increase';
}
interface DecreasePositionRequest extends BaseRequest {
size: number;
collateral: number;
size_denomination: string;
collateral_denomination: string;
adjustment_type: 'DecreaseFlash' | 'DecreaseJupiter' | 'DecreaseDrift' | 'DecreaseAdrena';
}
interface ClosePositionRequest extends BaseRequest {
adjustment_type: 'CloseFlash' | 'CloseJupiter' | 'CloseDrift' | 'CloseAdrena' | 'CloseAll';
}
interface TransactionResponse {
message: string; // Base64-encoded transaction
meta?: {
executed_price?: number;
executed_size?: number;
executed_collateral?: number;
venues_used?: string[];
};
}
interface PositionsResponse {
positions: Position[];
}
Ranger aggregates perpetual markets across:
| Protocol | Markets |
|---|---|
| Drift | SOL, BTC, ETH, and 20+ assets |
| Flash | SOL, BTC, ETH |
| Adrena | SOL, BTC, ETH |
| Jupiter | SOL, BTC, ETH |
try {
const response = await sorApi.increasePosition(request);
} catch (error) {
if (error.error_code) {
// API error
console.error('API Error:', error.message);
console.error('Error code:', error.error_code);
} else {
// Network or other error
throw error;
}
}
Always Get Quotes First : Before executing trades, use getOrderMetadata to compare pricing across venues.
Handle Transaction Signing Securely : Never hardcode private keys. Use environment variables or secure key management.
Monitor Positions : Regularly fetch positions to track PnL and liquidation prices.
Use Appropriate Venue : When decreasing/closing, choose the venue where your position exists.
Set Appropriate Collateral : Consider leverage when setting collateral. Higher collateral = lower liquidation risk.
ranger-finance/
├── SKILL.md # This file
├── resources/
│ ├── api-reference.md # API endpoint reference
│ └── types-reference.md # Complete TypeScript types
├── examples/
│ ├── basic/
│ │ └── example.ts # Basic trade operations
│ ├── positions/
│ │ └── example.ts # Position queries and management
│ └── transactions/
│ └── example.ts # Transaction signing flow
├── templates/
│ └── setup.ts # Ready-to-use setup template
└── docs/
├── troubleshooting.md # Common issues and solutions
└── ai-agent-integration.md # AI agent setup guide
Weekly Installs
47
Repository
GitHub Stars
68
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
gemini-cli43
opencode43
codex43
github-copilot41
cursor40
kimi-cli39
飞书视频会议CLI工具:lark-vc技能详解,高效搜索与管理会议记录与纪要
47,500 周安装
安全模式技能:20条安全规则,涵盖身份验证、LLM安全、OWASP防护,加固应用程序开发
185 周安装
AI测试自动化专家:TDD、Playwright、Selenium、性能测试与CI/CD集成
185 周安装
北极星愿景技能:定义产品愿景、凝聚团队、指导战略决策的完整方法论
194 周安装
Substance 3D Painter PBR纹理制作与网页导出教程:Python自动化与Three.js集成
188 周安装
iOS图形与Metal开发指南:GPU渲染、Metal迁移、RealityKit 3D内容与显示性能优化
188 周安装
API响应优化指南:提升性能、减少负载、加速应用
186 周安装