koios_sdk/api/

account.rs

use crate::{
    error::Result,
    models::{
        account::{
            AccountAddresses, AccountAssets, AccountHistory, AccountInfo, AccountList,
            AccountRewards, AccountUpdates,
        },
        address::AddressTransaction,
        requests::{
            StakeAddressesRequest, StakeAddressesWithEpochRequest,
            StakeAddressesWithExtendedRequest, StakeAddressesWithFirstOnlyAndEmptyRequest,
        },
        UtxoInfo,
    },
    types::{AfterBlockHeight, StakeAddress},
    Client,
};

impl Client {
    /// Get a list of all stake addresses that have at least 1 transaction
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let accounts = client.get_account_list().await?;
    ///     println!("Account list: {:?}", accounts);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_list(&self) -> Result<Vec<AccountList>> {
        self.get("/account_list").await
    }

    /// Get the account information for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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(())
    /// }
    /// ```
    pub async fn get_account_info(&self, stake_addresses: &[String]) -> Result<Vec<AccountInfo>> {
        let request = StakeAddressesRequest::new(stake_addresses.to_vec());
        self.post("/account_info", &request).await
    }

    /// Get the cached account information for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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_cached(&stake_addresses).await?;
    ///     println!("Cached account info: {:?}", account_info);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_info_cached(
        &self,
        stake_addresses: &[String],
    ) -> Result<Vec<AccountInfo>> {
        let request: StakeAddressesRequest = StakeAddressesRequest::new(stake_addresses.to_vec());
        self.post("/account_info_cached", &request).await
    }

    /// Get a list of all UTxOs for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    /// * `extended` - Optional flag to include extended information
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 utxos = client.get_account_utxos(&stake_addresses, Some(true)).await?;
    ///     println!("Account UTXOs: {:?}", utxos);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_utxos(
        &self,
        stake_addresses: &[String],
        extended: Option<bool>,
    ) -> Result<Vec<UtxoInfo>> {
        let request = StakeAddressesWithExtendedRequest::new(stake_addresses.to_vec(), extended);
        self.post("/account_utxos", &request).await
    }

    /// Get a list of all transactions for a given stake address
    ///
    /// # Arguments
    ///
    /// * `stake_address` - Stake address to query
    /// * `after_block_height` - Optional block height to filter from
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use koios_sdk::Client;
    /// use koios_sdk::types::{StakeAddress, AfterBlockHeight};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     let client = Client::new()?;
    ///     let stake_address = "stake1ux3g2c9dx2nhhehyrezyxpkstartcqmu9hk63qgfkccw5rqttygt7";
    ///     let txs = client.get_account_transactions(
    ///         StakeAddress::new(stake_address),
    ///         Some(AfterBlockHeight::new(42000000))
    ///     ).await?;
    ///     println!("Account transactions: {:?}", txs);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_transactions(
        &self,
        stake_address: StakeAddress,
        after_block_height: Option<AfterBlockHeight>,
    ) -> Result<Vec<AddressTransaction>> {
        // Encode stake address
        let encoded_stake_addr = urlencoding::encode(stake_address.value()).to_string();

        // Start building endpoint with encoded stake address
        let mut endpoint = format!("/account_txs?_stake_address={}", encoded_stake_addr);

        // Add encoded block height if present
        if let Some(height) = after_block_height {
            let encoded_height = urlencoding::encode(&height.value().to_string()).to_string();
            endpoint.push_str(&format!("&_after_block_height={}", encoded_height));
        }

        self.get(&endpoint).await
    }

    /// Get the full rewards history for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    /// * `epoch_no` - Optional epoch number to query from
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 epoch_no = Some("320".to_string());
    ///     let rewards = client.get_account_rewards(&stake_addresses, epoch_no).await?;
    ///     println!("Account rewards: {:?}", rewards);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_rewards(
        &self,
        stake_addresses: &[String],
        epoch_no: Option<String>,
    ) -> Result<Vec<AccountRewards>> {
        let request = StakeAddressesWithEpochRequest::new(
            stake_addresses.to_vec(),
            epoch_no.map(|e| e.parse().unwrap()),
        );
        self.post("/account_rewards", &request).await
    }

    /// Get the account updates for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 updates = client.get_account_updates(&stake_addresses).await?;
    ///     println!("Account updates: {:?}", updates);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_updates(
        &self,
        stake_addresses: &[String],
    ) -> Result<Vec<AccountUpdates>> {
        let request = StakeAddressesRequest::new(stake_addresses.to_vec());
        self.post("/account_updates", &request).await
    }

    /// Get all addresses associated with given staking accounts
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    /// * `first_only` - Optional flag to return only the first address
    /// * `empty` - Optional flag to include empty addresses
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 addresses = client.get_account_addresses(
    ///         &stake_addresses,
    ///         Some(true),
    ///         Some(false)
    ///     ).await?;
    ///     println!("Account addresses: {:?}", addresses);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_addresses(
        &self,
        stake_addresses: &[String],
        first_only: Option<bool>,
        empty: Option<bool>,
    ) -> Result<Vec<AccountAddresses>> {
        let request = StakeAddressesWithFirstOnlyAndEmptyRequest::new(
            stake_addresses.to_vec(),
            first_only,
            empty,
        );
        self.post("/account_addresses", &request).await
    }

    /// Get the native asset balance for given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 assets = client.get_account_assets(&stake_addresses).await?;
    ///     println!("Account assets: {:?}", assets);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_assets(
        &self,
        stake_addresses: &[String],
    ) -> Result<Vec<AccountAssets>> {
        let request = StakeAddressesRequest::new(stake_addresses.to_vec());
        self.post("/account_assets", &request).await
    }

    /// Get the staking history of given stake addresses
    ///
    /// # Arguments
    ///
    /// * `stake_addresses` - List of stake addresses to query
    /// * `epoch_no` - Optional epoch number to query from
    ///
    /// # Examples
    ///
    /// ```no_run
    /// 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 epoch_no = Some("320".to_string());
    ///     let history = client.get_account_history(&stake_addresses, epoch_no).await?;
    ///     println!("Account history: {:?}", history);
    ///     Ok(())
    /// }
    /// ```
    pub async fn get_account_history(
        &self,
        stake_addresses: &[String],
        epoch_no: Option<String>,
    ) -> Result<Vec<AccountHistory>> {
        let request = StakeAddressesWithEpochRequest::new(
            stake_addresses.to_vec(),
            epoch_no.map(|e| e.parse().unwrap()),
        );
        self.post("/account_history", &request).await
    }
}