TWAP — Time-Weighted Average Price

Divide uma ordem em fatias (clips) igualmente espaçadas entre init_time e end_time, de forma que o preço médio de execução acompanhe o preço aritmético ponderado pelo tempo na janela. Limites opcionais permitem dimensionar por volume financeiro ou participar até uma porcentagem do volume negociado.

Quando usar

• Quando você quer baixo impacto de mercado em uma ordem de tamanho moderado.
• Quando você não tem uma visão forte sobre a distribuição intraday do volume (use VWAP se tiver).
• Quando você pode se comprometer com uma janela de tempo fixa.

Início rápido

from investflex import AsyncInvestflexClient
from investflex.models.algos import TWAP
from investflex.models.algos.twap import TWAPLeg
from investflex.models.common import AgressionLevel, OrdType, Side

twap = TWAP(
    name="petr4-buy-1k",
    init_time="10:00:00",
    end_time="11:00:00",
    aggression_level=AgressionLevel.COUNTER_PARTY,  # também: AgressionLevel.OWN_SIDE
    using_financial_volume="N",
    limit_by_volume="N",
    price_limit=36.00,
    legs=[
        TWAPLeg(
            symbol="PETR4",
            side=Side.BUY,
            quantity=1000,
            alloc_account="SUA_CONTA",
            ord_type=OrdType.LIMIT,
            max_clip_size=100,
        )
    ],
)

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

Parâmetros

Estratégia

Campo	Tipo	Obrigatório	Editável	Padrão	Notas
name	str	sim	não	—	Rótulo legível; aparece no fluxo de snapshots.
init_time	HH:MM:SS	sim	não	—	Início da janela de fatiamento.
end_time	HH:MM:SS	sim	não	—	Fim da janela de fatiamento.
expire_date	YYYYMMDD	não	não	20380101	Validade da ordem-dia.
price_limit	número	não	sim	—	Pior preço que você está disposto a atravessar. Obrigatório quando ord_type = LIMIT.
aggression_level	AgressionLevel	sim	sim	—	AgressionLevel.COUNTER_PARTY (atravessa o spread), AgressionLevel.OWN_SIDE (posta no próprio lado).
using_financial_volume	"Y" / "N"	sim	não	"N"	Dimensiona por valor financeiro em vez de quantidade de ações.
max_financial_volume	número	condicional	sim	—	Limite de valor financeiro. Obrigatório quando using_financial_volume = "Y".
limit_by_volume	"Y" / "N"	sim	não	"N"	Limita a participação a uma % do volume negociado.
target_percent	número	condicional	sim	—	Limite de participação (ex.: 10.0 = 10%). Obrigatório quando limit_by_volume = "Y".
consider_cross_orders	"Y" / "N"	não	sim	"N"	Conta negócios diretos (cross) na base de volume.

Perna (Leg)

TWAP roda contra uma única perna.

Campo	Tipo	Obrigatório	Editável	Notas
symbol	str	sim	não	Código do instrumento (ex.: "PETR4").
side	Side.BUY / Side.SELL	sim	não
quantity	int	condicional	sim	Quantidade total. Obrigatório quando using_financial_volume = "N". Deve ser > 0.
alloc_account	str	sim	não	Código da conta na corretora.
ord_type	OrdType.MARKET / OrdType.LIMIT	sim	sim	LIMIT exige price_limit.
max_clip_size	int	sim	sim	Maior tamanho de uma fatia (clip), em ações.

Editando um TWAP em execução

Apenas os campos marcados como editáveis acima podem ser alterados em voo:

await client.algos.edit(
    handle.clord_id,
    PriceLimit=36.50,
    TargetPercent=15.0,
)

A edição retorna imediatamente; os novos valores valem a partir da próxima fatia.

Comandos de ciclo de vida

await client.algos.commands.cancel(handle.clord_id)   # encerra o algo
await client.algos.commands.suspend(handle.clord_id)  # pausa; depois retoma
await client.algos.commands.resume(handle.clord_id)

Notas de comportamento

• As fatias são agendadas uniformemente em [init_time, end_time]. Qualquer saldo não executado em end_time é cancelado.
• max_clip_size limita cada ordem-filha individual; não altera a quantidade total.
• Com limit_by_volume="Y", o algo se autorregula se as execuções acumuladas excederem target_percent do volume negociado. Ele retoma o fatiamento assim que a participação cair abaixo do limite.
• aggression_level=AgressionLevel.OWN_SIDE posta passivamente; espere uma taxa de execução menor, mas melhor captura do spread.
• using_financial_volume="Y" dimensiona por valor financeiro e ignora quantity na perna — defina max_financial_volume em vez.