odds-api 0.1.0

<p align="center">
  <a href="https://odds-api.net">
    <img src="assets/odds-api-hero.svg" alt="Odds API: easy access to odds, betting, sports, racing, and market data" width="100%">
  </a>
</p>

<p align="center">
  <a href="https://odds-api.net"><img alt="Website" src="https://img.shields.io/badge/website-odds--api.net-22C55E?style=for-the-badge&labelColor=0B1220"></a>
  <a href="https://api.odds-api.net/v1/reference"><img alt="API reference" src="https://img.shields.io/badge/API-api.odds--api.net%2Fv1-38BDF8?style=for-the-badge&labelColor=0B1220"></a>
  <a href="https://github.com/odds-api/odds-api-rust/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/odds-api/odds-api-rust?style=for-the-badge&labelColor=0B1220"></a>
  <a href="https://github.com/odds-api/odds-api-rust/forks"><img alt="GitHub forks" src="https://img.shields.io/github/forks/odds-api/odds-api-rust?style=for-the-badge&labelColor=0B1220"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/odds-api/odds-api-rust?style=for-the-badge&labelColor=0B1220"></a>
  <a href="https://docs.rs/odds-api"><img alt="docs.rs" src="https://img.shields.io/docsrs/odds-api?style=for-the-badge&labelColor=0B1220"></a>
  <a href="https://crates.io/crates/odds-api"><img alt="crates.io" src="https://img.shields.io/crates/v/odds-api?style=for-the-badge&labelColor=0B1220"></a>
  <img alt="OpenAPI" src="https://img.shields.io/badge/OpenAPI-3.1-FACC15?style=for-the-badge&labelColor=0B1220">
</p>

<h1 align="center">odds-api/odds-api-rust</h1>

<p align="center">
  <strong>Rust SDK for odds-api.net, an OpenAPI-first sports betting odds API for coding agents and developers.</strong>
</p>

<p align="center">
  Collect a free API key from <a href="https://odds-api.net">odds-api.net</a>.
</p>

<p align="center">
  <a href="#install">Install</a>
  .
  <a href="#quickstart">Quickstart</a>
  .
  <a href="#common-methods">Common methods</a>
  .
  <a href="#examples">Examples</a>
  .
  <a href="#safety">Safety</a>
  .
  <a href="SECURITY.md">Security</a>
</p>

---

## Install

Install from crates.io after publishing:

```bash
cargo add odds-api
```

Or use the GitHub repo before the crate is published:

```toml
[dependencies]
odds-api = { git = "https://github.com/odds-api/odds-api-rust", tag = "v0.1.0" }
```

For local development from the GitHub repo:

```bash
git clone https://github.com/odds-api/odds-api-rust.git
cd odds-api-rust
cargo test
```

## Quickstart

```rust
use odds_api::{query_params, OddsApiClient};

#[tokio::main]
async fn main() -> odds_api::Result<()> {
    let client = OddsApiClient::from_env()?;
    let params = query_params([("sport", "rugby-league"), ("league", "NRL")]);

    let events = client.search_events(Some(&params)).await?;
    println!("{events:#}");

    Ok(())
}
```

The SDK reads `ODDS_API_KEY` and `ODDS_API_BASE_URL` from the environment:

```rust
let client = OddsApiClient::from_env()?;
let sports = client.list_sports().await?;
```

## Common methods

- `list_sports`
- `list_bookmakers`
- `list_leagues`
- `search_events`
- `get_event`
- `get_event_bookmakers`
- `get_odds_snapshot`
- `get_odds_history`
- `find_best_odds`
- `compare_bookmakers`
- `find_arbitrage`
- `find_positive_ev`
- `get_line_movement`
- `search_racing_events`
- `get_racing_event`
- `get_racing_odds`
- `get_results`
- `get_api_metadata`
- `get_me`
- `get_usage`
- `get_limits`
- `get_market_schema`

## Examples

```text
examples/basic.rs
examples/arbitrage_scanner.rs
```

Run an example:

```bash
export ODDS_API_KEY="your_api_key"
cargo run --example basic
```

## Why use this SDK?

`odds-api-rust` keeps the Python and Go SDKs' small, mock-friendly shape while using idiomatic Rust:

- async requests with `reqwest`
- `ODDS_API_KEY` and `ODDS_API_BASE_URL` support
- API key auth with `X-API-Key`
- optional bearer token support
- typed error variants for auth, rate limits, validation, and server errors
- helper methods for common sports, racing, odds, betting, account, and metadata workflows
- generic `get` and `post` methods for endpoints not covered yet

## Safety

Arbitrage and positive EV examples are betting research workflows, not guaranteed-profit systems. Always account for stale odds, limits, delays, suspensions, voids, jurisdiction, and execution risk.

## Links

- Website: https://odds-api.net
- API: https://api.odds-api.net/v1
- OpenAPI: https://github.com/odds-api/odds-api/blob/main/openapi.yaml
- Main repo: https://github.com/odds-api/odds-api
- Rust package docs: https://docs.rs/odds-api