Databento.Client 3.0.17-beta

databento-dotnet

A high-performance .NET client for accessing Databento market data, supporting both real-time streaming and historical data queries.

⚠️ Beta Software: This is a newly developed client library. While functional and tested, it should be thoroughly validated in your specific use case before production deployment. Please report any issues to the issue tracker.

Installation

NuGet Package (Recommended)

📦 Package: Databento.Client on NuGet.org

Install via .NET CLI:

dotnet add package Databento.Client --version 3.0.6-beta

Or via Package Manager Console:

Install-Package Databento.Client -Version 3.0.6-beta

Or add directly to your .csproj:

<ItemGroup>
  <PackageReference Include="Databento.Client" Version="3.0.6-beta" />
</ItemGroup>

Build from Source

See Building section below for instructions on building from source.

Features

• Live Streaming: Real-time market data with async/await and IAsyncEnumerable support
• Historical Data: Query past market data with time-range filtering
• Cross-Platform: Works on Windows, Linux, and macOS
• High Performance: Built on top of Databento's C++ client library
• Type-Safe: Strongly-typed API with full IntelliSense support
• .NET 8: Modern C# with nullable reference types

Implementation Status

Record Type Coverage: 100% ✅

All 16 DBN record types from databento-cpp are fully implemented:

API Coverage

Implementation Statistics

• Total Record Types: 16/16 (100%)
• Enumerations: 11/11 (100%)
  • Schema, RType, Action, Side, InstrumentClass, MatchAlgorithm, UserDefinedInstrument, SecurityUpdateAction, StatType, StatUpdateAction, SType
• Helper Classes: 3/3 (100%)
  • FlagSet, Constants, BidAskPair/ConsolidatedBidAskPair
• Live Streaming: Fully functional
• Binary Deserialization: All DBN formats supported
• Lines of Code: ~2,500 in high-level API, ~500 in P/Invoke layer, ~800 in native wrapper

Recent Changes

Latest (November 2025) - Production Ready

• ✅ Reference API implementation (SecurityMaster, AdjustmentFactors, CorporateActions)
• ✅ OpenTelemetry telemetry with retry policies
• ✅ Complete metadata & symbol mapping (TsSymbolMap, PitSymbolMap)
• ✅ All 16 record types with proper deserialization
• ✅ Thread-safe LiveClient with reconnection support

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Your .NET Application                     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│           Databento.Client (High-Level API)                  │
│   • LiveClient, HistoricalClient                            │
│   • Async/await, IAsyncEnumerable, Events                   │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│        Databento.Interop (P/Invoke Layer)                   │
│   • SafeHandles, Marshaling                                 │
└────────────────────────┬────────────────────────────────────┘
                         │ P/Invoke
┌────────────────────────▼────────────────────────────────────┐
│      Databento.Native (C Wrapper - CMake)                   │
│   • C exports wrapping databento-cpp                        │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│            databento-cpp (Git Submodule)                    │
│   • Live streaming, Historical queries                      │
│   • DBN encoding/decoding                                   │
└─────────────────────────────────────────────────────────────┘

Prerequisites

For Building

Required:

• .NET 8 SDK or later
• CMake 3.24 or later
• C++17 compatible compiler:
  • Windows: Visual Studio 2019 or later
  • Linux: GCC 9+ or Clang 10+
  • macOS: Xcode 11+

Automatically fetched by CMake:

• databento-cpp (via FetchContent)
• OpenSSL 3.0+
• Zstandard (zstd)
• nlohmann_json

For Using (NuGet Package)

• .NET 8 Runtime or later

Quick Start

1. Install Package

dotnet add package Databento.Client --version 3.0.5-beta

2. Set API Key

Set your Databento API key as an environment variable:

Windows:

$env:DATABENTO_API_KEY="your-api-key-here"

Linux/macOS:

export DATABENTO_API_KEY="your-api-key-here"

Get your API key at https://databento.com/portal/keys

3. Write Code - Live Streaming Example

using Databento.Client.Builders;
using Databento.Client.Models;

// Get API key from environment variable (secure)
var apiKey = Environment.GetEnvironmentVariable("DATABENTO_API_KEY")
    ?? throw new InvalidOperationException("DATABENTO_API_KEY environment variable not set");

// Create live client
await using var client = new LiveClientBuilder()
    .WithApiKey(apiKey)
    .Build();

// Subscribe to events
client.DataReceived += (sender, e) =>
{
    Console.WriteLine($"Received: {e.Record}");
};

// Subscribe to NVDA trades
await client.SubscribeAsync(
    dataset: "EQUS.MINI",
    schema: Schema.Trades,
    symbols: new[] { "NVDA" }
);

// Start streaming
await client.StartAsync();

// Stream records using IAsyncEnumerable
await foreach (var record in client.StreamAsync())
{
    // Process records
    if (record is TradeMessage trade)
    {
        Console.WriteLine($"Trade: {trade.InstrumentId} @ {trade.PriceDecimal}");
    }
}

4. Historical Data Example

using Databento.Client.Builders;
using Databento.Client.Models;

// Get API key from environment variable (secure)
var apiKey = Environment.GetEnvironmentVariable("DATABENTO_API_KEY")
    ?? throw new InvalidOperationException("DATABENTO_API_KEY environment variable not set");

// Create historical client
await using var client = new HistoricalClientBuilder()
    .WithApiKey(apiKey)
    .Build();

// Define time range - Static trading day: November 11-12, 2025
var startTime = new DateTimeOffset(2025, 11, 11, 0, 0, 0, TimeSpan.Zero); // 11/11/2025 00:00 UTC
var endTime = new DateTimeOffset(2025, 11, 12, 23, 59, 59, TimeSpan.Zero);   // 11/12/2025 23:59 UTC

// Query historical trades
await foreach (var record in client.GetRangeAsync(
    dataset: "EQUS.MINI",
    schema: Schema.Trades,
    symbols: new[] { "NVDA" },
    startTime: startTime,
    endTime: endTime))
{
    Console.WriteLine($"Historical record: {record}");
}

Try it yourself: Run the included example with:

dotnet run --project examples/Historical.Readme.Example/Historical.Readme.Example.csproj

Building

Build All (Native + .NET)

# Windows
./build/build-all.ps1 -Configuration Release

# Linux/macOS
./build/build-all.sh --configuration Release

Build Native Library Only

# Windows
./build/build-native.ps1 -Configuration Release

# Linux/macOS
./build/build-native.sh --configuration Release

Build .NET Solution Only

dotnet build databento-dotnet.sln -c Release

Project Structure

databento_client/
├── src/
│   ├── Databento.Native/          # C++ native wrapper
│   │   ├── include/               # C API headers
│   │   ├── src/                   # C++ implementation
│   │   └── CMakeLists.txt
│   ├── Databento.Interop/         # P/Invoke layer
│   │   ├── Native/                # P/Invoke declarations
│   │   └── Handles/               # SafeHandle wrappers
│   └── Databento.Client/          # High-level .NET API
│       ├── Live/                  # Live streaming
│       ├── Historical/            # Historical queries
│       ├── Reference/             # Reference data APIs
│       ├── Models/                # Data models
│       └── Builders/              # Builder pattern
├── examples/
│   ├── LiveStreaming.Example/
│   ├── HistoricalData.Example/
│   ├── Reference.Example/
│   └── (26+ examples total)
├── build/
│   ├── build-native.ps1           # Native build (Windows)
│   ├── build-native.sh            # Native build (Linux/macOS)
│   └── build-all.ps1              # Full solution build
└── databento-dotnet.sln           # Visual Studio solution

Running Examples

Prerequisites: Set the DATABENTO_API_KEY environment variable (see API Key Setup above).

# Run live streaming example
dotnet run --project examples/LiveStreaming.Example

# Run historical data example
dotnet run --project examples/HistoricalData.Example

# Run reference data example
dotnet run --project examples/Reference.Example

Supported Schemas

• MBO: Market by order
• MBP-1: Market by price (Level 1)
• MBP-10: Market by price (Level 10)
• Trades: Trade messages
• OHLCV: OHLCV bars (1s, 1m, 1h, 1d)
• Definition: Instrument definitions
• Statistics: Market statistics
• Status: Trading status
• Imbalance: Order imbalances

API Documentation

LiveClient

ILiveClient client = new LiveClientBuilder()
    .WithApiKey(apiKey)
    .Build();

// Events
client.DataReceived += (sender, e) => { /* ... */ };
client.ErrorOccurred += (sender, e) => { /* ... */ };

// Methods
await client.SubscribeAsync(dataset, schema, symbols);
await client.StartAsync();
await client.StopAsync();

// IAsyncEnumerable streaming
await foreach (var record in client.StreamAsync()) { /* ... */ }

HistoricalClient

IHistoricalClient client = new HistoricalClientBuilder()
    .WithApiKey(apiKey)
    .Build();

// Query historical data
await foreach (var record in client.GetRangeAsync(
    dataset, schema, symbols, startTime, endTime))
{
    // Process records
}

ReferenceClient

IReferenceClient client = new ReferenceClientBuilder()
    .SetApiKey(apiKey)
    .Build();

// Get latest security master data
var records = await client.SecurityMaster.GetLastAsync(
    symbols: new[] { "NVDA" },
    stypeIn: SType.RawSymbol
);

// Get security master data for a date range
var historicalRecords = await client.SecurityMaster.GetRangeAsync(
    start: DateTimeOffset.UtcNow.AddDays(-30),
    end: DateTimeOffset.UtcNow,
    symbols: new[] { "NVDA" }
);

// Get adjustment factors
var adjustments = await client.AdjustmentFactors.GetRangeAsync(
    start: DateTimeOffset.UtcNow.AddDays(-90),
    symbols: new[] { "NVDA" }
);

// Get corporate actions
var corporateActions = await client.CorporateActions.GetRangeAsync(
    start: DateTimeOffset.UtcNow.AddYears(-1),
    symbols: new[] { "NVDA" }
);

Performance Considerations

1. Memory Management: Records are copied from native to managed memory. For high-throughput scenarios, consider batching.

2. Threading: Callbacks fire on native threads. The library marshals them to the .NET thread pool via Channel<T>.

3. Backpressure: The Channel<T> is unbounded by default. Consider adding bounds for memory-constrained environments.

4. Disposal: Always use await using to ensure proper resource cleanup.

Troubleshooting

Native Library Not Found

Ensure the native library is built and copied to the output directory:

# Rebuild native library
./build/build-native.ps1

CMake Configuration Fails

Ensure all prerequisites are installed:

# Windows (with chocolatey)
choco install cmake visualstudio2022buildtools

# Linux (Ubuntu/Debian)
sudo apt-get install cmake build-essential libssl-dev libzstd-dev

# macOS (with Homebrew)
brew install cmake openssl zstd

API Authentication Errors

Verify your API key is correct and has the required permissions:

# Test API key
curl -H "Authorization: Bearer your-api-key" https://api.databento.com/v1/metadata.list_datasets

License

Apache 2.0 License. See LICENSE for details.

Resources

• Databento Documentation
• databento-cpp GitHub
• Issue Tracker

Acknowledgments

Built on top of Databento's official C++ client.