API para desenvolvedores

Construa sobre o TradingNote com a API REST pública /api/v1: contas, operações, algoritmos, backtests, explorações e portfólios em qualquer linguagem, autenticado com sua API key.

O TradingNote expõe uma API REST pública para você construir suas próprias integrações: dashboards, bots, planilhas, alertas ou o que quiser. É o MESMO catálogo de ferramentas que o conector do Claude usa (~125 ferramentas de contas, operações, algoritmos, explorações, backtests, portfólios, métricas e trading), mas em HTTP + JSON puro: funciona em qualquer linguagem, sem depender do Claude.

A API REST e as API keys são exclusivas do plano ELITE desde 3 de outubro de 2026 (os planos TRADER/PRO ativos antes da mudança mantêm o acesso até o próximo corte de cobrança). O conector do Claude (OAuth) é diferente: o teste grátis o inclui exceto operar ao vivo e o PRO tem leitura básica de perfil e contas.

Base URL

text
https://app.tradingnote.co/api/v1
Todas as rotas deste artigo partem daqui.

A especificação OpenAPI 3.1 completa —gerada dos esquemas reais, importável no Postman ou em qualquer gerador de SDK— vive em «/api/v1/openapi.json» e é pública.

Autenticação

  1. 1

    Gere sua API key

    No app: Ajustes → «API para desenvolvedores» → «Gerar nova API Key». Escolha um nome e marque as permissões por categoria que sua integração precisa (todas vêm ativas por padrão).

  2. 2

    Guarde a chave — ela aparece UMA única vez

    A chave tem a forma «tn_…» e não é mostrada de novo (guardamos apenas o hash). Se você a perder, revogue e gere outra.

  3. 3

    Envie em cada requisição e verifique

    Cabeçalho «Authorization: Bearer tn_…». Verifique com GET /me: retorna seu usuário, o tipo de credencial e as permissões ativas da chave.

bash
curl -H "Authorization: Bearer tn_TU_CLAVE" \
  https://app.tradingnote.co/api/v1/me
Primeira chamada recomendada: identidade e permissões da credencial.

A API key é um segredo: use apenas no seu servidor ou scripts, nunca em código rodando no navegador. Você pode revogá-la a qualquer momento em Ajustes e o acesso é cortado na hora. Access tokens OAuth («tnoa_…») emitidos pelo fluxo OAuth do TradingNote também são aceitos.

Como ela é organizada

Cada capacidade é uma «ferramenta» (tool) com nome próprio, e cada ferramenta é um endpoint em /tools/{nome}. Seu ponto de partida é GET /tools: retorna o catálogo VISÍVEL para sua chave —nome, descrição, método HTTP e o esquema exato de entrada de cada uma. O que não aparecer ali é porque sua chave não tem a permissão daquela categoria.

  • Leituras → GET /tools/{nome} com os argumentos como query params. Um GET nunca modifica nada.
  • Mutações → POST /tools/{nome} com os argumentos como body JSON. Um GET em uma ferramenta que muda estado responde 405 com «Allow: POST».
  • No GET, os tipos são convertidos pelo esquema da ferramenta: números e booleanos («true/false/1/0») vão direto; um argumento array ou objeto viaja como JSON url-encodado; uma chave repetida («?symbols=A&symbols=B») chega como array.
  • Toda resposta usa o mesmo envelope: «{ success: true, data: … }» no sucesso e «{ success: false, error: "mensagem acionável" }» na falha.
  • Um parâmetro escrito errado é REJEITADO com sugestão do nome correto («você quis dizer 'accountId'?») em vez de ser ignorado em silêncio — assim um typo nunca faz algo diferente do que você pediu.

Exemplos

bash
KEY="tn_TU_CLAVE"
B="https://app.tradingnote.co/api/v1"

# 1. Descubrir qué puede hacer tu clave
curl -H "Authorization: Bearer $KEY" "$B/tools"

# 2. Lectura simple
curl -H "Authorization: Bearer $KEY" "$B/tools/list_accounts"

# 3. Lectura con parámetros
curl -H "Authorization: Bearer $KEY" "$B/tools/get_account?accountId=42"

# 4. Mutación (body JSON por POST)
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mi portafolio","description":"creado por API"}' \
  "$B/tools/create_portfolio"

Permissões por categoria

Cada chave carrega permissões por categoria, escolhidas ao gerá-la. Sem a permissão, as ferramentas daquela categoria não aparecem no seu catálogo e chamá-las responde 403. Dê a cada integração só o que ela precisa.

CategoriaO que permite
accountsListar, ver e criar contas; estatísticas, equity, saúde e posições abertas.
operationsLer operações fechadas e lançamentos contábeis.
strategiesAlgoritmos: listar, ver, criar, publicar; histórico de trades, curvas de equity, modelos de custos.
strategyDevExplorações (fábrica de algoritmos), robustez post-hoc e o IDE de estratégias.
copyTradingCopy trading: seus masters e assinaturas (modo de risco, lote, multiplicador, limites), histórico de cópias com motivo de rejeição, sinais; pausar/retomar e ajustar o tamanho (o tamanho exige também o interruptor de operar ao vivo). Nunca cria nem apaga masters ou assinaturas.
backtestingSessões de backtesting manual e seu replay (operar com dinheiro simulado sobre velas históricas).
portfoliosPortfólios e sessões live: criar, configurar risco/rotação, iniciar/pausar/parar, logs.
metricsTN Score, saúde de conta/portfólio e alertas de risco.
notesNotas sobre operações.
profilePerfil do usuário e plano efetivo (cotas disponíveis).
tradingTrading manual: abrir, modificar e fechar posições nas suas contas. Tem uma trava extra (veja abaixo).

As ferramentas de trading executam ordens com dinheiro real e têm trava tripla: além da permissão «trading» na chave, exigem plano ELITE E o interruptor «Permitir operar ao vivo» em Ajustes (desligado por padrão). A categoria sozinha nunca executa uma ordem.

Erros e limites

CódigoSignificado
400Argumentos inválidos ou requisição rejeitada (inclui a rejeição de parâmetros errados, com sugestão).
401Credencial ausente, inválida, expirada ou revogada.
402Seu plano não inclui acesso à API (exclusiva do ELITE; o plano é revalidado a cada requisição).
403A chave não tem a permissão daquela categoria, ou falta a trava de trading.
404Ferramenta ou recurso inexistente (consulte GET /tools).
405GET em uma ferramenta que muda estado — use POST (a resposta traz «Allow: POST»).
429Rate limit: 240 requisições/minuto POR credencial. Respeite «Retry-After» e os cabeçalhos «X-RateLimit-*».
500Erro interno. Se persistir, fale conosco com o horário e a rota.

Gere um cliente tipado (SDK)

Como o spec OpenAPI é público e gerado dos esquemas reais, qualquer gerador padrão te dá um cliente tipado na sua linguagem. Você também pode importá-lo direto no Postman ou Insomnia e explorar a API com autocompletar.

bash
# Descargar el spec
curl -s https://app.tradingnote.co/api/v1/openapi.json > tn-openapi.json

# Ejemplo: cliente TypeScript con openapi-typescript
npx openapi-typescript tn-openapi.json -o tradingnote-api.d.ts

# Ejemplo: cliente Python con openapi-python-client
pipx run openapi-python-client generate --path tn-openapi.json

Boas práticas

  • Uma chave por integração, com as permissões mínimas. Assim você revoga uma sem derrubar as outras.
  • Guarde a chave em variável de ambiente ou gerenciador de segredos, nunca no código nem no repositório.
  • Diante de um 429, espere o que «Retry-After» disser antes de tentar de novo — insistir só alonga o bloqueio.
  • Faça cache das leituras que não mudam a cada segundo (catálogos, históricos) do seu lado: sua cota de 240/min rende muito mais.

O que a API não pode fazer

  • Modificar o saldo de uma conta nem as operações fechadas.
  • Executar ordens sem o plano ELITE e sem o interruptor de trading ativado em Ajustes.
  • Alterar sua senha ou email, nem acessar funções de administração.

Prefere linguagem natural em vez de código? O mesmo catálogo está disponível como conector do Claude via OAuth, sem chaves manuais — veja o artigo «Conectar o Claude ao TradingNote» desta mesma wiki.