Get started
Authentication
The Bearer header, which routes need it, and how keys live and die.
Two ways in, one account. An agent host signs in through the browser and never sees a key; a script or a REST call carries a key, created on this site, shown once and revocable at any time. Both end up in the same header and count against the same limits.
Sign in from an agent host
Claude Code, Codex, Cursor, claude.ai and ChatGPT all do the same thing when they meet the MCP server: the first request answers 401 with a pointer, the host opens the browser, you sign in to TradingPal and approve, and the host keeps a token it refreshes by itself. The approval appears on Keys as a key named after the host, marked as a connected app; revoking it signs that host out. The MCP page has the flow step by step for anyone writing a host.
The header
Authorization: Bearer tp_live_…Keys start with tp_live_; sign-in tokens start with tp_oat_. The REST API and the MCP server accept either in the same header, and both count against the same limits.
curl "https://api.tradingpal.io/api/v1/me" \
-H "Authorization: Bearer $TRADINGPAL_API_KEY"Name your client
Optionally send X-TradingPal-Client: <your agent or script name>. Every request is logged with it, so when you ask about usage we can tell your script's calls from your agent's. MCP hosts are recorded by the client name they send at initialize.
Which routes need a key
| Routes | Key |
|---|---|
/me, /tickers, /tickers/{symbol}/patterns, /tickers/{symbol}/history, /tickers/{symbol}/chart.png | Required. These read or change the account's tracked tickers and their setups. |
/families, /families/{family}/stats, /universe | Optional. Keyless calls are limited per IP; keyed calls count against the key. |
/demo, /demo/{symbol}, /demo/{symbol}/chart.png | None. A fixed set of large caps, so an agent can show the data before anyone signs up. |
| MCP server | Signs the user in, or takes the key header. https://api.tradingpal.io/mcp/demo needs neither: demo and get_family_track_record work there, the other tools return an error that says how to connect. |
Key lifecycle
- Shown once. The full key appears at creation and never again; the server stores a hash. The Keys page keeps the prefix, the name, the creation time and the last use.
- Revoke any time. Revoking is immediate; anything still using the key gets
invalid_api_key. - Connected apps. A sign-in from an agent host is a key too, named after the host. Revoking it signs the host out; its tokens otherwise expire on their own, seven days for access and ninety for refresh.
- Rotate by creating, switching, revoking. Create the new key, move it into place, then revoke the old one. Nothing is lost in between.
- Plan. During the beta, keys work on Premium accounts. A key on an account without API access gets
forbiddenuntil the account is upgraded; the key itself stays valid.
Keep it out of transcripts
Signing in avoids the problem: the host holds a token you never see. Where a key is used, an agent host reads it from its configuration or the environment, never from the conversation. The Codex configuration names an environment variable for that reason; Claude Code and Cursor take the header in their own settings. If you paste a prompt that includes a key, treat that conversation as private and rotate the key when you are done.
Errors
| Status | Code | When |
|---|---|---|
| 401 | missing_api_key | The header was not sent on a route that needs it. |
| 401 | invalid_api_key | Unknown or revoked key. |
| 401 | invalid_token | A sign-in token that expired or was revoked. The host refreshes it or signs in again; the WWW-Authenticate header says which. |
| 403 | forbidden | The account is not on a plan with API access. |
| 429 | rate_limited | Over the per-key or per-IP limit; details.retry_after_seconds says how long to wait. |
Every error body has the same shape, and its fix field says what to do next.