ostium-rust-sdk 0.1.0

# Quick Start Guide

Get up and running with the Ostium Rust SDK in under 5 minutes. This guide walks you through creating your first application that fetches market data and checks account balances.

## Prerequisites

- Rust 1.70+ installed ([Install Rust](https://rustup.rs/))
- Basic familiarity with async/await in Rust

## Step 1: Create a New Project

```bash
cargo new ostium-quickstart
cd ostium-quickstart
```

## Step 2: Add Dependencies

Add the SDK to your `Cargo.toml`:

```toml
[dependencies]
ostium-rust-sdk = "0.1.0"
tokio = { version = "1.0", features = ["full"] }
rust_decimal = "1.36"
tracing-subscriber = "0.3"
```

## Step 3: Write Your First Application

Replace the contents of `src/main.rs`:

```rust
use ostium_rust_sdk::{OstiumClient, Network, Result};
use tracing_subscriber;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize logging to see what's happening
    tracing_subscriber::fmt::init();

    println!("🚀 Ostium Quick Start");
    println!("====================\n");

    // Step 1: Create a client (read-only, no private key needed)
    println!("📡 Connecting to Ostium testnet...");
    let client = OstiumClient::new(Network::Testnet).await?;
    println!("✅ Connected successfully!\n");

    // Step 2: Fetch available trading pairs
    println!("📈 Fetching trading pairs...");
    let pairs = client.get_pairs().await?;
    println!("✅ Found {} trading pairs:", pairs.len());
    
    // Show first 3 pairs
    for pair in pairs.iter().take(3) {
        println!("  • {}", pair.symbol);
    }
    println!();

    // Step 3: Get current BTC price
    println!("💰 Fetching BTC/USD price...");
    match client.get_price("BTC/USD").await {
        Ok(price) => {
            println!("✅ BTC/USD: ${}", price.mark_price);
            println!("   24h High: ${}", price.high_24h);
            println!("   24h Low: ${}", price.low_24h);
        }
        Err(e) => {
            println!("⚠️  Could not fetch price: {}", e);
        }
    }
    println!();

    // Step 4: Check if market is open
    println!("🕐 Checking market hours...");
    let hours = client.get_trading_hours("BTC/USD").await?;
    println!("✅ Market is {}", if hours.is_open { "OPEN" } else { "CLOSED" });
    println!();

    println!("🎉 Quick start completed successfully!");
    println!("\n📚 What's next?");
    println!("   • Add a private key to enable trading");
    println!("   • Check out the examples/ directory");
    println!("   • Read the full documentation");

    Ok(())
}
```

## Step 4: Run Your Application

```bash
cargo run
```

You should see output like this:

```
🚀 Ostium Quick Start
====================

📡 Connecting to Ostium testnet...
✅ Connected successfully!

📈 Fetching trading pairs...
✅ Found 12 trading pairs:
  • BTC/USD
  • ETH/USD
  • SOL/USD

💰 Fetching BTC/USD price...
✅ BTC/USD: $43,256.78
   24h High: $44,120.00
   24h Low: $42,890.15

🕐 Checking market hours...
✅ Market is OPEN

🎉 Quick start completed successfully!

📚 What's next?
   • Add a private key to enable trading
   • Check out the examples/ directory
   • Read the full documentation
```

## Step 5: Add Trading Capabilities (Optional)

To enable trading, you'll need a private key. **Use testnet for learning!**

### Set Up Environment Variables

```bash
# Export your testnet private key
export OSTIUM_PRIVATE_KEY="0x..."
```

### Update Your Code

Add this to your `main.rs` after the market hours check:

```rust
// Step 5: Try account operations (requires private key)
println!("💳 Testing account operations...");

// Check if we have a private key
if let Ok(private_key) = std::env::var("OSTIUM_PRIVATE_KEY") {
    println!("🔑 Private key found, creating trading client...");
    
    let trading_client = OstiumClient::builder(Network::Testnet)
        .with_private_key(&private_key)?
        .build()
        .await?;

    // Check balance
    match trading_client.get_balance(None).await {
        Ok(balance) => {
            println!("✅ USDC Balance: {}", balance.total);
            
            // Get your address
            if let Some(address) = trading_client.signer_address() {
                println!("👤 Your address: {}", address);
            }
        }
        Err(e) => {
            println!("⚠️  Could not fetch balance: {}", e);
        }
    }
} else {
    println!("ℹ️  No private key found (OSTIUM_PRIVATE_KEY)");
    println!("   Add one to enable trading features");
}
```

## What You've Built

Congratulations! You've created an application that:

- ✅ Connects to the Ostium platform
- ✅ Fetches available trading pairs
- ✅ Gets real-time price data
- ✅ Checks market trading hours
- ✅ (Optional) Checks account balance

## Common Issues

### Connection Errors

If you see network errors:
- Check your internet connection
- Try again in a few seconds (temporary network issues)
- The testnet might be temporarily unavailable

### Compilation Errors

If the code doesn't compile:
- Make sure you're using Rust 1.70+: `rustup update`
- Verify your dependencies match the versions above
- Try `cargo clean` and then `cargo build`

### Empty Trading Pairs

If no trading pairs are returned:
- This is usually a temporary API issue
- Check the [Ostium status page](https://status.ostium.io)
- Try connecting to mainnet: `Network::Mainnet`

## What's Next?

Now that you have the basics working, explore more features:

### Learn Trading Operations
- **[Your First Trade](first-trade.md)** - Execute a complete trade
- **[Trading Guide](../guides/trading-operations.md)** - Advanced trading patterns

### Explore Market Data
- **[Market Data Guide](../guides/market-data.md)** - Historical data, price feeds
- **[Real-time Updates](../examples/price-streaming.md)** - Live price updates

### Build Real Applications
- **[Portfolio Manager](../examples/portfolio-management.md)** - Manage multiple positions
- **[Trading Bot](../examples/trading-bot.md)** - Automated trading strategies

### Production Deployment
- **[Error Handling](../guides/error-handling.md)** - Robust error handling
- **[Testing](../guides/testing.md)** - Test your integration
- **[Security](../architecture/security.md)** - Security best practices

## Need Help?

- **Documentation**: Check the [guides](../guides/) and [API reference](../api-reference/)
- **Examples**: Browse working examples in the [examples directory](../../examples/)
- **Issues**: Report problems on [GitHub Issues](https://github.com/ranger-finance/ostium-rust-sdk/issues)
- **Discussions**: Ask questions in [GitHub Discussions](https://github.com/ranger-finance/ostium-rust-sdk/discussions)

---

**Ready for more?** Try the [Your First Trade](first-trade.md) tutorial to learn trading operations!