Back to Details

ranger-finance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ranger Finance SDK Development Guide

Ranger Finance SDK 开发指南

A comprehensive guide for building Solana applications with Ranger Finance - the first perpetual futures aggregator on Solana.
一份关于使用 Ranger Finance（Solana 上首个永续期货聚合器）构建 Solana 应用程序的综合指南。

Overview

概述

Ranger Finance is a Smart Order Router (SOR) that aggregates perpetual futures trading across multiple Solana protocols:
  • Drift Protocol: Leading perps DEX on Solana
  • Flash Trade: High-performance perpetuals
  • Adrena: Leverage trading protocol
  • Jupiter Perps: Jupiter's perpetuals platform
Ranger Finance 是一款智能订单路由（SOR）工具，聚合了多个 Solana 协议上的永续期货交易：
  • Drift Protocol：Solana 上领先的永续期货 DEX
  • Flash Trade：高性能永续期货平台
  • Adrena：杠杆交易协议
  • Jupiter Perps：Jupiter 的永续期货平台

Key Benefits

核心优势

  • Best Execution: Automatically routes orders to venues with best pricing
  • Unified API: Single interface for all supported perp protocols
  • Position Aggregation: View and manage positions across all venues
  • AI Agent Support: Built-in MCP server for AI trading agents
  • 最优执行：自动将订单路由到定价最优的场所
  • 统一 API：所有支持的永续期货协议共享单一接口
  • 仓位聚合：查看并管理所有场所的仓位
  • AI Agent 支持：内置 MCP 服务器，适配 AI 交易 Agent

Quick Start

快速开始

Installation (TypeScript)

安装（TypeScript）

bash
undefined
bash
undefined

Clone the SDK demo

Clone the SDK demo

git clone https://github.com/ranger-finance/sor-ts-demo.git cd sor-ts-demo npm install
undefined
git clone https://github.com/ranger-finance/sor-ts-demo.git cd sor-ts-demo npm install
undefined

Environment Setup

环境设置

Create a 
.env
file:
bash
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
创建 
.env
文件：
bash
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

Basic Setup

基础设置

typescript
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';
typescript
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';

Core Concepts

核心概念

1. Trade Sides

1. 交易方向

typescript
type TradeSide = 'Long' | 'Short';
typescript
type TradeSide = 'Long' | 'Short';

2. Adjustment Types

2. 调整类型

typescript
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
typescript
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

3. Position Interface

3. 仓位接口

typescript
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'
}
typescript
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'
}

4. Quote Response

4. 报价响应

typescript
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;
}
typescript
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;
}

Trading Operations

交易操作

Get a Quote

获取报价

Before executing a trade, get a quote to see pricing across venues:
typescript
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;
}
执行交易前，先获取报价以查看各场所的定价：
typescript
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;
}

Open/Increase a Position

开仓/加仓

typescript
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);
}
typescript
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);
}

Decrease a Position

减仓

typescript
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);
}
typescript
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 a Position

平仓

typescript
// 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);
}
typescript
// 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);
}

Sign and Execute Transaction

签名并执行交易

typescript
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;
}
typescript
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;
}

Position Management

仓位管理

Fetch All Positions

获取所有仓位

typescript
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;
}
typescript
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;
}

Filter Positions by Platform

按平台筛选仓位

typescript
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;
}
typescript
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;
}

Filter Positions by Symbol

按交易对筛选仓位

typescript
async function getSolPositions() {
  const positions = await sorApi.getPositions(walletAddress, {
    symbols: ['SOL-PERP'],
  });

  return positions;
}
typescript
async function getSolPositions() {
  const positions = await sorApi.getPositions(walletAddress, {
    symbols: ['SOL-PERP'],
  });

  return positions;
}

AI Agent Integration

AI Agent 集成

Ranger provides an MCP (Model Context Protocol) server for AI agent integration.
Ranger 提供了 MCP（Model Context Protocol）服务器用于 AI Agent 集成。

Installation (Python)

安装（Python）

bash
pip install mcp-agent numpy
bash
pip install mcp-agent numpy

MCP Server Tools

MCP 服务器工具

The Ranger MCP server exposes these tools:
SOR Tools:
  • sor_get_trade_quote
    - Get pricing quotes
  • sor_increase_position
    - Open/increase positions
  • sor_decrease_position
    - Reduce positions
  • sor_close_position
    - Close positions
Data API Tools:
  • data_get_positions
    - Fetch current positions
  • data_get_trade_history
    - Trading history
  • data_get_liquidations
    - Liquidation data and signals
  • data_get_funding_rates
    - Funding rate analytics
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
    - 资金费率分析

Example: Mean Reversion Agent

示例：均值回归 Agent

python
import 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())
python
import 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())

Starting the MCP Server

启动 MCP 服务器

bash
cd ranger-agent-kit/perps-mcp
cp .env.example .env
bash
cd ranger-agent-kit/perps-mcp
cp .env.example .env

Edit .env with your API credentials

Edit .env with your API credentials

python -m ranger_mcp
undefined
python -m ranger_mcp
undefined

API Reference

API 参考

SorApi Class

SorApi 类

typescript
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;
}
typescript
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;
}

Configuration

配置

typescript
interface SorSdkConfig {
  apiKey: string;
  sorApiBaseUrl?: string;   // Default: Ranger SOR API
  dataApiBaseUrl?: string;  // Default: Ranger Data API
  solanaRpcUrl?: string;    // Default: Mainnet RPC
}
typescript
interface SorSdkConfig {
  apiKey: string;
  sorApiBaseUrl?: string;   // Default: Ranger SOR API
  dataApiBaseUrl?: string;  // Default: Ranger Data API
  solanaRpcUrl?: string;    // Default: Mainnet RPC
}

Request Types

请求类型

typescript
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';
}
typescript
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';
}

Response Types

响应类型

typescript
interface TransactionResponse {
  message: string;  // Base64-encoded transaction
  meta?: {
    executed_price?: number;
    executed_size?: number;
    executed_collateral?: number;
    venues_used?: string[];
  };
}

interface PositionsResponse {
  positions: Position[];
}
typescript
interface TransactionResponse {
  message: string;  // Base64-encoded transaction
  meta?: {
    executed_price?: number;
    executed_size?: number;
    executed_collateral?: number;
    venues_used?: string[];
  };
}

interface PositionsResponse {
  positions: Position[];
}

Supported Markets

支持的市场

Ranger aggregates perpetual markets across:
ProtocolMarkets
DriftSOL, BTC, ETH, and 20+ assets
FlashSOL, BTC, ETH
AdrenaSOL, BTC, ETH
JupiterSOL, BTC, ETH
Ranger 聚合了以下协议的永续期货市场：
协议交易对
DriftSOL、BTC、ETH 及 20+ 种资产
FlashSOL、BTC、ETH
AdrenaSOL、BTC、ETH
JupiterSOL、BTC、ETH

Error Handling

错误处理

typescript
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;
  }
}
typescript
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;
  }
}

Best Practices

最佳实践

  1. Always Get Quotes First: Before executing trades, use 
    getOrderMetadata
    to compare pricing across venues.
  2. Handle Transaction Signing Securely: Never hardcode private keys. Use environment variables or secure key management.
  3. Monitor Positions: Regularly fetch positions to track PnL and liquidation prices.
  4. Use Appropriate Venue: When decreasing/closing, choose the venue where your position exists.
  5. Set Appropriate Collateral: Consider leverage when setting collateral. Higher collateral = lower liquidation risk.
  1. 始终先获取报价：执行交易前，使用 
    getOrderMetadata
    比较各场所的定价。
  2. 安全处理交易签名：切勿硬编码私钥，使用环境变量或安全的密钥管理方式。
  3. 监控仓位：定期获取仓位信息以跟踪盈亏和清算价格。
  4. 选择合适的场所：减仓/平仓时，选择仓位所在的对应协议场所。
  5. 设置合理的保证金：设置保证金时考虑杠杆比例，保证金越高，清算风险越低。

Resources

资源

Skill Structure

技能结构

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
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 Agent 配置指南