Algos

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)

import {
  InvestflexClient,
  Spread,
  ExecutionType,
  Side,
  Trigger,
} from "@investflex/sdk";

const sp = new Spread({
  name: "petr4-vale3",
  initTime: "09:00:00",
  endTime: "17:00:00",
  executionType: ExecutionType.ENTRY,
  trigger: Trigger.SPREAD, // também: Trigger.FINANCIAL_DIFF
  triggerValue: 30,
  bookDepth: 1,
  legs: [
    {
      symbol: "PETR4",
      side: Side.BUY,
      quantity: 100,
      allocAccount: "YOUR_ACCOUNT",
      resting: "Y",
      maxClipSize: 100,
      firstTimeout: 5000,
    },
    {
      symbol: "VALE3",
      side: Side.SELL,
      quantity: 100,
      allocAccount: "YOUR_ACCOUNT",
      resting: "N",
      maxClipSize: 100,
      firstTimeout: 5000,
    },
  ],
});

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

await client.close();

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.
`exec_strategy`	`ExecStrategy`	não	não	`ExecStrategy.RESTING` (`2`)	Modo de execução: `AGGRESSIVE` (`1`), `RESTING` (`2`), `MIT` (`5`). TypeScript: `execStrategy`; wire: `ExecStrategy`.
`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).

Os modos RESTING (2, padrão da API) e MIT (5) exigem pelo menos uma perna com resting="Y". AGGRESSIVE (1) não exige Y; o motor seleciona a primeira perna internamente. Para duas pernas no modo agressor, os flags podem ser omitidos. Para 3–6 pernas, todos devem ser explícitos em qualquer modo. exec_strategy é independente de execution_type (entrada ou ganho/perda).

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"`	3–6 pernas	sim	Obrigatório em cada perna de `spread3p`–`spread6p`; opcional para duas pernas. `Y` posta passivo; `N` deixa esta perna como agressora. Sem padrão.
`max_clip_size`	int	sim	sim	Maior pedaço visível por ordem filha (> 0); obrigatório em cada perna, sem padrão.
`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,
)

await client.algos.edit(
  handle.clOrdId,
  {
    TriggerValue: 29,
    ToMarketTriggerValue: 0,
    BandPriceHigh: 100,
    BandPriceLow: 0,
    IgnoreOffersLT: 0,
    BookDepth: 1,
  },
  { strategyCode: "spread" },
);

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

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.