Market Data

client.marketdata expõe helpers REST para metadados de instrumento, último trade e busca de papéis. Para atualizações contínuas, veja Streaming.

Definitions

Busca metadados de um ou mais papéis. Útil para descobrir tick size, lot size, moeda, bolsa, etc.

async with AsyncInvestflexClient.from_env() as client:
    defs = await client.marketdata.definitions(["PETR4", "VALE3", "WINQ19"])
    for d in defs:
        print(d.symbol, d.tick_size, d.lot_size, d.exchange)

O resultado é uma lista de Definition:

Campo	Tipo	Observações
symbol	str	Código do instrumento.
security_id	str | None	Id interno.
exchange	str | None	ex.: XBSP, XBMF.
currency	str | None	ex.: BRL.
tick_size	float | None	Incremento mínimo de preço.
lot_size	int | None	Tamanho do lote-padrão.
description	str | None	Nome legível.

Campos desconhecidos / futuros são preservados em model_extra, então backends mais novos não quebram clientes mais antigos.

Último trade

O último negócio impresso para um papel — útil como referência de preço ao dimensionar ou validar ordens.

async with AsyncInvestflexClient.from_env() as client:
    t = await client.marketdata.last_trade("PETR4")
    print(t.symbol, t.price, t.qty, t.timestamp)

Campos de Trade:

Campo	Tipo	Observações
symbol	str
price	float	Preço do último negócio.
qty	int	Quantidade do negócio.
side	Side | None	Lado agressor, quando disponível.
trade_id	str | None	Id do negócio na bolsa.
timestamp	datetime | None	Horário.

Lista de papéis

Pesquisa a lista de papéis da plataforma. Os filtros são enviados como query params; o conjunto exato depende do backend, mas os mais comuns são exchange, query (substring), currency e active.

async with AsyncInvestflexClient.from_env() as client:
    matches = await client.marketdata.security_list(
        exchange="XBSP", query="PETR"
    )
    for d in matches[:10]:
        print(d.symbol, d.description)

A resposta é uma lista de Definition — mesmo formato de definitions().

Livro de ofertas

O livro agregado MBP é entregue por streaming, não REST — veja Streaming para o modelo Book e subscribe_book().

Quando usar REST x streaming

• Helpers REST são point-in-time. Baratos de chamar esporadicamente: preencher um autocomplete, validar um símbolo, mostrar um preço de referência ao lado de um formulário.
• Streams mantêm estado sincronizado. Use-os para dashboards ao vivo, loops de decisão de algos ou para alimentar uma escada de livro na UI.

Para a maioria dos algos só REST basta: a engine lê market data no servidor. O serviço de marketdata é principalmente para lógica no cliente.