Crate koios_sdk

Source
Expand description

Koios SDK - A Rust SDK for the Koios Cardano API

This crate provides a strongly-typed client for interacting with the Koios API, which provides access to Cardano blockchain data. Koios is a decentralized and elastic RESTful query layer for exploring data on the Cardano blockchain.

§Features

  • Strongly typed API client
  • Support for multiple networks (Mainnet, Preprod, Preview, Guild)
  • Authentication support (JWT Bearer tokens)
  • Rate limiting
  • Async/await support
  • Comprehensive error handling
  • Full coverage of Koios API endpoints

§Example

use koios_sdk::{Client, Network, error::Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client with default configuration (Mainnet)
    let client = Client::new()?;

    // Or specify a different network
    let client = Client::builder()
        .network(Network::Preprod)
        .build()?;

    // Get the current tip of the blockchain
    let tip = client.get_tip().await?;
    println!("Current tip: {:?}", tip);

    Ok(())
}

§Network Selection

The SDK supports multiple Cardano networks:

use koios_sdk::{Client, Network};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Preprod network
    let preprod_client = Client::builder()
        .network(Network::Preprod)
        .build()?;

    // Connect to Preview network
    let preview_client = Client::builder()
        .network(Network::Preview)
        .build()?;

    // Connect to Guild network
    let guild_client = Client::builder()
        .network(Network::Guild)
        .build()?;

    Ok(())
}

§Authentication

You can authenticate using a JWT Bearer token:

use koios_sdk::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new()
        .auth_token("your-jwt-token")
        .build()?;

    Ok(())
}

§Rate Limiting

The SDK includes built-in rate limiting:

use koios_sdk::ClientBuilder;
use governor::Quota;
use std::num::NonZeroU32;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new()
        .rate_limit(Quota::per_second(NonZeroU32::new(100).unwrap()))
        .build()?;

    Ok(())
}

§Modules

  • client - Client implementation and builder
  • api - API endpoint implementations
  • models - Data models and types
  • error - Error types and handling
  • network - Network configuration and options

Re-exports§

pub use client::Client;
pub use client::ClientBuilder;
pub use error::Error;
pub use error::Result;
pub use network::Network;

Modules§

api
API endpoint implementations
client
Client implementation for the Koios API
error
models
network
prelude
Re-export of commonly used types
types

Constants§

API_VERSION
DEFAULT_API_URL
VERSION