Quickstart

Make a real, authenticated call to the TradeWave API in the next 30 seconds - no signup, no key, no credit card. A public demo token is built into the examples below. Run one, see live detected seasonal patterns come back, then grab a free key to unlock every symbol and market.

1. Try it now - no signup

The base URL for every call is https://api.tradewave.ai/v1. Pass the token in the Authorization header. Check what the demo token can see with /me:

curl https://api.tradewave.ai/v1/me \
  -H "Authorization: Bearer tw_demo_explore"

import urllib.request, json

req = urllib.request.Request(
    "https://api.tradewave.ai/v1/me",
    headers={
        "Authorization": "Bearer tw_demo_explore",
        "Accept": "application/json",
        "User-Agent": "TradeWave-Python-Quickstart/1.0",
    },
)
with urllib.request.urlopen(req) as r:
    me = json.loads(r.read())

print(me["tier_name"], "- markets:",
      [m["name"] for m in me["markets_in_scope"]])

Real response:

{
  "tier": "demo",
  "tier_name": "Demo",
  "markets_in_scope": [
    { "id": "2", "name": "S&P 500 STOCKS", "ml_eligible": true }
  ],
  "opp_limit": 5,
  "rate": { "per_minute": 30, "per_day": 1000 },
  "upgrade_url": "https://tradewave.ai/account/api"
}

2. Scan the top seasonal patterns

/scan ranks the strongest current setups for a market. With the demo token, /scan is scoped to the 5 demo tickers (AAPL, MSFT, NVDA, AMZN, TSLA) - a free key scans the full market:

curl "https://api.tradewave.ai/v1/scan?markets=2&limit=5" \
  -H "Authorization: Bearer tw_demo_explore"

import urllib.request, json

req = urllib.request.Request(
    "https://api.tradewave.ai/v1/scan?markets=2&limit=5",
    headers={
        "Authorization": "Bearer tw_demo_explore",
        "Accept": "application/json",
        "User-Agent": "TradeWave-Python-Quickstart/1.0",
    },
)
with urllib.request.urlopen(req) as r:
    data = json.loads(r.read())

for o in data["opportunities"]:
    print(o["rank"], o["symbol"], o["direction"],
          "edge", o["edge_score"], "-", o["headline"])

const res = await fetch(
  "https://api.tradewave.ai/v1/scan?markets=2&limit=5",
  { headers: { Authorization: "Bearer tw_demo_explore" } }
);
const { opportunities } = await res.json();
opportunities.forEach(o =>
  console.log(o.rank, o.symbol, o.direction, "edge", o.edge_score)
);

Real response (top setup shown; arrays trimmed for the docs):

{
  "count": 3,
  "evaluated_count": 3,
  "rank_by": "sharpe",
  "markets_scanned": ["2"],
  "opportunities": [
    {
      "rank": 1,
      "symbol": "NVDA",
      "market": { "id": "2", "name": "S&P 500 STOCKS" },
      "direction": "long",
      "bias": "bullish",
      "edge_score": 70,
      "edge_basis": "win_rate 0.90 x sharpe 1.0 x 10y history",
      "headline": "NVDA long - enter ~Jul 17, hold 213d. Won 9/10 years, avg +40.8%, Sharpe 1.0.",
      "setup": {
        "entry_date": "2026-07-17",
        "entry_window": "2026-07-14 to 2026-07-20",
        "exit_date": "2027-02-15",
        "hold_days": 213
      },
      "stats": {
        "historical_win_rate": 0.9, "avg_return_pct": 40.84,
        "median_return_pct": 45.89, "sharpe_ratio": 0.98, "years": "10"
      },
      "ml": null,
      "next_step": {
        "order_ticket": { "side": "BUY", "symbol": "NVDA", "type": "MARKET",
                           "time_in_force": "DAY", "suggested_exit_date": "2027-02-15" }
      },
      "receipts": { "...": "per-year wins/losses, best/worst year, seasonal curve summary" }
    }
  ]
}

3. Deep-dive one symbol

/analyze/<symbol> returns the full Pattern Card for one ticker - the best current setup plus its full per-year history and a few alternative windows. With the demo token, use one of the 5 allowlisted tickers:

curl "https://api.tradewave.ai/v1/analyze/AAPL?market=2" \
  -H "Authorization: Bearer tw_demo_explore"

import urllib.request, json

req = urllib.request.Request(
    "https://api.tradewave.ai/v1/analyze/AAPL?market=2",
    headers={
        "Authorization": "Bearer tw_demo_explore",
        "Accept": "application/json",
        "User-Agent": "TradeWave-Python-Quickstart/1.0",
    },
)
with urllib.request.urlopen(req) as r:
    data = json.loads(r.read())

card = data["card"]
print(card["headline"])
print("edge", card["edge_score"], "win rate",
      card["stats"]["historical_win_rate"])

Or open it in the browser: https://api.tradewave.ai/v1/analyze/AAPL?market=2&api_key=tw_demo_explore

Real response (the card, trimmed):

{
  "as_of": "2026-06-19",
  "card": {
    "symbol": "AAPL",
    "market": { "id": "2", "name": "S&P 500 STOCKS" },
    "direction": "long",
    "bias": "bullish",
    "edge_score": 97,
    "headline": "AAPL long - enter ~Jun 25, hold 24d. Won 10/10 years, avg +6.0%, Sharpe 3.4.",
    "setup": {
      "entry_date": "2026-06-25",
      "entry_window": "2026-06-22 to 2026-06-28",
      "exit_date": "2026-07-19",
      "hold_days": 24
    },
    "stats": {
      "historical_win_rate": 1.0, "avg_return_pct": 6.05,
      "median_return_pct": 6.01, "sharpe_ratio": 3.42, "years": "10"
    },
    "ml": null,
    "verdict": "Strong, consistent seasonal long.",
    "receipts": { "wins": 10, "losses": 0, "per_year": [ "...10 years..." ] }
  },
  "other_setups": [
    { "entry_date": "2026-06-24", "hold_days": 28, "avg_return_pct": 6.5, "sharpe_ratio": 2.95 }
  ]
}

4. Get your own key (free)

1. Open the API console at tradewave.ai/account/api and sign in (or create a free account).
2. Click Create Key. Copy it immediately - the secret is shown only once.
3. Keys look like tw_live_abc123.... Keep them secret and send them in the Authorization header, never in the URL.

5. Use your key

Same calls, now with your own key and any symbol or market you like:

# your key, your symbol, any market
curl "https://api.tradewave.ai/v1/analyze/AAPL?market=2" \
  -H "Authorization: Bearer <your-api-key>"

import urllib.request, json

KEY = "<your-api-key>"  # tw_live_...
req = urllib.request.Request(
    "https://api.tradewave.ai/v1/scan?markets=2&limit=5",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Accept": "application/json",
        "User-Agent": "TradeWave-Python-Quickstart/1.0",
    },
)
with urllib.request.urlopen(req) as r:
    data = json.loads(r.read())

for o in data["opportunities"]:
    print(o["rank"], o["symbol"], o["edge_score"])

const KEY = "<your-api-key>";  // tw_live_...

const res = await fetch(
  "https://api.tradewave.ai/v1/scan?markets=2&limit=5",
  { headers: { Authorization: `Bearer ${KEY}` } }
);
const { opportunities } = await res.json();
opportunities.forEach(o => console.log(o.rank, o.symbol, o.edge_score));

Next steps

• API Reference - every endpoint with full parameters and response schemas.
• Playground - run live calls against your key right in the browser.
• MCP setup - connect TradeWave to ChatGPT, Claude, or Cursor.
• Authentication - key creation, rotation, and MCP sign-in or BYOK.
• Data Dictionary - plain-English definitions of every field.