Ranger Finance SDK for building perpetual futures trading applications on Solana. The first Solana Perps Aggregator - aggregates liquidity across multiple perp protocols (Drift, Flash, Adrena, Jupiter). Use when integrating perps trading, smart order routing, position management, or building AI trading agents.
npxskills add sendaifun/skills--skill ranger-financeLoading…
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.
Clone ranger-agent-kit and follow its README for setup.
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
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).