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
https://app.tradingnote.co/api/v1A 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
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
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
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.
curl -H "Authorization: Bearer tn_TU_CLAVE" \
https://app.tradingnote.co/api/v1/meA 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
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"const BASE = "https://app.tradingnote.co/api/v1"
const KEY = process.env.TN_API_KEY // nunca hardcodees la clave
async function tn(path, { method = "GET", body } = {}) {
const res = await fetch(BASE + path, {
method,
headers: {
Authorization: `Bearer ${KEY}`,
...(body ? { "Content-Type": "application/json" } : {}),
},
body: body ? JSON.stringify(body) : undefined,
})
const json = await res.json()
if (!json.success) throw new Error(`${res.status}: ${json.error}`)
return json.data
}
// Lecturas
const cuentas = await tn("/tools/list_accounts")
const cuenta = await tn("/tools/get_account?accountId=42")
// Mutación
const portafolio = await tn("/tools/create_portfolio", {
method: "POST",
body: { name: "Mi portafolio" },
})import os, requests
BASE = "https://app.tradingnote.co/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['TN_API_KEY']}"
def tn(path, method="GET", body=None):
r = S.request(method, BASE + path, json=body)
data = r.json()
if not data.get("success"):
raise RuntimeError(f"{r.status_code}: {data.get('error')}")
return data["data"]
# Lecturas
cuentas = tn("/tools/list_accounts")
cuenta = tn("/tools/get_account?accountId=42")
# Mutación
portafolio = tn("/tools/create_portfolio", "POST", {"name": "Mi portafolio"})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.
| Categoria | O que permite |
|---|---|
| accounts | Listar, ver e criar contas; estatísticas, equity, saúde e posições abertas. |
| operations | Ler operações fechadas e lançamentos contábeis. |
| strategies | Algoritmos: listar, ver, criar, publicar; histórico de trades, curvas de equity, modelos de custos. |
| strategyDev | Explorações (fábrica de algoritmos), robustez post-hoc e o IDE de estratégias. |
| copyTrading | Copy 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. |
| backtesting | Sessões de backtesting manual e seu replay (operar com dinheiro simulado sobre velas históricas). |
| portfolios | Portfólios e sessões live: criar, configurar risco/rotação, iniciar/pausar/parar, logs. |
| metrics | TN Score, saúde de conta/portfólio e alertas de risco. |
| notes | Notas sobre operações. |
| profile | Perfil do usuário e plano efetivo (cotas disponíveis). |
| trading | Trading 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ódigo | Significado |
|---|---|
| 400 | Argumentos inválidos ou requisição rejeitada (inclui a rejeição de parâmetros errados, com sugestão). |
| 401 | Credencial ausente, inválida, expirada ou revogada. |
| 402 | Seu plano não inclui acesso à API (exclusiva do ELITE; o plano é revalidado a cada requisição). |
| 403 | A chave não tem a permissão daquela categoria, ou falta a trava de trading. |
| 404 | Ferramenta ou recurso inexistente (consulte GET /tools). |
| 405 | GET em uma ferramenta que muda estado — use POST (a resposta traz «Allow: POST»). |
| 429 | Rate limit: 240 requisições/minuto POR credencial. Respeite «Retry-After» e os cabeçalhos «X-RateLimit-*». |
| 500 | Erro 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.
# 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.jsonBoas 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.