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 Python suporta Python 3.10+.

Para Node.js, instale o SDK TypeScript:

npm install @investflex/sdk

Ele exige Node 20+ e publica builds ESM e CommonJS.

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

import { InvestflexClient } from "@investflex/sdk";

const client = await InvestflexClient.login({
  username: "your-user",
  password: "your-password",
  baseUrl: "https://api.investflex.example",
});

const snaps = await client.algos.list();
console.log(snaps.length, "running algos");

await client.close();

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:
    ...

import { InvestflexClient } from "@investflex/sdk";

const client = InvestflexClient.fromToken("eyJhbGciOi...", {
  baseUrl: "https://api.investflex.example",
});

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:
    ...

import { InvestflexClient } from "@investflex/sdk";

const client = InvestflexClient.fromEnv();

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, Feeds mdhub

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

import { InvestflexClient, OrdType, SecurityExchange, Side } from "@investflex/sdk";

const client = InvestflexClient.fromEnv();

const ack = await client.orders.create({
  symbol: "PETR4",
  side: Side.BUY,
  qtty: 100,
  ordType: OrdType.LIMIT,
  price: 20.0,
  account: "YOUR_ACCOUNT",
  exchange: SecurityExchange.XBSP,
  name: "hello-investflex",
});
console.log("created:", ack.orderId);

// Cancele em seguida — isto foi apenas um teste de fumaça.
if (ack.orderId) await client.orders.cancel(ack.orderId);

await client.close();

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

  • Aprenda as estratégias: Estratégias.
  • Leia o estado ao vivo: Snapshots.
  • Assine eventos em tempo real: Streaming.