Algos

Long & Short

Combina uma perna comprada com uma perna vendida em uma única estrutura gerenciada: o algo executa as duas pernas juntas, de modo que a posição resultante tenha a exposição de par desejada.

Quando usar

Você está operando um par long/short, em que a tese é o spread entre dois ativos.
Quer exposição direcional neutra ou quase-neutra.
Precisa de execuções sincronizadas para evitar ficar "perneado".

Início rápido

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

ls = LongShort(
    name="petr4-petr3",
    init_time="09:00:00",
    end_time="17:00:00",
    trigger=Trigger.BUY_SELL_RATIO,
    execution_type=ExecutionType.ENTRY,
    trigger_value=1.08,
    book_depth=1,
    legs=[
        dict(symbol="PETR4", side=Side.BUY,  quantity=100_000,
             alloc_account="YOUR_ACCOUNT", resting="Y", max_clip_size=100),
        dict(symbol="PETR3", side=Side.SELL, quantity=100_000,
             alloc_account="YOUR_ACCOUNT", resting="Y", max_clip_size=100),
    ],
)

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

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

const ls = new LongShort({
  name: "petr4-petr3",
  initTime: "09:00:00",
  endTime: "17:00:00",
  trigger: Trigger.BUY_SELL_RATIO,
  executionType: ExecutionType.ENTRY,
  triggerValue: 1.08,
  bookDepth: 1,
  legs: [
    {
      symbol: "PETR4",
      side: Side.BUY,
      quantity: 100_000,
      allocAccount: "YOUR_ACCOUNT",
      resting: "Y",
      maxClipSize: 100,
    },
    {
      symbol: "PETR3",
      side: Side.SELL,
      quantity: 100_000,
      allocAccount: "YOUR_ACCOUNT",
      resting: "Y",
      maxClipSize: 100,
    },
  ],
});

const client = InvestflexClient.fromEnv();
const handle = await client.algos.create(ls);
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.
`trigger`	`Trigger`	sim	não	—	`Trigger.BUY_SELL_RATIO`, `Trigger.SELL_BUY_RATIO`, `Trigger.BUY_SELL_SPREAD_DIFF`, `Trigger.SELL_BUY_SPREAD_DIFF`, `Trigger.FINANCIAL_DIFF`.
`execution_type`	`ExecutionType`	sim	não	—	`ExecutionType.ENTRY`, `ExecutionType.GAIN_LOSS`.
`trigger_value`	número	sim	sim	—	Valor de entrada (`execution_type=ExecutionType.ENTRY`) ou alvo de ganho (`execution_type=ExecutionType.GAIN_LOSS`).
`to_market_trigger_value`	número	condicional	sim	—	Alvo de perda; obrigatório quando `execution_type=ExecutionType.GAIN_LOSS`.
`book_depth`	int	não	sim	—	Nível de profundidade (1..N) usado para avaliar o gatilho.
`ignore_offers_lt`	int	não	sim	—	Ignora ofertas contrárias menores que este tamanho.
`service_group`	str	não	não	—	Interno — roteamento do controlador.

Pernas

Exatamente duas pernas. Cada perna é um dict (ou LongShortLeg).

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	Uma BUY + uma SELL.
`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 nesta perna; `N` faz dela a perna 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 Long & Short em execução

await client.algos.edit(
    handle.clord_id,
    TriggerValue=1.10,
    ToMarketTriggerValue=0.55,
    BookDepth=2,
    IgnoreOffersLT=100,
)

await client.algos.edit(
  handle.clOrdId,
  {
    TriggerValue: 1.1,
    ToMarketTriggerValue: 0.55,
    BookDepth: 2,
    IgnoreOffersLT: 100,
  },
  { strategyCode: "lgshort" },
);

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

Uma perna fica passiva, a outra agride. A agressora só dispara quando a condição do gatilho é atendida e a perna passiva já executou o suficiente para manter a estrutura balanceada.
book_depth permite avaliar o gatilho contra liquidez mais profunda, não apenas o toque.
Use execution_type=ExecutionType.GAIN_LOSS apenas quando existir uma posição Long & Short aberta — trigger_value passa a ser o alvo de ganho e to_market_trigger_value o alvo de perda.