Twelve Data Rust Client

A Rust API client for Twelve Data — comprehensive financial market data API with access to stocks, forex, ETFs, mutual funds, commodities, and cryptocurrencies across 50+ countries.

This client features automatic builder pattern generation for all API operations, making it ergonomic to work with endpoints that have many optional parameters.

Features

• ✅ Builder Pattern API: Clean, chainable parameter builders instead of functions with 20+ parameters
• ✅ Full API Coverage: Complete access to all Twelve Data endpoints (time series, fundamentals, ETFs, technical indicators, etc.)
• ✅ Type-Safe: Strongly typed request/response models generated from OpenAPI spec
• ✅ Async: Built on reqwest with async/await support via tokio
• ✅ Authentication: API key authentication via Authorization header

Installation

Add to your Cargo.toml:

[dependencies]
twelve-data-client = "0.4"
tokio = { version = "1.49.0", features = ["full"] }

Quick Start

use twelve_data_client::apis::{configuration, time_series_api};
use twelve_data_client::apis::time_series_api::GetTimeSeriesParams;
use twelve_data_client::models::GetTimeSeriesResponse;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure authentication
    let mut config = configuration::Configuration::new();
    config.api_key = Some(configuration::ApiKey {
        prefix: Some("apikey".to_string()),
        key: std::env::var("TWELVE_DATA_API_KEY")?,
    });

    // Build parameters using builder pattern
    let params = GetTimeSeriesParams::builder()
        .symbol("AAPL")
        .interval("1day")
        .outputsize(10)
        .build();

    // Make API call and handle response
    let response = time_series_api::get_time_series(&config, params).await?;
    
    match response {
        GetTimeSeriesResponse::TimeSeries(data) => {
            println!("Symbol: {:?}", data.meta.as_ref().unwrap().symbol);
            println!("Data points: {}", data.values.as_ref().unwrap().len());
        }
        GetTimeSeriesResponse::ApiError(err) => {
            eprintln!("API Error: {}", err.message.unwrap_or_default());
        }
        GetTimeSeriesResponse::Text(csv) => {
            println!("CSV Response:\n{}", csv);
        }
    }
    
    Ok(())
}

Authentication

Get your API key from the Twelve Data dashboard.

Set it as an environment variable:

export TWELVE_DATA_API_KEY="your_api_key_here"

Or configure it directly:

config.api_key = Some(configuration::ApiKey {
    prefix: Some("apikey".to_string()),
    key: "your_api_key_here".to_string(),
});

Response Types

Most endpoints return an enum with variants for different response scenarios:

• Data variant: Contains the actual response data (e.g., TimeSeries)
• ApiError variant: Contains error information when the API returns an error
• Text variant: Contains raw text (CSV) response when using format parameter

This provides type-safe error handling and format flexibility without needing to manually parse errors.

Available APIs

This client provides access to all Twelve Data endpoints organized by module:

• time_series_api - Historical OHLCV data
• fundamentals_api - Company financials, balance sheets, income statements
• reference_data_api - Symbols, exchanges, currencies
• technical_indicator_api - Technical analysis indicators
• market_data_api - Real-time quotes and prices
• etfs_api - ETF-specific data
• mutual_funds_api - Mutual fund data
• analysis_api - Analysis endpoints
• regulatory_api - Regulatory filings
• advanced_api - Advanced data endpoints

Code Generation

This client is auto-generated from the Twelve Data OpenAPI spec using openapi-generator-rust-builders, which adds automatic builder pattern support.

Requirements

Before regenerating the client, ensure you have:

• Java 21 or later - Required to run the OpenAPI Generator
• Python 3.6+ - Required for spec transformation scripts
• Maven - Included with the generator (uses ./mvnw wrapper)

Regenerating the Client

Run the provided script to fetch the latest spec, apply transformations, and regenerate:

bash regenerate.sh

This script:

1. Fetches the latest OpenAPI spec from Twelve Data
2. Removes the queryParameter security scheme (best practice: API keys should only be in headers, not query parameters)
3. Ensures all 200 responses include ApiError variant for error handling
4. Adds text/csv response type to endpoints supporting the format parameter
5. Renames response schemas to cleaner names (e.g., GetTimeSeries_200_response → time_series_data)
6. Regenerates the Rust client with the modified spec
7. Formats the generated code

First-Time Setup

If this is your first time generating the client, build the generator first:

cd openapi-generator-rust-builders
./mvnw clean package -DskipTests
cd ..
bash regenerate.sh

Examples

See the tests/ directory for complete working examples:

• time_series_builder.rs - Fetching historical time series data with builder pattern, including JSON, error, and CSV response handling

Run the tests:

export TWELVE_DATA_API_KEY="your_api_key"
cargo test --test time_series_builder

Documentation

• Twelve Data API Documentation
• API Reference
• Get API Key

License

This client library is licensed under the Unlicense.

The Twelve Data API is a commercial service. See Twelve Data pricing for details.

Links

• Twelve Data Website
• Twelve Data GitHub
• OpenAPI Generator Fork (with Rust Builders)
• Base OpenAPI Generator