Skip to content
Skip to main content

Authentication

Every request to the TradeZero API is authenticated with a public key and a secret that you generate inside the TradeZero Portal. Before keys are available, you'll need to enable the API Trading add-on on your account and sign the API Trading Agreement in the portal.

This page walks the full portal flow for both live and paper accounts, shows how to attach the resulting credentials to a request, and lists the rules that govern an API key pair's lifecycle.

Pick an environment​

Live and paper are completely independent accounts with completely independent key pairs. Both environments share the same base URL - the API key pair you send determines which environment your request hits. There's no crossover: a paper key never reaches the live environment, and a live key never reaches paper, even though the URL is identical. You can't accidentally place a live order while testing against paper, and vice versa.

If this is your first integration with the TradeZero API, start with paper. The endpoints, schemas, and error semantics are identical to live, but you're working with simulated funds - any mistake in your code becomes a learning moment instead of a real loss. Move to live keys once your paper integration is hardened.

Get keys for a Live account​

You'll need an active live account with at least one platform bundle (ProBundle or FreeBundle) selected. API Trading is an add-on, not a standalone platform - you keep your GUI access (ZeroPro, TZ1, ZeroMobile) alongside programmatic access, so you can always manage positions from a TradeZero platform 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.

That's it. You now have a working live API key pair. See Authenticating requests below for how to attach the credentials to your first call.

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. (POST /v1/api/oauth2/jwtexchange exists for OAuth2-compliant clients integrating with TradeZero, but it is not required for programmatic API access - the two headers above are sufficient and recommended for direct integrations.)

Base URL​

Both live and paper share a single base URL: https://webapi.tradezero.com. It's the value baked into every code sample on this site and in the Quickstart Recipes. Your API key pair is what selects the environment - send paper keys and you hit paper; send live keys and you hit live. The portal also displays this URL as your Trading API Endpoint next to each generated key pair, so you can always copy it from there.

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.

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 account access. You can't have more than one set of keys at a time, and there is no per-endpoint scoping - anything you could do in the portal, your keys can do. If you need 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. Any application using the old secret stops working instantly - the previous 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 are isolated. Both environments share the same base URL, but the key pair you send is what selects the environment - a live key never reaches paper data, and a paper key never reaches live. Each environment has its own audit trail.

Next steps​

  • API Reference - the full endpoint catalog with request and response schemas.
  • Account Information - once authenticated, the first call most integrations make is GET /v1/api/accounts to list the accounts the keys can trade.
  • Authenticate & Discover Account - a hands-on recipe that runs the first call against the API with your fresh keys, confirms paper vs live, and enumerates the routes your account can use.
  • Place Your First Order - end-to-end flow from API key to a working order, including the buying-power check and reading back the fill state.
  • Quickstart Recipes - the full gallery of copy-paste flows in Python and TypeScript.