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

text
https://app.tradingnote.co/api/v1
Todas las rutas de este artículo cuelgan de aquí.

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

bash
curl -H "Authorization: Bearer tn_TU_CLAVE" \
  https://app.tradingnote.co/api/v1/me
Primera llamada recomendada: identidad y permisos de la credencial.

La 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

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"

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íaQué permite
accountsListar, ver y crear cuentas; estadísticas, equity, salud y posiciones abiertas.
operationsLeer operaciones cerradas y asientos de contabilidad.
strategiesAlgoritmos: listar, ver, crear, desplegar; historial de trades, curvas de equity, plantillas de costos.
strategyDevExploraciones (fábrica de algoritmos), robustez post-hoc y el IDE de estrategias.
copyTradingCopy 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.
backtestingSesiones de backtesting manual y su replay (operar con dinero simulado sobre velas históricas).
portfoliosPortafolios y sesiones live: crear, configurar riesgo/rotación, iniciar/pausar/detener, logs.
metricsTN Score, salud de cuenta/portafolio y alertas de riesgo.
notesNotas sobre operaciones.
profilePerfil del usuario y plan efectivo (cupos disponibles).
tradingTrading 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ódigoSignificado
400Argumentos inválidos o petición rechazada (incluye el rechazo de parámetros mal escritos, con sugerencia).
401Credencial ausente, inválida, expirada o revocada.
402Tu plan no incluye acceso a la API (exclusiva de ELITE; el plan se revalida en cada petición).
403La clave no tiene el permiso de esa categoría, o falta el candado de trading.
404Herramienta o recurso inexistente (consulta GET /tools).
405GET sobre una herramienta que modifica estado — usa POST (la respuesta trae «Allow: POST»).
429Rate limit: 240 peticiones/minuto POR credencial. Respeta «Retry-After» y las cabeceras «X-RateLimit-*».
500Error 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.

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

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