Skip to content
Skip to main content

Authentication

Authenticate every REST request with an API key pair from the TradeZero Portal. Send TZ-API-KEY-ID and TZ-API-SECRET-KEY as HTTP headers on each HTTPS call - no OAuth redirect or token refresh loop. WebSocket streams use the same key pair in the post-connect JSON authentication frame, not as WebSocket upgrade headers - see About WebSocket API → Connection and authentication.

Using an AI assistant instead?

Paste the hosted URL and sign in with OAuth - see TradeZero MCP.

Building a platform for TradeZero customers?

If your product connects other people's TradeZero accounts, do not use API keys. Use Connect Trade - TradeZero's chosen broker-connectivity partner - unless TradeZero has specified a direct partner program. See OAuth 2.0 Partner Integration.

Before keys appear, enable API Trading on your account and sign the API Trading Agreement in the portal.

TradeZero does not charge a separate execution fee for API use. You still need an eligible platform plan (ProBundle or FreeBundle on live accounts) and API Trading enabled before keys are issued.

This guide walks through Portal onboarding for paper and live accounts, shows how to attach credentials to a request, and documents key-pair lifecycle rules.

Official API only

TradeZero integrations use HTTPS with TZ-API-KEY-ID and TZ-API-SECRET-KEY. Third-party packages that drive a browser session are not affiliated with TradeZero and are not substitutes for this REST API. Use only the endpoints and credentials documented on this site.

  • Choose paper or live, enable API Trading in the portal, sign the API Trading Agreement, then generate keys. Verify with GET /v1/api/accounts. The Authenticate & Discover Account recipe walks through the first call end-to-end.

  • Sign and read the API Trading Agreement before going live. Start on paper, validate order placement and lifecycle end-to-end, then switch to live keys when you are ready. The API supports personal trading tools you control - you remain responsible for trading decisions and can always manage the account from TradeZero Platforms.

Pick an environment​

Live and paper are completely independent accounts with completely independent key pairs. Both share the same base URL (https://webapi.tradezero.com) - the API key pair you send selects the environment. A paper key never reaches live, and a live key never reaches paper.

If this is your first integration, start with paper. You share the same host and JSON schemas as live, but you trade simulated funds. Locates, route defaults when route is omitted, historical order retention, cash ledger depth, and some session reject codes differ - see the table below, then move to live keys once your paper integration is ready.

Paper vs live​

PaperLive
Starting balance$1,000,000 paper dollarsYour funded balance
Account lifespan30 days (permanent if linked to a live account)None
Account IDPaper portal IDs use a TZP prefix in the portal (not an API contract)Opaque - do not pattern-match
Short sellingEvery symbol treated as easy-to-borrowReal ETB / HTB inventory
Locates (quote / accept / sell-back)Accepted, but no offerable inventory - see belowFull workflow
Routes when route is omittedAuto-assigns PAPER / PAPERMYou must send an explicit route from GET /routes

Paper and live share the same host and JSON schemas. Differences that affect integration are in the table above (locates, route defaults) plus session reject codes and historical retention - always label paper vs live when those behaviors matter.

Locates are live-only​

Locates require a live account

Locates allocate real borrow inventory. On paper, the endpoints accept requests, but quotes do not produce offerable inventory. Details: Short Locates.

Build the order side against paper; complete quote → accept → sell-back on a live key pair before scaling short-side workflows.

Tell them apart over the API​

Read accountType from GET /v1/api/account/{accountId}. Paper returns "Paper". Live returns "Live" or another non-"Paper" value (for example "Margin" or "Cash"). Treat anything other than "Paper" as live. Do not parse account IDs - the TZP prefix is a portal convention, not an API contract.

detail = client.get(f"/v1/api/account/{account_id}").json()
is_paper = detail.get("accountType") == "Paper"

Paper account lifespan​

  • New paper accounts open with $1,000,000 and last 30 days unless you link them to a live TradeZero account in the portal (then they become permanent).
  • You can reset a paper account from the paper portal at any time - balance returns to $1,000,000 and positions/orders clear. Your API key pair keeps working; you do not need to regenerate keys after a reset.

Moving from paper to live​

  1. Swap TZ-API-KEY-ID and TZ-API-SECRET-KEY for your live pair. The base URL stays the same.
  2. Send an explicit route on live orders - query GET /routes and include a matching routeName. See Get available routes.
  3. Complete locate quote → accept on live before scaling short-side work.
  4. Confirm accountType before mutating calls if your tool can write to either environment.

Get keys for a Live account​

You'll need an active live account with at least one platform bundle (ProBundle or FreeBundle) selected and API Trading enabled in the portal. API Trading is an add-on - it does not replace your GUI access to TradeZero Platforms, so you can always manage positions from the apps alongside your API integration.

1. Open Platform Selection​

Log into the TradeZero Portal and choose Trade → Platform Selection from the main navigation.

2. Enable the API Trading add-on​

On the Platform Selection page, pick a bundle (ProBundle or FreeBundle) if you don't have one yet, and enable the API Trading add-on. API Trading is an additive toggle - it does not replace your existing platform pack.

3. Sign the API Trading agreements​

You'll be taken to the Agreements page. Sign every agreement listed there, including the new API Trading Agreement. The API Keys tab won't appear in the portal until every agreement on this page shows Signed.

4. Confirm API Keys is enabled​

Once every agreement is signed and submitted, an API Keys tab appears in the account-settings tab strip. If you don't see the tab, revisit the Agreements page and make sure every row is marked Signed.

5. Generate your API key pair​

Open API Keys → API Key Management and click Generate API Keys. The portal will show you three values:

  • Trading API Endpoint - the base URL your requests go to (always visible).
  • Public Key - the TZ-API-KEY-ID header value (always visible).
  • Secret - the TZ-API-SECRET-KEY header value. Shown once, then it disappears.

Copy the secret somewhere secure before you navigate away or refresh. If you lose it, the only recovery path is to regenerate - which invalidates the old secret immediately.

You now have a working live API key pair. See Authenticating requests below for how to attach the credentials to your first REST or WebSocket call. For assistants, see TradeZero MCP.

Get keys for a Paper account​

Paper accounts use the same TradeZero Portal credentials but route into a separate paper environment. No platform bundle selection is required - paper accounts get every platform by default - so the flow is one step shorter than live.

1. Log into the Paper Portal​

The Paper Portal entry point is the same URL you'd use for live, but selecting your paper account takes you into the paper environment. The paper UI is a leaner version of the live portal.

2. Click Enable API Trading​

On the paper portal home you'll see a call-to-action labeled API Keys or Enable API Trading. Click it to start the paper-specific API onboarding flow. There is no Platform Selection step.

3. Sign the API Trading agreements​

Sign the paper-context API Trading agreements. The terms mirror the live agreements, with additional language clarifying that paper trades are simulated and carry no real financial risk.

4. Confirm API Keys is enabled​

The API Key Management section appears in your paper portal. Paper API access is fully independent of your live API access - enabling paper does not enable live, and disabling live does not disable paper.

5. Generate your paper API key pair​

Open API Key Management and click Generate API Keys. The interface is identical to live: a public key (always visible), a secret (shown once), and the same Trading API Endpoint URL - the paper key pair is what routes your requests into the paper environment. Save the secret immediately.

Authenticating requests​

All TradeZero API requests are made over HTTPS. The public key and secret are sent on every request as two custom headers:

  • TZ-API-KEY-ID - your public key.
  • TZ-API-SECRET-KEY - your secret.

No session, no refresh flow - the headers are checked on every request, so any HTTP client in any language works out of the box.

Base URL​

Base URL: https://webapi.tradezero.com - same for paper and live; the key pair selects the environment (Pick an environment). The portal shows this URL as Trading API Endpoint next to each generated key pair.

cURL example​

cURL
curl 'https://webapi.tradezero.com/v1/api/account/:accountId' \
  -H 'Accept: application/json' \
  -H 'TZ-API-KEY-ID: {YOUR_PUBLIC_KEY}' \
  -H 'TZ-API-SECRET-KEY: {YOUR_SECRET}'

For end-to-end Python and TypeScript walkthroughs, see the Quickstart Recipes - every recipe starts from the same two headers. Recipes read TZ_API_KEY_ID, TZ_API_SECRET, and TZ_ACCOUNT from your environment (copy .env.example to .env and fill in the paper or live key pair you generated in the portal).

Keep your secret out of client-side code

Treat the secret like a password: never commit it to source control, never embed it in a mobile or browser bundle, and never log full request headers in production. If the secret leaks, regenerate it immediately from the Portal - see the lifecycle rules below.

Key lifecycle rules​

The same rules apply to live and paper key pairs:

  • One active pair per account, full trading permissions. Each account supports one active key pair at a time. API keys inherit the account's full trading permissions and are not scoped per endpoint - treat them as privileged credentials. Store secrets server-side only, rotate immediately on suspected exposure, and restrict who can access them internally. To rotate credentials, use Regenerate Secret or Disable + Generate (described below).
  • The secret is shown exactly once. It appears immediately after generation and disappears the moment you refresh, navigate away, or leave the page. There is no "show me the secret again" button. If you lose it, your only option is to regenerate - which invalidates the existing secret.
  • Regenerate Secret rotates the secret only. The public key stays the same; the secret is replaced. Applications still using the previous secret receive auth failures immediately - the old secret is invalidated the moment you click Regenerate. The new secret is shown once, same as on initial generation.
  • Disable API Key Pair invalidates BOTH keys. Both the public key and the secret are torn down. To get programmatic access back you must press Generate API Keys to create a brand-new pair (and a new public key).
  • Every lifecycle event is logged. You can review when each key was created, regenerated, or disabled in the Audit Trail on the API Key Management page, and you'll get an email notification at the same time. If you see an event you didn't initiate, treat your credentials as compromised and regenerate immediately.
  • Live and paper each have their own audit trail. A key pair never crosses environments - see Pick an environment.

Next steps​