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)

const client = InvestflexClient.fromEnv();

const defs = await client.marketdata.definitions(["PETR4", "VALE3", "WINQ19"]);
for (const d of defs) {
  console.log(d.symbol, d.tickSize, d.lotSize, d.exchange);
}

O resultado é uma lista de Definition:

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)

const client = InvestflexClient.fromEnv();

const t = await client.marketdata.lastTrade("PETR4");
console.log(t.symbol, t.price, t.qty, t.timestamp);

Campos de Trade:

Nomes de papéis

symbols() devolve todos os instrumentos do cadastro como strings simples. É a metade leve do cadastro: security_list() devolve as definições completas de tudo que casar com o filtro, o que na B3 são cerca de 150 000 instrumentos em uma única resposta sem paginação, enquanto este devolve só os nomes — que é o que um índice de autocomplete realmente precisa. Hidrate os poucos que você exibe com definitions().

async with AsyncInvestflexClient.from_env() as client:
    names = await client.marketdata.symbols(security_type="EQUITY")
    print(len(names), "papéis")

    shown = [s for s in names if s.startswith("PETR")][:5]
    for d in await client.marketdata.definitions(shown):
        print(d.symbol, d.tick_size, d.description)

const client = InvestflexClient.fromEnv();

const names = await client.marketdata.symbols({ securityType: "EQUITY" });
console.log(names.length, "papéis");

const shown = names.filter((s) => s.startsWith("PETR")).slice(0, 5);
for (const d of await client.marketdata.definitions(shown)) {
  console.log(d.symbol, d.tickSize, d.description);
}

security_type restringe o cadastro a EQUITY, OPT ou FUT; omita para trazer tudo.

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)

const client = InvestflexClient.fromEnv();

const matches = await client.marketdata.securityList({
  exchange: "XBSP",
  query: "PETR",
});
for (const d of matches.slice(0, 10)) {
  console.log(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(). Os books brutos da B3 — agregado (subscribe_mbp / conflacionado subscribe_cmbp) e ordem a ordem (subscribe_mbo) — são servidos pelo broadcaster /mdh; veja Feeds mdhub.

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.