# koios-sdk
A comprehensive Rust SDK for interacting with the Koios Cardano API. This SDK provides a strongly-typed, async interface for accessing Cardano blockchain data through Koios endpoints.
[](https://crates.io/crates/koios-sdk)
[](https://docs.rs/koios-sdk)
[](LICENSE)
[](https://github.com/justmert/koios.rs/actions/workflows/ci.yml)
[](https://github.com/justmert/koios.rs/actions/workflows/ci.yml)
[](https://github.com/justmert/koios.rs/actions/workflows/ci.yml)
## Features
- 🔄 Full coverage of Koios API endpoints
- 🌐 Support for multiple networks (Mainnet, Preprod, Preview, Guild)
- 🔒 Authentication support (JWT Bearer tokens)
- ⚡ Built-in rate limiting
- 🔄 Async/await support
- 💪 Strong typing with comprehensive error handling
- 📦 Zero-copy deserialization
- 🛠️ Builder pattern for client configuration
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
koios-sdk = "0.1.0"
```
## Quick Start
```rust
use koios_sdk::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a client with default configuration (Mainnet)
let client = Client::new()?;
// Get the current tip of the blockchain
let tip = client.get_tip().await?;
println!("Current tip: {:?}", tip);
Ok(())
}
```
## Network Selection
```rust
use koios_sdk::{Client, Network};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Connect to Preprod network
let client = Client::builder()
.network(Network::Preprod)
.build()?;
// Get the current epoch info
let epoch = client.get_epoch_info(None, None).await?;
println!("Current epoch: {:?}", epoch);
Ok(())
}
```
## Authentication
```rust
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(())
}
```
## Advanced Configuration
```rust
use koios_sdk::ClientBuilder;
use governor::Quota;
use std::num::NonZeroU32;
use std::time::Duration;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = ClientBuilder::new()
.network(Network::Preview)
.timeout(Duration::from_secs(30))
.rate_limit(Quota::per_second(NonZeroU32::new(100).unwrap()))
.build()?;
Ok(())
}
```
## Features
The SDK supports several optional features:
- `rustls-tls` (default) - Uses rustls for TLS
- `native-tls` - Uses native TLS implementation
- `full` - Enables all optional features including base64 and hex encoding
Enable features in your `Cargo.toml`:
```toml
[dependencies]
koios-sdk = { version = "0.1.0", features = ["full"] }
```
## Examples
### Query Account Information
```rust
use koios_sdk::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new()?;
let stake_addresses = vec![
"stake1ux3g2c9dx2nhhehyrezyxpkstartcqmu9hk63qgfkccw5rqttygt7".to_string()
];
let account_info = client.get_account_info(&stake_addresses).await?;
println!("Account info: {:?}", account_info);
Ok(())
}
```
### Get Pool Information
```rust
use koios_sdk::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new()?;
let pool_ids = vec![
"pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2q3lkdy".to_string()
];
let pool_info = client.get_pool_info(&pool_ids).await?;
println!("Pool info: {:?}", pool_info);
Ok(())
}
```
## API Coverage
The SDK provides comprehensive coverage of all Koios API endpoints, including:
- [X] [Network](https://api.koios.rest/#tag--Network)
- [X] [Epoch](https://api.koios.rest/#tag--Epoch)
- [X] [Block](https://api.koios.rest/#tag--Block)
- [X] [Transaction](https://api.koios.rest/#tag--Transaction)
- [X] [Stake Account](https://api.koios.rest/#tag--Stake-Account)
- [X] [Address](https://api.koios.rest/#tag--Address)
- [X] [Asset](https://api.koios.rest/#tag--Asset)
- [X] [Governance](https://api.koios.rest/#tag--Governance)
- [X] [Pool](https://api.koios.rest/#tag--Pool)
- [X] [Script](https://api.koios.rest/#tag--Script)
- [X] [Ogmios](https://api.koios.rest/#tag--Ogmios)
## Error Handling
The SDK provides detailed error types for handling various failure cases:
```rust
use koios_sdk::{Client, error::Error};
#[tokio::main]
async fn main() {
let client = Client::new().unwrap();
match client.get_tip().await {
Ok(tip) => println!("Current tip: {:?}", tip),
Err(Error::Api { status, message }) => {
eprintln!("API error {}: {}", status, message);
}
Err(Error::RateLimit(wait_time)) => {
eprintln!("Rate limited, retry after {} seconds", wait_time);
}
Err(e) => eprintln!("Other error: {}", e),
}
}
```
## Development
### Building
To build the project:
```bash
# Debug build
cargo build
# Release build
cargo build --release
# Build with all features
cargo build --all-features
```
### Testing
Run the test suite:
```bash
# Run all tests
cargo test
# Run tests with all features
cargo test --all-features
# Run specific test
cargo test test_name
# Run tests with output
cargo test -- --nocapture
```
### Documentation
Generate and view the documentation:
```bash
# Generate documentation
cargo doc --no-deps
# Generate and open documentation in browser
cargo doc --no-deps --open
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.