Developer API

Build on TradingNote with the public REST API /api/v1: accounts, operations, algorithms, backtests, explorations and portfolios from any language, authenticated with your API key.

TradingNote exposes a public REST API so you can build your own integrations: dashboards, bots, spreadsheets, alerts or anything else. It's the SAME tool catalog the Claude connector uses (~125 tools across accounts, operations, algorithms, explorations, backtests, portfolios, metrics and trading), but as plain HTTP + JSON: it works from any language, with no dependency on Claude.

The REST API and API keys are exclusive to the ELITE plan since October 3, 2026 (TRADER/PRO plans active before the change keep access until their next billing cutoff). The Claude connector (OAuth) is different: the free trial includes it except live trading and PRO has basic read access to profile and accounts.

Base URL

text
https://app.tradingnote.co/api/v1
Every route in this article hangs off this base.

The full OpenAPI 3.1 spec —generated from the real schemas, importable into Postman or any SDK generator— lives at «/api/v1/openapi.json» and is public.

Authentication

  1. 1

    Generate your API key

    In the app: Settings → «Developer API» → «Generate new API Key». Pick a name and check the per-category permissions your integration needs (all are on by default).

  2. 2

    Save the key — it's shown only ONCE

    The key looks like «tn_…» and is never shown again (we only store its hash). If you lose it, revoke it and generate a new one.

  3. 3

    Send it on every request and verify

    Header «Authorization: Bearer tn_…». Verify with GET /me: it returns your user, the credential type and the key's active permissions.

bash
curl -H "Authorization: Bearer tn_TU_CLAVE" \
  https://app.tradingnote.co/api/v1/me
Recommended first call: the credential's identity and permissions.

The API key is a secret: use it only from your server or scripts, never in code running in the browser. You can revoke it anytime from Settings and access is cut off instantly. OAuth access tokens («tnoa_…») issued by TradingNote's OAuth flow are also accepted.

How it's organized

Each capability is a named «tool», and each tool is an endpoint under /tools/{name}. Your starting point is GET /tools: it returns the catalog VISIBLE to your key —name, description, HTTP method and the exact input schema of each one. Anything missing from it means your key lacks that category's permission.

  • Reads → GET /tools/{name} with arguments as query params. A GET never modifies anything.
  • Mutations → POST /tools/{name} with arguments as a JSON body. A GET against a state-changing tool returns 405 with «Allow: POST».
  • On GET, types are coerced from the tool's schema: numbers and booleans («true/false/1/0») go as-is; an array or object argument travels as URL-encoded JSON; a repeated key («?symbols=A&symbols=B») arrives as an array.
  • Every response uses the same envelope: «{ success: true, data: … }» on success and «{ success: false, error: "actionable message" }» on failure.
  • A misspelled parameter is REJECTED with a suggestion of the correct name («did you mean 'accountId'?») instead of being silently ignored — so a typo never does something other than what you asked.

Examples

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"

Per-category permissions

Each key carries per-category permissions, chosen when you generate it. Without the permission, that category's tools don't appear in your catalog and calling them returns 403. Give each integration only what it needs.

CategoryWhat it allows
accountsList, view and create accounts; stats, equity, health and open positions.
operationsRead closed trades and accounting entries.
strategiesAlgorithms: list, view, create, deploy; trade history, equity curves, cost templates.
strategyDevExplorations (algorithm factory), post-hoc robustness and the strategy IDE.
copyTradingCopy trading: your masters and subscriptions (risk mode, lot, multiplier, limits), copy history with rejection reason, signals; pause/resume and adjust sizing (sizing also requires the live trading switch). Never creates or deletes masters or subscriptions.
backtestingManual backtesting sessions and their replay (trading simulated money over historical candles).
portfoliosPortfolios and live sessions: create, configure risk/rotation, start/pause/stop, logs.
metricsTN Score, account/portfolio health and risk alerts.
notesNotes on trades.
profileUser profile and effective plan (available quotas).
tradingManual trading: open, modify and close positions on your accounts. Has an extra lock (see below).

Trading tools execute real-money orders and have a triple lock: besides the «trading» permission on the key, they require the ELITE plan AND the «Allow live trading» switch in Settings (off by default). The category alone never executes an order.

Errors and limits

CodeMeaning
400Invalid arguments or rejected request (includes misspelled-parameter rejection, with a suggestion).
401Missing, invalid, expired or revoked credential.
402Your plan doesn't include API access (ELITE-only; the plan is re-checked on every request).
403The key lacks that category's permission, or the trading lock is missing.
404Tool or resource doesn't exist (check GET /tools).
405GET against a state-changing tool — use POST (the response carries «Allow: POST»).
429Rate limit: 240 requests/minute PER credential. Honor «Retry-After» and the «X-RateLimit-*» headers.
500Internal error. If it persists, contact us with the time and the route.

Generate a typed client (SDK)

Since the OpenAPI spec is public and generated from the real schemas, any standard generator gives you a typed client in your language. You can also import it straight into Postman or Insomnia and explore the API with autocompletion.

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

Best practices

  • One key per integration, with minimal permissions. That way you can revoke one without breaking the rest.
  • Store the key in an environment variable or a secrets manager, never in code or in the repository.
  • On a 429, wait what «Retry-After» says before retrying — hammering only extends the block.
  • Cache reads that don't change every second (catalogs, history) on your side: your 240/min budget goes much further.

What the API cannot do

  • Modify an account's balance or closed trades.
  • Execute orders without the ELITE plan and the trading switch enabled in Settings.
  • Change your password or email, or access admin features.

Prefer natural language over code? The same catalog is available as a Claude connector via OAuth, with no manual keys — see the «Connect Claude to TradingNote» article in this wiki.