Gradiente Linear

Estratégia de grade de uma perna. Posta number_of_entrances ordens de entrada começando em entrance_price e avançando por increment_price_step_entrance. Cada entrada executada encadeia uma ordem de stop-gain a increment_price_stop_gain ticks além da entrada.

Quando usar

• Você quer entrar ou sair de uma posição em diferentes níveis de preço.
• Tem uma visão sobre uma faixa de preço, mas não um ponto exato de entrada.
• Prefere comportamento de reversão à média a um único fill.

Início rápido

from investflex import AsyncInvestflexClient
from investflex.models.algos import GradLinear
from investflex.models.common import SelectStopByPrice, Side

g = GradLinear(
    name="winq-grid",
    init_time="09:00:00",
    end_time="17:00:00",
    # grade de entrada
    order_quantity=1,
    entrance_price=4000.0,
    increment_price_step_entrance=20.0,
    number_of_entrances=10,
    increment_price_stop_gain=20.0,
    number_of_min_price_increments_to_start=5,
    # start-when-cross
    use_start_when_cross="N",
    # stop-by-price
    select_stop_by_price1=SelectStopByPrice.MANUAL,
    stop_by_price1=3000.0,
    # stops financeiros
    stop_loss_finance=100.0,
    use_stop_gain_global_finance="N",
    send_stop_loss_on_end="Y",
    # preservação
    use_preservation="Y",
    preservation_start_trigger=80.0,
    preservation_step=10.0,
    preservation_percentual=20.0,
    # perna (sem quantidade aqui)
    symbol="WINQ19",
    side=Side.BUY,
    account="YOUR_ACCOUNT",
)

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

Parâmetros

Estratégia — grade de entrada

Campo	Tipo	Obrigatório	Editável	Observações
order_quantity	int	sim	sim	Quantidade por ordem de entrada.
entrance_price	número	sim	sim	Preço da primeira entrada.
increment_price_step_entrance	número	sim	sim	Passo em ticks entre entradas consecutivas.
number_of_entrances	int	sim	sim	Quantas entradas a grade posta.
increment_price_stop_gain	número	sim	sim	Distância em ticks da entrada ao seu stop-gain.
number_of_min_price_increments_to_start	int	não	não	Ticks de confirmação antes de armar a grade.

Estratégia — gatilho start-when-cross

Campo	Tipo	Obrigatório	Editável	Observações
use_start_when_cross	"Y" / "N"	não	não	Esperar start_when_cross ser tocado antes de armar.
start_when_cross	número	condicional	sim	Preço-gatilho; obrigatório quando use_start_when_cross="Y".

Estratégia — níveis stop-by-price

Dois níveis independentes que desligam a grade ao serem tocados.

Campo	Tipo	Obrigatório	Editável	Observações
select_stop_by_price1	SelectStopByPrice	não	não	SelectStopByPrice.DISABLED, SelectStopByPrice.MANUAL (para no cruzamento para cima), SelectStopByPrice.AUTOMATIC (para no cruzamento para baixo).
stop_by_price1	número	condicional	sim	Preço para o nível 1.
select_stop_by_price2	SelectStopByPrice	não	não	Mesmos modos, para o nível 2.
stop_by_price2	número	condicional	sim	Preço para o nível 2.

Estratégia — stops financeiros

Campo	Tipo	Obrigatório	Editável	Observações
stop_loss_finance	número	não	sim	Limite de perda em BRL.
use_stop_gain_global_finance	"Y" / "N"	não	sim	Habilita stop-gain global.
stop_gain_global_finance	número	condicional	sim	Alvo de ganho em BRL quando habilitado.
send_stop_loss_on_end	"Y" / "N"	não	sim	Enviar stop-loss ao final da janela.

Estratégia — preservação (lock-in de ganhos)

Campo	Tipo	Obrigatório	Editável	Observações
use_preservation	"Y" / "N"	não	não	Habilita preservação dinâmica.
preservation_start_trigger	número	condicional	sim	Lucro em BRL a partir do qual a preservação arma.
preservation_step	número	condicional	sim	Passo em BRL entre reavaliações.
preservation_percentual	número	condicional	sim	% do lucro a preservar.

Perna

Perna única, passada de forma plana. quantity não é usado aqui — o tamanho por entrada é order_quantity na estratégia.

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
account	str	sim	não	Conta da corretora.
security_exchange	str	não	não	Padrão XBSP.

Editando um Gradiente Linear em execução

await client.algos.edit(
    handle.clord_id,
    EntrancePrice=5000,
    IncrementPriceStepEntrance=20,
    NumberOfEntrances=10,
    OrderQuantity=1,
    StopLossFinance=100,
    UseStopGainGlobalFinance="Y",
    StopGainGlobalFinance=100,
    PreservationStartTrigger=80,
    PreservationStep=10,
    PreservationPercentual=20,
)

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

• A grade é estática: os preços são calculados uma única vez a partir de entrance_price e nunca são recentrados. Use GradDynamic se quiser uma grade que acompanha o mercado.
• Cada entrada executada recebe imediatamente uma ordem pareada de stop-gain em entrance + increment_price_stop_gain ticks (o sinal depende do side).
• select_stop_by_price1/2 oferecem dois gatilhos independentes para parar a grade — úteis para níveis globais de suporte/resistência.
• A preservação só entra em ação quando preservation_start_trigger BRL de lucro acumulado é atingido; a partir daí o algo desloca o stop protetor em incrementos de preservation_step, travando preservation_percentual do ganho realizado.