kobe-client 0.1.2

Rust client library for Kobe APIs
Documentation

Kobe Client

A comprehensive, async Rust client library for interacting with Jito Network APIs.

Crates.io Documentation License

Features

  • MEV & Staker Rewards API: Query MEV and priority fee rewards for stakers and validators
  • Stake Pool API: Access validator statistics, JitoSOL metrics, and network data
  • StakeNet API: On-chain validator history and performance data
  • Async/Await: Built on tokio and reqwest for high-performance async operations
  • Type-Safe: Strongly typed request and response structures
  • Error Handling: Comprehensive error types with detailed messages
  • Retry Logic: Automatic retry with exponential backoff
  • Configurable: Flexible configuration options for timeouts, retries, and more

Installation

Add this to your Cargo.toml:

[dependencies]
kobe-client = "0.1"
tokio = { version = "1", features = ["full"] }

Quick Start

use kobe_client::client::KobeClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a client with mainnet defaults
    let client = KobeClient::mainnet();

    // Get staker rewards
    let rewards = client.get_staker_rewards(Some(10)).await?;
    println!("Found {} staker rewards", rewards.rewards.len());

    // Get validator information
    let validators = client.get_validators(None).await?;
    println!("Found {} validators", validators.validators.len());

    // Get MEV rewards for the network
    let mev_rewards = client.get_mev_rewards(None).await?;
    println!("Epoch: {}, Total MEV: {} lamports",
             mev_rewards.epoch,
             mev_rewards.total_network_mev_lamports);

    Ok(())
}

Usage Examples

MEV & Staker Rewards API

Get Staker Rewards

use jito_api_client::JitoClient;

let client = JitoClient::mainnet();

// Get top 5 staker rewards
let rewards = client.get_staker_rewards(Some(5)).await?;

for reward in rewards.rewards {
    println!("Stake Account: {}", reward.stake_account);
    println!("MEV Rewards: {} lamports", reward.mev_rewards);
    println!("Claimed: {}", reward.mev_claimed);
}

Get Validator Rewards

// Get validator rewards for a specific epoch
let validator_rewards = client.get_validator_rewards(Some(678), Some(10)).await?;

for validator in validator_rewards.validators {
    println!("Vote Account: {}", validator.vote_account);
    println!("MEV Rewards: {} lamports", validator.mev_rewards);
    println!("MEV Commission: {} bps", validator.mev_commission_bps);
}

Stake Pool API

Get Validator Information

// Get all validators for the current epoch
let validators = client.get_validators(None).await?;

// Get validators for a specific epoch
let validators_600 = client.get_validators(Some(600)).await?;

// Filter validators running Jito
let jito_validators: Vec<_> = validators.validators
    .into_iter()
    .filter(|v| v.running_jito)
    .collect();

println!("Found {} Jito validators", jito_validators.len());

Get Validator History

// Get historical data for a specific validator
let vote_account = "GdRKUZKdiXMEATjddQW6q4W8bPgXRBYJKayfeqdQcEPa";
let history = client.get_validator_history(vote_account).await?;

for entry in history.iter().take(5) {
    println!("Epoch {}: {} lamports", entry.epoch, entry.mev_rewards);
}

Get MEV Network Statistics

// Get current epoch MEV stats
let mev_stats = client.get_mev_rewards(None).await?;
println!("Total Network MEV: {} lamports", mev_stats.total_network_mev_lamports);
println!("MEV per lamport: {}", mev_stats.mev_reward_per_lamport);

// Get MEV stats for a specific epoch
let mev_stats_600 = client.get_mev_rewards(Some(600)).await?;

Get JitoSOL Metrics

use chrono::{Duration, Utc};

// Get JitoSOL to SOL ratio for the last 7 days
let end = Utc::now();
let start = end - Duration::days(7);
let ratio = client.get_jitosol_sol_ratio(start, end).await?;

for point in ratio.ratios {
    println!("{}: {}", point.date, point.data);
}

Get MEV Commission Averages

// Get historical MEV commission averages with APY and TVL data
let commission_data = client.get_mev_commission_average_over_time().await?;

println!("Aggregated MEV Rewards: {}", commission_data.aggregated_mev_rewards);

// Print APY data
for apy_point in commission_data.apy {
    println!("{}: {:.2}%", apy_point.date, apy_point.data * 100.0);
}

Convenience Methods

// Get current epoch
let current_epoch = client.get_current_epoch().await?;
println!("Current epoch: {}", current_epoch);

// Get only Jito-running validators
let jito_validators = client.get_jito_validators().await?;

// Get top 10 validators by MEV rewards
let top_validators = client.get_validators_by_mev_rewards(None, 10).await?;

// Check if a validator is running Jito
let is_jito = client.is_validator_running_jito(
    "GdRKUZKdiXMEATjddQW6q4W8bPgXRBYJKayfeqdQcEPa"
).await?;

// Get validator MEV commission
let commission = client.get_validator_mev_commission(
    "GdRKUZKdiXMEATjddQW6q4W8bPgXRBYJKayfeqdQcEPa"
).await?;

// Calculate total MEV rewards across multiple epochs
let total_mev = client.calculate_total_mev_rewards(600, 610).await?;
println!("Total MEV from epoch 600-610: {} lamports", total_mev);

Configuration

Using the Builder Pattern

use jito_api_client::JitoClientBuilder;
use std::time::Duration;

let client = JitoClientBuilder::new()
    .timeout(Duration::from_secs(60))
    .user_agent("my-app/1.0")
    .retry(true)
    .max_retries(5)
    .build();

Using Config

use jito_api_client::{JitoClient, Config};
use std::time::Duration;

let config = Config::mainnet()
    .with_timeout(Duration::from_secs(60))
    .with_user_agent("my-app/1.0")
    .with_retry(true)
    .with_max_retries(5);

let client = JitoClient::new(config);

Custom Base URL

let config = Config::custom("https://custom-api.example.com");
let client = JitoClient::new(config);

Error Handling

The library provides detailed error types:

use jito_api_client::{JitoClient, JitoError};

let client = JitoClient::mainnet();

match client.get_staker_rewards(Some(10)).await {
    Ok(rewards) => println!("Success: {} rewards", rewards.rewards.len()),
    Err(JitoError::RateLimitExceeded) => {
        eprintln!("Rate limit exceeded, please wait");
    }
    Err(JitoError::NotFound(msg)) => {
        eprintln!("Resource not found: {}", msg);
    }
    Err(JitoError::ApiError { status_code, message }) => {
        eprintln!("API error {}: {}", status_code, message);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

Advanced Usage

Query Parameters

use jito_api_client::QueryParams;

let params = QueryParams::default()
    .limit(50)
    .offset(100)
    .epoch(600);

let rewards = client.get_staker_rewards_with_params(&params).await?;

Retry Logic

The client automatically retries failed requests with exponential backoff. You can configure this behavior:

let client = JitoClientBuilder::new()
    .retry(true)           // Enable retries
    .max_retries(3)        // Maximum 3 retry attempts
    .build();

Retries are attempted for:

  • Network timeouts
  • Connection errors
  • Temporary network issues

Retries are NOT attempted for:

  • Invalid parameters (400)
  • Not found errors (404)
  • Rate limiting (429)
  • Server errors (5xx)

API Documentation

For detailed API documentation, visit:

Examples

Check the examples/ directory for complete working examples:

# Run the basic example
cargo run --example basic

# Run the validator analysis example
cargo run --example validator_analysis

# Run the MEV tracking example
cargo run --example mev_tracking

Testing

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_config_builder

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under either of:

at your option.

Disclaimer

This is an unofficial client library and is not affiliated with or endorsed by Jito Labs or the Jito Foundation.

Links