Algos

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)

import { InvestflexClient, GradLinear, SelectStopByPrice, Side } from "@investflex/sdk";

const g = new GradLinear({
  name: "winq-grid",
  initTime: "09:00:00",
  endTime: "17:00:00",
  // grade de entrada
  orderQuantity: 1,
  entrancePrice: 4000.0,
  incrementPriceStepEntrance: 20.0,
  numberOfEntrances: 10,
  incrementPriceStopGain: 20.0,
  numberOfMinPriceIncrementsToStart: 5,
  // start-when-cross
  useStartWhenCross: "N",
  // stop-by-price
  selectStopByPrice1: SelectStopByPrice.MANUAL,
  stopByPrice1: 3000.0,
  // stops financeiros
  stopLossFinance: 100.0,
  useStopGainGlobalFinance: "N",
  sendStopLossOnEnd: "Y",
  // preservação
  usePreservation: "Y",
  preservationStartTrigger: 80.0,
  preservationStep: 10.0,
  preservationPercentual: 20.0,
  // perna (sem quantidade aqui)
  symbol: "WINQ19",
  side: Side.BUY,
  account: "YOUR_ACCOUNT",
});

const client = InvestflexClient.fromEnv();
const handle = await client.algos.create(g);
console.log(handle.clOrdId, handle.status);

await client.close();

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,
)

await client.algos.edit(
  handle.clOrdId,
  {
    EntrancePrice: 5000,
    IncrementPriceStepEntrance: 20,
    NumberOfEntrances: 10,
    OrderQuantity: 1,
    StopLossFinance: 100,
    UseStopGainGlobalFinance: "Y",
    StopGainGlobalFinance: 100,
    PreservationStartTrigger: 80,
    PreservationStep: 10,
    PreservationPercentual: 20,
  },
  { strategyCode: "grdlin" },
);

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)

await client.commands.cancel(handle.clOrdId);
await client.commands.suspend(handle.clOrdId);
await client.commands.resume(handle.clOrdId);

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.