InvestflexInvestflexSDK
Getting Started

Getting Started

Esta página guia você pela instalação do SDK, configuração e autenticação na plataforma Investflex.

Instalação

pip install investflex-py

O SDK suporta Python 3.10+.

Configuração

AsyncInvestflexClient lê sua base URL e token de algumas fontes, em ordem de prioridade:

  1. Argumentos explícitos no factory (from_token(token, base_url=...)).
  2. Uma instância ClientConfig que você mesmo constrói.
  3. Variáveis de ambiente (INVESTFLEX_TOKEN, INVESTFLEX_BASE_URL).

Para a maioria dos usuários from_env() ou login() é suficiente — veja abaixo.

Opções de login

Há três formas de autenticar, dependendo de onde você roda o SDK.

1. Usuário + senha

A opção mais direta: o SDK chama o endpoint de login da plataforma e guarda o bearer token retornado em memória durante o ciclo de vida do cliente.

import asyncio
from investflex import AsyncInvestflexClient

async def main() -> None:
    client = await AsyncInvestflexClient.login(
        username="seu-usuario",
        password="sua-senha",
        base_url="https://api.investflex.example",
    )
    async with client:
        snaps = await client.algos.list()
        print(len(snaps), "algos rodando")

asyncio.run(main())

2. Bring-your-own token

Se você já tem um JWT (porque logou em outro lugar, ou tem um token de integração de longa duração), passe direto:

from investflex import AsyncInvestflexClient

async with AsyncInvestflexClient.from_token(
    token="eyJhbGciOi…",
    base_url="https://api.investflex.example",
) as client:
    ...

3. A partir de variáveis de ambiente

Quando o SDK roda em um sandbox gerenciado (CI, o playground web, um notebook com segredos injetados), use from_env. Ele lê:

  • INVESTFLEX_TOKEN — bearer token (obrigatório)
  • INVESTFLEX_BASE_URL — URL base da API (opcional; usa a URL padrão da plataforma se ausente)
from investflex import AsyncInvestflexClient

async with AsyncInvestflexClient.from_env() as client:
    ...

O cliente

Uma vez autenticado, o cliente expõe os serviços abaixo:

Atributo O que faz Veja
client.algos Submit, edit, list, get, stream de snapshots. Estratégias, Snapshots, Streaming
client.orders API direta de ordens: create, replace, cancel, get, list, filter. Amostra Orders API
client.commands Comandos de ciclo de vida: cancel, suspend, resume. Estratégias
client.marketdata Market data REST + streaming. Market Data, Streaming

Primeiro round-trip

Envie uma ordem limit simples pela API direta de ordens para confirmar que tudo funciona. Use esse caminho sempre que quiser uma ordem isolada — é mais simples e mais performante que envelopar uma ordem única em uma estratégia algorítmica.

import asyncio
from investflex import AsyncInvestflexClient
from investflex.models.common import OrdType, SecurityExchange, Side

async def main() -> None:
    async with AsyncInvestflexClient.from_env() as client:
        ack = await client.orders.create(
            symbol="PETR4",
            side=Side.BUY,
            qtty=100,
            ord_type=OrdType.LIMIT,
            price=20.00,
            account="YOUR_ACCOUNT",
            exchange=SecurityExchange.XBSP,
            name="hello-investflex",
        )
        print("criada:", ack.order_id)

        # Cancela em seguida — foi só um smoke test.
        await client.orders.cancel(ack.order_id)

asyncio.run(main())

Se você viu um ClOrdID impresso e nenhuma exceção, está pronto.

Tratamento de erros

O SDK levanta exceções tipadas em investflex.errors:

  • AuthError — login falhou ou token foi rejeitado.
  • TransportError — erros de rede / 5xx.
  • ValidationError — sua estratégia ou edit é inválida (levantada antes da requisição sair do cliente).
  • ApiError — a plataforma rejeitou a requisição (ex.: firewall, conta inválida).

Envolva chamadas em try/except quando precisa tratar falhas específicas.

Próximos passos