Add raw crypto trades endpoint with Binance provider

[parthdongre]

Summary

This PR adds raw crypto trade support to the OpenBB crypto price extension through a new exchange-neutral CryptoTrades standard model and an initial provider implementation for Binance Spot public market data.

It introduces a new crypto.price.trades(...) command that is intended to return recent execution-level crypto trades, starting with Binance as the first provider.

The Binance implementation is not limited to Bitcoin. It supports any valid Binance Spot trading pair, such as:

• BTCUSDT
• ETHUSDT
• SOLUSDT
• BNBUSDT
• DOGEUSDT
• ETHBTC
• BNB/BTC
• ETH/USDT
• SOL-USDT

The symbol is normalized before making the request, so common formats like BTC/USDT and BTC-USDT are converted into Binance's expected format, BTCUSDT.

What Changed

This PR adds:

• A new CryptoTrades standard model.

• A new crypto.price.trades(...) router command under the crypto price extension.

• A new openbb-binance provider package.

• A Binance recent trades fetcher using Binance Spot public recent trades data.

• Support for any valid Binance Spot trading pair.

• Symbol normalization support for common formats:

  • BTCUSDT
  • BTC/USDT
  • BTC-USDT
  • ETH/USDT
  • SOL-USDT
  • BNB/BTC

• Trade-side conversion from Binance's isBuyerMaker field into an aggressor-side value:

  • buy
  • sell

• Unit tests for:

  • symbol normalization
  • trade-side conversion
  • query transformation
  • data transformation
  • limit validation

• README documentation for the new Binance provider.

Motivation

OpenBB already supports crypto historical price data, but raw execution-level trade data is useful for more detailed market analysis.

Historical OHLCV candles show aggregated price movement over time, while raw trades show the individual executions that create those candles. This gives users access to a more granular market-data layer.

Recent raw trades provide a foundation for future crypto market data features such as:

• latest execution price
• short-term traded volume
• quote volume
• recent high and low
• VWAP from trades
• trade count
• buy/sell aggressor analysis
• microstructure and order-flow analytics
• multi-exchange crypto trade comparisons

This PR keeps the first implementation intentionally focused by adding the standard model, route, and one public provider implementation.

New Command

from openbb import obb

trades = obb.crypto.price.trades(
    symbol="BTCUSDT",
    provider="binance",
    limit=100,
)

Other valid Binance Spot pairs can also be requested:

from openbb import obb

eth_trades = obb.crypto.price.trades(
    symbol="ETHUSDT",
    provider="binance",
    limit=100,
)

sol_trades = obb.crypto.price.trades(
    symbol="SOL/USDT",
    provider="binance",
    limit=100,
)

bnb_btc_trades = obb.crypto.price.trades(
    symbol="BNB-BTC",
    provider="binance",
    limit=100,
)

New Standard Model

This PR adds a new CryptoTrades standard model with the following fields:

symbol: str
exchange: str | None
trade_id: int | str
price: float
quantity: float
quote_quantity: float | None
timestamp: datetime
side: Literal["buy", "sell"] | None

The model is intended to be exchange-neutral so additional providers can implement the same interface later.

Binance Provider Behavior

The Binance implementation uses Binance Spot public recent trades data.

The fetcher:

1. Accepts a symbol and limit.
2. Normalizes the symbol into Binance format.
3. Requests recent trades from Binance.
4. Converts numeric string fields into floats.
5. Converts Binance millisecond timestamps into UTC datetimes.
6. Converts isBuyerMaker into an aggressor-side value.

Symbol normalization examples:

BTCUSDT  -> BTCUSDT
BTC/USDT -> BTCUSDT
BTC-USDT -> BTCUSDT
ETH/USDT -> ETHUSDT
SOL-USDT -> SOLUSDT
BNB/BTC  -> BNBBTC

Trade-side conversion:

isBuyerMaker=True  -> side="sell"
isBuyerMaker=False -> side="buy"

Reasoning:

• If isBuyerMaker=True, the buyer was the maker, so the seller was the taker/aggressor.
• If isBuyerMaker=False, the buyer was the taker/aggressor.

Example Output

A live fetcher test returned transformed rows like:

symbol='BTCUSDT' exchange='binance' trade_id=6433972103 price=62481.4 quantity=0.00042 quote_quantity=26.242188 timestamp=datetime.datetime(2026, 6, 23, 9, 34, 54, 240000, tzinfo=datetime.timezone.utc) side='buy'

symbol='BTCUSDT' exchange='binance' trade_id=6433972104 price=62481.39 quantity=0.00418 quote_quantity=261.1722102 timestamp=datetime.datetime(2026, 6, 23, 9, 34, 54, 346000, tzinfo=datetime.timezone.utc) side='sell'

Example Use Cases

This endpoint can be used to retrieve execution-level trade data for:

• Recent BTC/USDT trades.
• Recent ETH/USDT trades.
• Recent SOL/USDT trades.
• Base/quote pairs like BNB/BTC.
• Building trade-derived metrics such as latest price, recent volume, quote volume, VWAP, and trade count.
• Comparing future exchange implementations through a shared standard model.

Example pair requests:

from openbb import obb

btc = obb.crypto.price.trades(
    symbol="BTCUSDT",
    provider="binance",
    limit=50,
)

eth = obb.crypto.price.trades(
    symbol="ETH/USDT",
    provider="binance",
    limit=50,
)

sol = obb.crypto.price.trades(
    symbol="SOL-USDT",
    provider="binance",
    limit=50,
)

bnb_btc = obb.crypto.price.trades(
    symbol="BNB/BTC",
    provider="binance",
    limit=50,
)

Testing

Unit Tests

PYTHONPATH="$PWD/openbb_platform/core:$PWD/openbb_platform/providers/binance" \
python -m pytest openbb_platform/providers/binance/tests -q

Result:

5 passed in 0.26s

Syntax Checks

python -m py_compile \
openbb_platform/core/openbb_core/provider/standard_models/crypto_trades.py \
openbb_platform/extensions/crypto/openbb_crypto/price/price_router.py \
openbb_platform/providers/binance/openbb_binance/__init__.py \
openbb_platform/providers/binance/openbb_binance/models/crypto_trades.py \
openbb_platform/providers/binance/openbb_binance/utils/helpers.py \
openbb_platform/providers/binance/tests/test_binance_fetchers.py

Live Fetcher Test

PYTHONPATH="$PWD/openbb_platform/core:$PWD/openbb_platform/providers/binance" python - <<'PY'
import asyncio
from openbb_binance.models.crypto_trades import BinanceCryptoTradesFetcher

async def main():
    query = BinanceCryptoTradesFetcher.transform_query(
        {"symbol": "BTCUSDT", "limit": 2}
    )
    raw = await BinanceCryptoTradesFetcher.aextract_data(query, credentials=None)
    transformed = BinanceCryptoTradesFetcher.transform_data(query, raw)
    for row in transformed:
        print(row)

asyncio.run(main())
PY

Result:

Returned two live BTCUSDT trade rows from Binance and transformed them into BinanceCryptoTradesData.

Example transformed output:

symbol='BTCUSDT' exchange='binance' trade_id=6433972103 price=62481.4 quantity=0.00042 quote_quantity=26.242188 timestamp=datetime.datetime(2026, 6, 23, 9, 34, 54, 240000, tzinfo=datetime.timezone.utc) side='buy'

symbol='BTCUSDT' exchange='binance' trade_id=6433972104 price=62481.39 quantity=0.00418 quote_quantity=261.1722102 timestamp=datetime.datetime(2026, 6, 23, 9, 34, 54, 346000, tzinfo=datetime.timezone.utc) side='sell'

Test Cases Covered

The included test file covers:

Symbol Normalization

BTCUSDT  -> BTCUSDT
BTC/USDT -> BTCUSDT
BTC-USDT -> BTCUSDT

Side Conversion

isBuyerMaker=True  -> sell
isBuyerMaker=False -> buy
isBuyerMaker=None  -> None

Query Transformation

Example input:

{"symbol": "BTC/USDT", "limit": 100}

Expected transformed query:

symbol="BTCUSDT"
limit=100

Data Transformation

The tests verify that Binance raw trade payloads are transformed into OpenBB model data with:

• normalized symbol
• exchange name
• provider trade ID
• float price
• float base quantity
• float quote quantity
• UTC timestamp
• mapped aggressor side

Limit Validation

The standard query validation enforces Binance's supported limit range.

Example invalid input:

{"symbol": "BTCUSDT", "limit": 1001}

Expected behavior:

raises ValueError

Files Added / Modified

Added:

• openbb_platform/core/openbb_core/provider/standard_models/crypto_trades.py
• openbb_platform/providers/binance/README.md
• openbb_platform/providers/binance/pyproject.toml
• openbb_platform/providers/binance/openbb_binance/__init__.py
• openbb_platform/providers/binance/openbb_binance/models/__init__.py
• openbb_platform/providers/binance/openbb_binance/models/crypto_trades.py
• openbb_platform/providers/binance/openbb_binance/utils/__init__.py
• openbb_platform/providers/binance/openbb_binance/utils/helpers.py
• openbb_platform/providers/binance/tests/test_binance_fetchers.py

Modified:

• openbb_platform/extensions/crypto/openbb_crypto/price/price_router.py

Notes

This PR uses Binance public market data and does not require credentials.

The current implementation depends on Binance Spot symbols being valid. If a symbol does not exist on Binance Spot, the provider will return a Binance API error.

The live fetcher test was run against BTCUSDT, while the implementation is symbol-generic and works for any valid Binance Spot pair accepted by Binance's public recent trades endpoint.

This PR does not claim that the full installed obb.crypto.price.trades(...) command was tested end-to-end. The testing performed includes unit tests, syntax checks, and a live fetcher-level Binance API test.

Follow-Up Work

Possible follow-up PRs can build on this standard model by adding:

• Coinbase support for CryptoTrades.

• Kraken support for CryptoTrades.

• Additional exchange providers using the same standard model.

• Trade-derived summary metrics such as:

  • latest price
  • VWAP
  • recent volume
  • quote volume
  • high
  • low
  • trade count

• A higher-level trade summary endpoint built from raw trades.

• More detailed provider-level tests with mocked HTTP responses.

• Additional live examples for other pairs such as ETHUSDT, SOLUSDT, and BNBBTC.

[CLAassistant]

All committers have signed the CLA.