API para desarrolladores
Construye sobre TradingNote con la API REST pública /api/v1: cuentas, operaciones, algoritmos, backtests, exploraciones y portafolios desde cualquier lenguaje, autenticado con tu API key.
TradingNote expone una API REST pública para que construyas tus propias integraciones: dashboards, bots, hojas de cálculo, alertas o lo que quieras. Es el MISMO catálogo de herramientas que usa el conector de Claude (~125 herramientas de cuentas, operaciones, algoritmos, exploraciones, backtests, portafolios, métricas y trading), pero en HTTP + JSON plano: funciona desde cualquier lenguaje, sin depender de Claude.
La API REST y las API keys son exclusivas del plan ELITE desde el 3 de octubre de 2026 (los planes TRADER/PRO activos antes del cambio conservan el acceso hasta su siguiente corte de facturación). El conector de Claude (OAuth) es distinto: la prueba gratis lo incluye salvo operar en vivo y PRO tiene lectura básica de perfil y cuentas.
Base URL
https://app.tradingnote.co/api/v1La especificación OpenAPI 3.1 completa —generada de los esquemas reales, importable en Postman o en cualquier generador de SDK— vive en «/api/v1/openapi.json» y es pública.
Autenticación
- 1
Genera tu API key
En la app: Ajustes → «API para desarrolladores» → «Generar nueva API Key». Elige un nombre y marca los permisos por categoría que necesite tu integración (por defecto vienen todos).
- 2
Guarda la clave — se muestra UNA sola vez
La clave tiene la forma «tn_…» y no vuelve a mostrarse (solo guardamos su hash). Si la pierdes, revócala y genera otra.
- 3
Envíala en cada petición y verifica
Cabecera «Authorization: Bearer tn_…». Verifica con GET /me: devuelve tu usuario, el tipo de credencial y los permisos activos de la clave.
curl -H "Authorization: Bearer tn_TU_CLAVE" \
https://app.tradingnote.co/api/v1/meLa API key es un secreto: úsala solo desde tu servidor o scripts, nunca en código que corra en el navegador. Puedes revocarla en cualquier momento desde Ajustes y el acceso se corta al instante. También se aceptan access tokens OAuth («tnoa_…») emitidos por el flujo OAuth de TradingNote.
Cómo está organizada
Cada capacidad es una «herramienta» (tool) con nombre propio, y cada herramienta es un endpoint bajo /tools/{nombre}. Tu punto de partida es GET /tools: devuelve el catálogo VISIBLE para tu clave —nombre, descripción, método HTTP y el esquema exacto de entrada de cada una—. Lo que no aparece ahí es porque tu clave no tiene el permiso de esa categoría.
- Lecturas → GET /tools/{nombre} con los argumentos como query params. Un GET jamás modifica nada.
- Mutaciones → POST /tools/{nombre} con los argumentos como body JSON. Hacer GET a una herramienta que modifica estado responde 405 con «Allow: POST».
- En GET, los tipos se convierten según el esquema de la herramienta: números y booleanos («true/false/1/0») van tal cual; un argumento array u objeto viaja como JSON url-encodeado; una clave repetida («?symbols=A&symbols=B») llega como array.
- Toda respuesta usa el mismo sobre: «{ success: true, data: … }» en éxito y «{ success: false, error: "mensaje accionable" }» en fallo.
- Un parámetro mal escrito se RECHAZA con sugerencia del nombre correcto («¿querías 'accountId'?») en vez de ignorarse en silencio — así un typo nunca hace algo distinto de lo que pediste.
Ejemplos
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"})Permisos por categoría
Cada clave lleva permisos por categoría, elegidos al generarla. Sin el permiso, las herramientas de esa categoría no aparecen en tu catálogo y llamarlas responde 403. Dale a cada integración solo lo que necesita.
| Categoría | Qué permite |
|---|---|
| accounts | Listar, ver y crear cuentas; estadísticas, equity, salud y posiciones abiertas. |
| operations | Leer operaciones cerradas y asientos de contabilidad. |
| strategies | Algoritmos: listar, ver, crear, desplegar; historial de trades, curvas de equity, plantillas de costos. |
| strategyDev | Exploraciones (fábrica de algoritmos), robustez post-hoc y el IDE de estrategias. |
| copyTrading | Copy trading: tus masters y suscripciones (modo de riesgo, lote, multiplicador, límites), historial de copias con motivo de rechazo, señales; pausar/reanudar y ajustar el tamaño (el tamaño exige además el interruptor de operar en vivo). No crea ni borra masters ni suscripciones. |
| backtesting | Sesiones de backtesting manual y su replay (operar con dinero simulado sobre velas históricas). |
| portfolios | Portafolios y sesiones live: crear, configurar riesgo/rotación, iniciar/pausar/detener, logs. |
| metrics | TN Score, salud de cuenta/portafolio y alertas de riesgo. |
| notes | Notas sobre operaciones. |
| profile | Perfil del usuario y plan efectivo (cupos disponibles). |
| trading | Trading manual: abrir, modificar y cerrar posiciones en tus cuentas. Tiene un candado extra (ver abajo). |
Las herramientas de trading ejecutan órdenes con dinero real y tienen triple candado: además del permiso «trading» en la clave, exigen plan ELITE Y el interruptor «Permitir operar en vivo» en Ajustes (apagado por defecto). La categoría sola nunca ejecuta una orden.
Errores y límites
| Código | Significado |
|---|---|
| 400 | Argumentos inválidos o petición rechazada (incluye el rechazo de parámetros mal escritos, con sugerencia). |
| 401 | Credencial ausente, inválida, expirada o revocada. |
| 402 | Tu plan no incluye acceso a la API (exclusiva de ELITE; el plan se revalida en cada petición). |
| 403 | La clave no tiene el permiso de esa categoría, o falta el candado de trading. |
| 404 | Herramienta o recurso inexistente (consulta GET /tools). |
| 405 | GET sobre una herramienta que modifica estado — usa POST (la respuesta trae «Allow: POST»). |
| 429 | Rate limit: 240 peticiones/minuto POR credencial. Respeta «Retry-After» y las cabeceras «X-RateLimit-*». |
| 500 | Error interno. Si persiste, escríbenos con la hora y la ruta. |
Genera un cliente tipado (SDK)
Como el spec OpenAPI es público y se genera de los esquemas reales, cualquier generador estándar te da un cliente tipado en tu lenguaje. También puedes importarlo directo en Postman o Insomnia y explorar la API con autocompletado.
# 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.jsonBuenas prácticas
- Una clave por integración, con los permisos mínimos. Así puedes revocar una sin tumbar las demás.
- Guarda la clave en una variable de entorno o gestor de secretos, nunca en el código ni en el repositorio.
- Ante un 429, espera lo que diga «Retry-After» antes de reintentar — insistir solo alarga el bloqueo.
- Cachea las lecturas que no cambian a cada segundo (catálogos, históricos) en tu lado: tu cupo de 240/min rinde mucho más.
Lo que la API no puede hacer
- Modificar el balance de una cuenta ni las operaciones cerradas.
- Ejecutar órdenes sin plan ELITE y sin el interruptor de trading activado en Ajustes.
- Cambiar tu contraseña o email, ni acceder a funciones de administración.
¿Prefieres lenguaje natural en vez de código? El mismo catálogo está disponible como conector de Claude vía OAuth, sin claves manuales — mira el artículo «Conectar Claude a TradingNote» de esta misma wiki.