# bitvavo-api-client
A Rust client library for the [Bitvavo API](https://docs.bitvavo.com/):
- Full REST API coverage: market data, trading, account, balances, deposits, and withdrawals
- WebSocket support for real-time public and private channels
- HMAC-SHA256 authentication for REST and WebSocket
- Async/await support with Tokio
- Strongly typed request/response structures
- Rate limit visibility from response headers
- Amounts and prices kept as strings to preserve exact decimal values
## TLS backends
The default `rustls-tls` feature uses rustls with the operating system certificate store for HTTPS and WSS connections.
To use the platform-native TLS implementation, disable default features and enable `native-tls`:
```toml
[dependencies]
bitvavo-api-client = { version = "0.1", default-features = false, features = ["native-tls"] }
```
## Library
Public REST API client:
```rust
use bitvavo_api_client::rest::{CandlesParams, RestClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = RestClient::public()?;
let ticker = client.ticker_price("BTC-EUR").await?;
println!("BTC-EUR: {}", ticker.price.unwrap_or_default());
let candles = client
.candles("BTC-EUR", "1h", &CandlesParams::new().limit(10))
.await?;
for candle in &candles {
println!("{}: close {}", candle.timestamp, candle.close);
}
Ok(())
}
```
Authenticated client:
```rust
use bitvavo_api_client::rest::{OrderRequest, RestClient};
use bitvavo_api_client::{ClientConfig, Side};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = RestClient::new(ClientConfig::with_credentials(
"your_api_key",
"your_api_secret",
))?;
let balances = client.balances().await?;
for balance in &balances {
println!("{}: {}", balance.symbol, balance.available);
}
let order = OrderRequest::limit("BTC-EUR", Side::Buy, "0.001", "50000");
let result = client.place_order(&order).await?;
println!("Order ID: {}", result.order_id);
Ok(())
}
```
WebSocket public channels:
```rust
use bitvavo_api_client::ws::{WsClient, WsEvent};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let (client, mut events) = WsClient::connect_public().await?;
client.subscribe_ticker(&["BTC-EUR", "ETH-EUR"])?;
client.subscribe_trades(&["BTC-EUR"])?;
while let Some(event) = events.recv().await {
match event {
WsEvent::Ticker(ticker) => {
println!(
"{}: bid {} ask {}",
ticker.market,
ticker.best_bid.unwrap_or_default(),
ticker.best_ask.unwrap_or_default()
);
}
WsEvent::Trade(trade) => {
println!("trade: {} {} @ {}", trade.market, trade.amount, trade.price);
}
WsEvent::Closed => break,
_ => {}
}
}
Ok(())
}
```
WebSocket private channel:
```rust
use bitvavo_api_client::ws::{WsClient, WsEvent};
use bitvavo_api_client::ClientConfig;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = ClientConfig::with_credentials("your_api_key", "your_api_secret");
let (client, mut events) = WsClient::connect(config).await?;
client.authenticate()?;
while let Some(event) = events.recv().await {
match event {
WsEvent::Authenticated => {
client.subscribe_account(&["BTC-EUR"])?;
}
WsEvent::Order(order) => println!("order update: {order:?}"),
WsEvent::Fill(fill) => println!("fill: {fill:?}"),
WsEvent::Closed => break,
_ => {}
}
}
Ok(())
}
```
## API coverage
REST endpoints:
| `time()` | `GET /time` | Public |
| `markets()`, `market()` | `GET /markets` | Public |
| `assets()`, `asset()` | `GET /assets` | Public |
| `order_book()` | `GET /{market}/book` | Public |
| `public_trades()` | `GET /{market}/trades` | Public |
| `candles()` | `GET /{market}/candles` | Public |
| `ticker_price()`, `ticker_prices()` | `GET /ticker/price` | Public |
| `ticker_book()`, `ticker_books()` | `GET /ticker/book` | Public |
| `ticker_24h()`, `tickers_24h()` | `GET /ticker/24h` | Public |
| `place_order()` | `POST /order` | Required |
| `get_order()` | `GET /order` | Required |
| `update_order()` | `PUT /order` | Required |
| `cancel_order()` | `DELETE /order` | Required |
| `get_orders()` | `GET /orders` | Required |
| `cancel_orders()` | `DELETE /orders` | Required |
| `open_orders()` | `GET /ordersOpen` | Required |
| `trades()` | `GET /trades` | Required |
| `account()` | `GET /account` | Required |
| `fees()` | `GET /account/fees` | Required |
| `balances()`, `balance()` | `GET /balance` | Required |
| `deposit_assets()` | `GET /depositAssets` | Required |
| `withdraw_assets()` | `POST /withdrawal` | Required |
| `deposit_history()` | `GET /depositHistory` | Required |
| `withdrawal_history()` | `GET /withdrawalHistory` | Required |
WebSocket channels:
- `ticker` - Best bid, best ask, and last price updates
- `ticker24h` - 24 hour statistics
- `trades` - Public trades
- `candles` - Candlestick updates per interval
- `book` - Order book deltas, with `get_book()` for snapshots
- `account` - Order and fill updates for your account (requires authentication)
The WebSocket client does not reconnect on its own.
A `WsEvent::ConnectionError` reports a transport or TLS failure.
A `WsEvent::Closed` event signals that the connection ended.
Reconnect with `WsClient::connect` and resubscribe when this happens.
## Configuration
```rust
use bitvavo_api_client::ClientConfig;
use std::time::Duration;
let config = ClientConfig::with_credentials("api_key", "api_secret")
.access_window_ms(10_000) // Signed request validity window
.timeout(Duration::from_secs(30)) // HTTP and WebSocket connection timeout
.rest_url("https://api.bitvavo.com/v2") // REST base URL override
.ws_url("wss://ws.bitvavo.com/v2/"); // WebSocket URL override
```
The client rejects unencrypted `http` and `ws` URLs by default.
Local tests can opt in with `.danger_allow_insecure_transport(true)`.
## Environment variables
You can set credentials via environment variables:
```bash
export BITVAVO_API_KEY=""
export BITVAVO_API_SECRET=""
```
`ClientConfig::from_env()` and `RestClient::from_env()` read these variables.
The examples and integration tests also load them from a `.env` file via `dotenvy`.
## Examples
```bash
cargo run --example market_data # Public REST market data
cargo run --example account # Private REST account data
cargo run --example ws_ticker # Live tickers and trades over WebSocket
```