Spread

Estratégia multi-perna passiva que trabalha duas ou mais pernas como uma única unidade, postando e gerenciando cada perna para que o trade combinado só execute no spread desejado.

Quando usar

• Você está operando um par (ou uma cesta pequena) onde só importa o preço relativo.
• Quer estrutura garantida: o algo só executa quando todas as pernas couberem dentro do spread.
• Prefere não ficar "perneado" gerenciando os componentes na mão.

Código de estratégia por número de pernas

O StrategyCode no fio é selecionado automaticamente pelo número de pernas:

Pernas	Código
2	spread
3	spread3p
4	spread4p
5	spread5p
6	spread6p

Use a mesma classe Python Spread em todos os casos — o SDK escolhe o código certo na serialização.

Início rápido

from investflex import AsyncInvestflexClient
from investflex.models.algos import Spread
from investflex.models.common import ExecutionType, Side, Trigger

sp = Spread(
    name="petr4-vale3",
    init_time="09:00:00",
    end_time="17:00:00",
    execution_type=ExecutionType.ENTRY,
    trigger=Trigger.SPREAD,              # também: Trigger.FINANCIAL_DIFF
    trigger_value=30,
    book_depth=1,
    legs=[
        dict(symbol="PETR4", side=Side.BUY,  quantity=100,
             alloc_account="YOUR_ACCOUNT", resting="Y", max_clip_size=100,
             first_timeout=5000),
        dict(symbol="VALE3", side=Side.SELL, quantity=100,
             alloc_account="YOUR_ACCOUNT", resting="N", max_clip_size=100,
             first_timeout=5000),
    ],
)

async with AsyncInvestflexClient.from_env() as client:
    handle = await client.algos.create(sp)
    print(handle.clord_id, handle.status.name)

Parâmetros

Estratégia

Campo	Tipo	Obrigatório	Editável	Padrão	Observações
name	str	sim	não	—	Rótulo.
init_time	HH:MM:SS	sim	não	—	Início da janela.
end_time	HH:MM:SS	sim	não	—	Fim da janela.
expire_date	YYYYMMDD	não	não	20380101	Validade da ordem-dia.
text	str	não	não	—	Comentário livre.
basket_id	str	não	não	—	Chave opcional de agrupamento.
execution_type	ExecutionType	sim	não	—	ExecutionType.ENTRY, ExecutionType.GAIN_LOSS.
trigger	Trigger	sim	não	—	Trigger.SPREAD (diferença de preço), Trigger.FINANCIAL_DIFF.
trigger_value	número	sim	sim	—	Valor de entrada (execution_type=ExecutionType.ENTRY) ou alvo de ganho (execution_type=ExecutionType.GAIN_LOSS). Fracional quando trigger=Trigger.SPREAD, inteiro quando trigger=Trigger.FINANCIAL_DIFF.
to_market_trigger_value	número	condicional	sim	—	Alvo de perda; obrigatório quando execution_type=ExecutionType.GAIN_LOSS.
to_market_trigger_value_enabled	"Y" / "N"	não	não	—	Y apenas quando execution_type=ExecutionType.GAIN_LOSS.
band_price_high	número	não	sim	—	Banda superior de proteção.
band_price_low	número	não	sim	—	Banda inferior de proteção.
ignore_offers_lt	int	não	sim	—	Ignora ofertas contrárias menores que este tamanho.
book_depth	int	não	sim	—	Profundidade (1..N) usada para avaliar o gatilho.

Pernas

Duas a seis pernas. Cada perna é um dict (ou StrategyLeg).

Campo	Tipo	Obrigatório	Editável	Observações
symbol	str	sim	não	Código do instrumento.
side	Side.BUY / Side.SELL	sim	não
quantity	int	sim	sim	Quantidade total (> 0).
alloc_account	str	sim	não	Conta da corretora.
security_exchange	str	não	não	Padrão XBSP.
resting	"Y" / "N"	não	sim	Y posta passivo; N deixa esta perna como agressora.
max_clip_size	int	não	sim	Maior pedaço visível por ordem filha.
first_timeout	int	não	não	Milissegundos até a primeira reavaliação.

Editando um Spread em execução

await client.algos.edit(
    handle.clord_id,
    TriggerValue=29,
    ToMarketTriggerValue=0,
    BandPriceHigh=100,
    BandPriceLow=0,
    IgnoreOffersLT=0,
    BookDepth=1,
)

Comandos de ciclo de vida

await client.algos.commands.cancel(handle.clord_id)
await client.algos.commands.suspend(handle.clord_id)
await client.algos.commands.resume(handle.clord_id)

Notas de comportamento

• Tipicamente exatamente uma perna fica passiva enquanto as outras agridem, mas a engine aceita qualquer combinação — caindo para comportamento "todas agressoras" caso nenhuma esteja configurada como passiva.
• band_price_high/band_price_low limitam os preços absolutos em que o algo pode enviar ordens, independentemente do spread.
• Para spreads de 3 a 6 pernas o mesmo conjunto de parâmetros se aplica; muda apenas o número de pernas.