# Quick Start Guide
Get up and running with rust-ibapi in minutes.
## Prerequisites
Before you begin, ensure you have:
1. **Rust installed** - [Install Rust](https://www.rust-lang.org/tools/install)
2. **IB Gateway or TWS** - Running and configured for API connections
3. **Git** - For cloning the repository
## Critical: Choose Your Feature
⚠️ **rust-ibapi requires exactly ONE feature flag:**
```mermaid
graph LR
Choice{Your Application Type?}
Sync[--features sync<br/>Traditional threads]
Async[--features async<br/>Tokio async/await]
Choice -->|Simple/Traditional| Sync
Choice -->|High Performance/Modern| Async
style Choice fill:#fff3e0
style Sync fill:#e8f5e9
style Async fill:#e3f2fd
```
- **`async` (default)** - Modern asynchronous execution using tokio
- **`sync`** - Traditional synchronous client; can be enabled on its own or alongside `async`
When both features are enabled, the async client remains on `client::Client` and the blocking client moves under `client::blocking::Client`.
## Installation
### As a Dependency
Add to your `Cargo.toml`:
```toml
[dependencies]
# Default async client
ibapi = "2.0"
# Sync-only (disable defaults)
ibapi = { version = "2.0", default-features = false, features = ["sync"] }
# Async + blocking
ibapi = { version = "2.0", features = ["sync"] }
```
### For Development
```bash
# Clone the repository
git clone https://github.com/wboayue/rust-ibapi.git
cd rust-ibapi
# Verify installation
cargo build # default async client
cargo build --no-default-features --features sync
cargo build --all-features
```
## Your First Example
### Step 1: Start IB Gateway/TWS
Ensure your IB Gateway or TWS is running with API connections enabled:
| IB Gateway | 127.0.0.1:4002 | 127.0.0.1:4001 |
| TWS | 127.0.0.1:7497 | 127.0.0.1:7496 |
### Step 2: Run a Simple Example
#### Sync Version
Create `src/main.rs`:
```rust
use ibapi::Client;
fn main() -> Result<(), Box<dyn std::error::Error>> {
// Connect to IB Gateway Paper Trading
let client = Client::connect("127.0.0.1:4002", 100)?;
// Request current time
let server_time = client.server_time()?;
println!("Server time: {}", server_time);
// Get account summary
let account_summary = client.account_summary()?;
for item in account_summary {
println!("{}: {} {}", item.tag, item.value, item.currency);
}
Ok(())
}
```
Run with:
```bash
cargo run --features sync
```
#### Async Version
Create `src/main.rs`:
```rust
use ibapi::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Connect to IB Gateway Paper Trading
let client = Client::connect("127.0.0.1:4002", 100).await?;
// Request current time
let server_time = client.server_time().await?;
println!("Server time: {}", server_time);
// Get account summary
let account_summary = client.account_summary().await?;
for item in account_summary {
println!("{}: {} {}", item.tag, item.value, item.currency);
}
Ok(())
}
```
Run with:
```bash
cargo run --features async
```
## Common Operations
### Creating Contracts
The library provides a type-safe contract builder API:
```rust
// Simple stock contract
let stock = Contract::stock("AAPL").build();
// Option with required fields enforced at compile time
let option = Contract::call("AAPL")
.strike(150.0)
.expires_on(2024, 12, 20)
.build();
```
For detailed documentation on creating all contract types, see the [Contract Builder Guide](contract-builder.md).
### Requesting Market Data
```rust
// Define a stock contract
let contract = Contract::stock("AAPL").build();
// Request real-time bars (sync)
let subscription = client.realtime_bars(&contract, BarSize::Sec5, WhatToShow::Trades, false)?;
for bar in subscription {
println!("Price: {}, Volume: {}", bar.close, bar.volume);
}
// Request real-time bars (async)
let mut subscription = client.realtime_bars(&contract, BarSize::Sec5, WhatToShow::Trades, false).await?;
while let Some(bar) = subscription.next().await {
println!("Price: {}, Volume: {}", bar.close, bar.volume);
}
```
### Placing Orders
```rust
// Create a market order
let contract = Contract::stock("AAPL");
let order = Order::market_order(Action::Buy, 100.0);
// Place the order
let order_id = client.next_order_id();
client.place_order(order_id, &contract, &order)?;
```
### Getting Account Information
```rust
// Get positions
let positions = client.positions()?;
for position in positions {
println!("{}: {} shares", position.contract.symbol, position.size);
}
// Get account values
let account_values = client.account_values()?;
for value in account_values {
println!("{}: {}", value.key, value.value);
}
```
## Running Examples
The repository includes many examples in the `examples/` directory:
```bash
# List all examples
ls examples/
# Run a sync example
cargo run --features sync --example account_summary
# Run an async example
cargo run --features async --example async_account_summary
# Run with debug logging
RUST_LOG=debug cargo run --features sync --example market_data
```
### Popular Examples
| `account_summary` | Display account information | `cargo run --no-default-features --features sync --example account_summary` |
| `market_data` | Stream real-time quotes | `cargo run --no-default-features --features sync --example market_data` |
| `place_order` | Place a simple order | `cargo run --no-default-features --features sync --example place_order` |
| `historical_data` | Fetch historical bars | `cargo run --no-default-features --features sync --example historical_data` |
| `contract_details` | Get contract information | `cargo run --no-default-features --features sync --example contract_details` |
For async versions, the default features are sufficient: `cargo run --example async_<name>`.
## Troubleshooting
### Common Issues and Solutions
#### "No feature specified" Error
```bash
error: no feature specified. Enable either 'sync' or 'async' feature
```
**Solution**: If you've disabled default features, add `--features sync` or `--features async` to your command.
#### "Mutually exclusive features" Error
```bash
error: features 'sync' and 'async' are mutually exclusive
```
**Solution**: Update to the latest release—current versions support enabling both features simultaneously.
#### Connection Refused
```bash
Error: Connection refused (os error 111)
```
**Solution**:
1. Ensure IB Gateway/TWS is running
2. Check the port number (4002 for paper, 4001 for live)
3. Enable API connections in IB Gateway/TWS settings
#### API Not Configured
```bash
Error: API connection not configured
```
**Solution**: In IB Gateway/TWS:
1. Go to Configuration → API → Settings
2. Enable "Enable ActiveX and Socket Clients"
3. Add 127.0.0.1 to trusted IPs
4. Disable "Read-Only API"
#### No Market Data Permissions
```bash
Error: No market data permissions
```
**Solution**: Ensure your IB account has market data subscriptions for the requested symbols.
### Debug Logging
Enable detailed logging to troubleshoot issues:
```bash
# Basic debug logging
RUST_LOG=debug cargo run --features sync --example your_example
# Trace-level logging (very verbose)
RUST_LOG=trace cargo run --features sync --example your_example
# Log only ibapi messages
RUST_LOG=ibapi=debug cargo run --features sync --example your_example
# Record all TWS messages for analysis
IBAPI_RECORDING_DIR=/tmp/tws-messages cargo run --features sync --example your_example
```
### Getting Help
1. **Check the examples** - Most common use cases are demonstrated
2. **Read the API docs** - `cargo doc --open --features sync`
3. **Review test cases** - Tests show expected behavior
4. **GitHub Issues** - Search existing issues or create a new one
5. **Documentation** - See [docs/](.) for detailed guides
## Next Steps
Now that you're up and running:
1. **Explore More Examples** - Check out the `examples/` directory
2. **Read the Architecture Guide** - Understand how rust-ibapi works internally
3. **Learn the API Patterns** - See [API Patterns](api-patterns.md)
4. **Contribute** - See [Contributing Guide](../CONTRIBUTING.md)
## Quick Reference
### Essential Commands
```bash
# Build
cargo build --features sync # or --features async
# Test
cargo test --features sync # or --features async
# Run example
cargo run --features sync --example example_name
# Generate docs
cargo doc --open --features sync
# Check code
cargo clippy --features sync -- -D warnings
cargo fmt --check
```
### Connection Endpoints
| IB Gateway Paper | 127.0.0.1 | 4002 |
| IB Gateway Live | 127.0.0.1 | 4001 |
| TWS Paper | 127.0.0.1 | 7497 |
| TWS Live | 127.0.0.1 | 7496 |
### Feature Selection Guide
Choose **sync** if you:
- Are new to Rust async programming
- Want simpler, traditional code
- Don't need high concurrency
- Prefer familiar thread-based patterns
Choose **async** if you:
- Need high performance
- Want to handle many concurrent operations
- Are comfortable with async/await
- Use other async libraries (tokio ecosystem)
Remember: You must choose exactly one!