kiteconnect-async-wasm 1.0.9

Modern async Rust client for KiteConnect REST APIs with WASM support. Clean, well-documented, and focused on REST-only operations.
Documentation

KiteConnect Async WASM v1.0.6

โš ๏ธ IMPORTANT DISCLAIMER โš ๏ธ

๐Ÿค– AI-GENERATED CODE - USE AT YOUR OWN RISK

This entire codebase has been generated using artificial intelligence and automated tools. While comprehensive testing has been performed, users should:

  • Thoroughly test all functionality in their specific use cases
  • Review and validate code before production use
  • Use at their own risk and responsibility
  • Not rely on this for critical financial operations without extensive validation

The maintainers provide no warranties or guarantees regarding the correctness, reliability, or suitability of this AI-generated code.

Crates.io Documentation License: Unlicense

Modern async Rust client for KiteConnect REST APIs with dual API support, enhanced error handling, and WASM compatibility

A production-ready, high-performance Rust library for KiteConnect API integration featuring both legacy and strongly-typed APIs.

๐Ÿš€ Features v1.0.6

  • โœ… Robust Historical Data API - Enhanced Candle deserialization with support for multiple API response formats
  • โœ… Environment Variable Integration - All examples use secure environment variables for API credentials
  • โœ… Enhanced Error Handling - Improved handling of missing metadata and OI fields
  • โœ… Timezone-Aware Parsing - Support for +0530 timezone and various date formats
  • โœ… Production-Ready Examples - Tested examples that work with real KiteConnect API
  • โœ… Enhanced Historical Data API - New HistoricalDataRequest struct with NaiveDateTime precision
  • โœ… Dual Serde Support - Flexible Interval enum accepting both strings and integers
  • โœ… Organized Enum System - Modular enum structure for better maintainability
  • โœ… Dual API Support - Legacy JSON + new strongly-typed APIs
  • โœ… Automatic Retry Logic with exponential backoff
  • โœ… Response Caching for performance optimization
  • โœ… Full WASM Compatibility for web applications
  • โœ… Thread-Safe Design with connection pooling
  • โœ… Comprehensive Documentation with migration guide
  • โœ… Backward Compatibility - all existing code continues to work
  • โœ… Professional Code Quality - Clippy optimized and formatted

๐Ÿ†• What's New in v1.0.6

๐Ÿ”ง Enhanced Historical Data Reliability

The v1.0.6 release focuses on making historical data fetching production-ready and robust:

use kiteconnect_async_wasm::connect::KiteConnect;
use kiteconnect_async_wasm::models::market_data::HistoricalDataRequest;
use kiteconnect_async_wasm::models::common::Interval;
use chrono::NaiveDateTime;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ๐Ÿ”’ Secure: Use environment variables
    let api_key = env::var("KITE_API_KEY")?;
    let access_token = env::var("KITE_ACCESS_TOKEN")?;
    let client = KiteConnect::new(&api_key, &access_token);

    // ๐Ÿ“Š Robust: Handles various API response formats
    let request = HistoricalDataRequest::new(
        256265, // Instrument token
        NaiveDateTime::parse_from_str("2024-12-20 09:00:00", "%Y-%m-%d %H:%M:%S")?,
        NaiveDateTime::parse_from_str("2024-12-20 16:00:00", "%Y-%m-%d %H:%M:%S")?,
        Interval::FiveMinute,
    );

    // โœ… Works reliably with real KiteConnect API
    let data = client.historical_data_typed(request).await?;
    println!("Fetched {} candles successfully!", data.candles.len());
    
    Ok(())
}

Key Improvements:

  • โœ… Custom Candle Deserializer - Handles both array and object formats from KiteConnect API
  • โœ… Metadata Synthesis - Generates metadata when API doesn't provide it
  • โœ… Timezone Support - Proper parsing of +0530 timezone and various date formats
  • โœ… Missing Field Handling - Graceful handling when Open Interest (OI) data is unavailable
  • โœ… Environment Variables - All examples use secure credential management
  • โœ… Real API Testing - Examples tested with actual KiteConnect API responses

๐ŸŽฏ Quick Start

Installation

[dependencies]
kiteconnect-async-wasm = "1.0.9"

# For WASM targets
# kiteconnect-async-wasm = "1.0.9", features = ["wasm"] }

Basic Usage (Legacy API - Backward Compatible)

use kiteconnect_async_wasm::connect::KiteConnect;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = KiteConnect::new("your_api_key", "");

    // Step 1: Get login URL and complete authentication
    println!("Login URL: {}", client.login_url());
    
    // Step 2: After authentication, generate session
    let session = client.generate_session("request_token", "api_secret").await?;
    println!("Session: {:?}", session);
    
    // Step 3: Use APIs (existing code works as before)
    let holdings = client.holdings().await?;
    println!("Holdings: {:?}", holdings);
    
    Ok(())
}

New Typed API (Recommended for v1.0.2)

use kiteconnect_async_wasm::connect::KiteConnect;
use kiteconnect_async_wasm::models::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KiteConnect::new("api_key", "access_token");
    
    // Strongly-typed responses with automatic retry and error handling
    let holdings: Vec<Holding> = client.holdings_typed().await?;
    let positions: Vec<Position> = client.positions_typed().await?;
    
    // Enhanced error handling
    match client.orders_typed().await {
        Ok(orders) => {
            println!("Found {} orders", orders.len());
            for order in orders {
                println!("Order {}: {} {} @ โ‚น{}", 
                    order.order_id, 
                    order.transaction_type, 
                    order.trading_symbol, 
                    order.price.unwrap_or(0.0)
                );
            }
        }
        Err(KiteError::Authentication(msg)) => {
            eprintln!("Authentication failed: {}", msg);
        }
        Err(KiteError::Api { status, message, .. }) => {
            eprintln!("API error {}: {}", status, message);
        }
        Err(e) => eprintln!("Other error: {}", e),
    }
    
    Ok(())
}

Enhanced Historical Data API (v1.0.3)

use kiteconnect_async_wasm::connect::KiteConnect;
use kiteconnect_async_wasm::models::market_data::HistoricalDataRequest;
use kiteconnect_async_wasm::models::common::Interval;
use chrono::NaiveDateTime;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = KiteConnect::new("api_key", "access_token");
    
    // New structured approach with precise datetime handling
    let request = HistoricalDataRequest::new(
        738561,  // RELIANCE instrument token
        NaiveDateTime::parse_from_str("2023-11-01 09:15:00", "%Y-%m-%d %H:%M:%S")?,
        NaiveDateTime::parse_from_str("2023-11-30 15:30:00", "%Y-%m-%d %H:%M:%S")?,
        Interval::Day,
    ).continuous(false).with_oi(true);
    
    let historical_data = client.historical_data_typed(request).await?;
    
    println!("Received {} candles", historical_data.candles.len());
    for candle in &historical_data.candles {
        println!("Date: {}, OHLC: {}/{}/{}/{}, Volume: {}", 
            candle.date, candle.open, candle.high, candle.low, candle.close, candle.volume);
    }
    
    Ok(())
}

Flexible Interval Usage (v1.0.3)

use kiteconnect_async_wasm::models::common::Interval;

// Accepts both string and integer formats
let from_string: Interval = serde_json::from_str("\"day\"").unwrap();
let from_integer: Interval = serde_json::from_str("0").unwrap();  // 0 = Day

// Always serializes as strings
assert_eq!(serde_json::to_string(&Interval::Day).unwrap(), "\"day\"");
assert_eq!(serde_json::to_string(&Interval::Minute).unwrap(), "\"minute\"");

Running Examples

KiteConnect REST API sample

cargo run --example connect_sample
cargo run --example historical_data_typed_example
cargo run --example endpoint_management_demo

โœ… Completed Features

  • โœ… Comprehensive serializer structs for all KiteConnect data structures

    • Full typed models for all API responses (see /src/models/)
    • Dual API support: Legacy JsonValue + new strongly-typed APIs
    • Type-safe access to holdings, orders, positions, market data, etc.
  • โœ… Advanced reconnection mechanism with intelligent retry logic

    • Automatic retry with exponential backoff
    • Configurable retry attempts and delays
    • Built-in rate limiting respecting official API limits
    • Connection pooling and automatic error recovery

Attribution

Current Maintainer: SPRAGE shauna.pai@gmail.com

This project was originally created by Joe Paul and other contributors. The current version has been significantly rewritten and modernized with:

  • Complete async/await implementation
  • WASM compatibility
  • Enhanced feature flags system
  • Comprehensive documentation
  • Modern CI/CD pipeline

License

This software is released into the public domain under The Unlicense. See the LICENSE file for details.

No warranties provided - This software is provided "as is" without warranty of any kind.

๐Ÿ“Š Performance Features

Automatic Caching

// Instruments data is automatically cached for 1 hour
let instruments1 = client.instruments(None).await?; // API call
let instruments2 = client.instruments(None).await?; // Cached response (fast!)

Intelligent Retry Logic

// All typed methods automatically retry with exponential backoff
let holdings = client.holdings_typed().await?; // Retries on network errors

Concurrent Operations

use tokio::try_join;

// Fetch multiple endpoints concurrently
let (holdings, positions, orders) = try_join!(
    client.holdings_typed(),
    client.positions_typed(), 
    client.orders_typed()
)?;

๐Ÿ”ง Advanced Configuration

use kiteconnect_async_wasm::connect::{KiteConnect, KiteConnectConfig, RetryConfig, CacheConfig};
use std::time::Duration;

let config = KiteConnectConfig {
    timeout: 60,
    retry_config: RetryConfig {
        max_retries: 5,
        base_delay: Duration::from_millis(200),
        max_delay: Duration::from_secs(10),
        exponential_backoff: true,
    },
    cache_config: Some(CacheConfig {
        enable_instruments_cache: true,
        cache_ttl_minutes: 60,
        max_cache_size: 1000,
    }),
    max_idle_connections: 20,
    idle_timeout: 60,
    ..Default::default()
};

let client = KiteConnect::with_config("api_key", "access_token", config);

๐ŸŒ WebAssembly Support

use wasm_bindgen::prelude::*;
use kiteconnect_async_wasm::connect::KiteConnect;

#[wasm_bindgen]
pub async fn get_portfolio_summary() -> Result<String, JsValue> {
    let client = KiteConnect::new("api_key", "access_token");
    
    let holdings = client.holdings_typed().await
        .map_err(|e| JsValue::from_str(&e.to_string()))?;
    
    let total_value: f64 = holdings.iter()
        .map(|h| h.last_price * h.quantity as f64)
        .sum();
        
    Ok(format!("Portfolio value: โ‚น{:.2}", total_value))
}

๐Ÿ“ˆ API Coverage

โœ… Complete API Support

Module Legacy Methods Typed Methods Status
Authentication โœ… โœ… Complete
Portfolio โœ… โœ… Complete
Orders โœ… โœ… Complete
Market Data โœ… โœ… Complete
Mutual Funds โœ… โœ… Complete

Key Methods Available

Portfolio APIs:

  • holdings() / holdings_typed() - Get stock holdings
  • positions() / positions_typed() - Get trading positions
  • auctions() / auctions_typed() - Get auction instruments

Order Management:

  • orders() / orders_typed() - Get all orders
  • place_order() / place_order_typed() - Place new orders
  • modify_order() / modify_order_typed() - Modify existing orders
  • cancel_order() - Cancel orders
  • trades() / trades_typed() - Get trade history

Market Data:

  • instruments() - Get instrument master (cached)
  • quote() / quote_typed() - Get real-time quotes
  • ohlc() / ohlc_typed() - Get OHLC data
  • ltp() / ltp_typed() - Get last traded price
  • historical_data() / historical_data_typed() - Get historical candles

Mutual Funds:

  • mf_orders() / mf_orders_typed() - Get MF orders
  • place_mf_order() / place_mf_order_typed() - Place MF orders
  • mf_sips() / mf_sips_typed() - Get SIP details
  • place_mf_sip() / place_mf_sip_typed() - Create SIPs
  • mf_holdings() / mf_holdings_typed() - Get MF holdings

๐Ÿ”„ Migration from v0.x

All existing code continues to work without changes! For new projects, use the typed APIs:

// Old way (still works)
let holdings = client.holdings().await?;
let first_isin = holdings["data"][0]["isin"].as_str().unwrap();

// New way (recommended)
let holdings = client.holdings_typed().await?;
let first_isin = &holdings[0].isin; // Type-safe access

See MIGRATION_GUIDE.md for detailed migration instructions.

๐Ÿ› ๏ธ Error Handling

v1.0.0 provides comprehensive error types:

use kiteconnect_async_wasm::models::common::KiteError;

match client.place_order_typed(&order_params).await {
    Ok(response) => println!("Order placed: {}", response.order_id),
    Err(KiteError::Authentication(msg)) => {
        // Handle authentication errors
        println!("Please re-authenticate: {}", msg);
    }
    Err(KiteError::Api { status, message, error_type }) => {
        // Handle API errors with context
        println!("API Error {}: {} ({})", status, message, error_type.unwrap_or_default());
    }
    Err(KiteError::Http(reqwest_err)) => {
        // Handle network errors (automatically retried)
        println!("Network error: {}", reqwest_err);
    }
    Err(e) => println!("Other error: {}", e),
}

๐Ÿ“š Examples

Check out the examples directory:

  • Basic Usage: Simple API calls and authentication
  • Portfolio Tracker: Real-time portfolio monitoring
  • Order Management: Placing and managing orders
  • Market Data: Fetching quotes and historical data
  • WASM Integration: Using in web applications

๐Ÿงช Testing

# Run all tests
cargo test

# Run with specific features
cargo test --features native
cargo test --features wasm

# Run integration tests (requires network)
cargo test --test integration_tests

๐Ÿ“‹ Requirements

  • Rust: 1.70.0 or later
  • Tokio: For async runtime (native)
  • Valid KiteConnect API credentials

๐Ÿค Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Automated Release Process

This repository uses automated releases:

  • Version Management: Use ./scripts/bump-version.sh [patch|minor|major|VERSION] to create release branches
  • Automated Publishing: When PRs are merged to main, GitHub Actions automatically:
    • Creates git tags
    • Publishes to crates.io
    • Generates GitHub releases
  • Documentation: See AUTOMATED_RELEASES.md for detailed workflow information
# Example: Bump to next patch version
./scripts/bump-version.sh patch

# Example: Bump to specific version  
./scripts/bump-version.sh 1.0.4

๐Ÿ“„ License

This project is released under the Unlicense - see the LICENSE file for details.

โš ๏ธ Disclaimer

This is an unofficial library. Use at your own risk. Not affiliated with Zerodha or KiteConnect.

๐Ÿ”— Links


Built with โค๏ธ in Rust for the trading community