Questrade Skill

Intent

Query a Questrade brokerage account and Canadian/US market data via the Questrade REST API. Use this skill to check account info (balances, positions, orders, executions, activities), fetch Level 1 market quotes, retrieve historical OHLCV candles, and search for symbols. Activate this when the user asks about their Questrade portfolio, Canadian/US stock prices, wants to verify orders or executions, or search for a ticker. note: personal API tokens are read-only, order placement and cancellation require Questrade partner access.

Inputs

External Connection: Questrade REST API

• endpoint: https://login.questrade.com and https://api01.questrade.com (or practice endpoint)
• auth method: OAuth 2.0 with refresh token rotation
• scope: market data access (optional, required for quote and candles), account data access (always included)

Credentials (choose one method):

1. Environment variables (recommended):

   • QUESTRADE_REFRESH_TOKEN: initial refresh token from API Centre (valid 7 days, auto-rotates)
   • QUESTRADE_PRACTICE: set to "true" for practice account, "false" for live
   • QUESTRADE_READ_ONLY: set to "true" to block order placement/cancellation (default: "true")

2. Credentials file (~/.openclaw/credentials/questrade.json):

   {
     "refreshToken": "paste-your-token-here",
     "practice": false,
     "readOnly": true
   }
   

Setup Steps:

1. Log in to Questrade → App Hub → API Centre → Activate API → generate manual authorization token
2. Store token in env var or credentials file (file auto-saves rotated tokens on each use)
3. Install dependencies: pip install requests

Edge Cases & Rate Limits:

• refresh tokens rotate on every use; the script auto-saves the new token to avoid expiry
• access tokens expire in ~30 minutes; the script auto-refreshes
• API rate limits: Questrade enforces limits by endpoint (typically 200 requests/min for account data, stricter for market data)
• network timeout risk: implement 30-second timeout on all HTTP calls
• empty result sets: certain queries (e.g., no open orders, no executions in date range) return empty arrays; handle gracefully

Procedure

1. Initialize connection & refresh access token

   • input: refresh token (from env or credentials file)
   • read current refresh token from storage
   • POST to https://login.questrade.com/oauth2/token with grant_type=refresh_token
   • output: new access token, new refresh token, expiry time
   • save new refresh token back to credentials storage

2. Fetch server time (optional, diagnostic)

   • input: access token
   • GET /time
   • output: server timestamp; confirms API connectivity

3. Fetch account list

   • input: access token
   • GET /accounts
   • output: array of account objects (id, type, status, isPrimary)
   • user selects or script filters to target account

4. Fetch account balances

   • input: access token, account id
   • GET /accounts/{id}/balances
   • output: cash, margin balances, buying power, currency breakdown

5. Fetch account positions

   • input: access token, account id
   • GET /accounts/{id}/positions
   • output: array of holdings (symbol id, quantity, price, unrealized gain/loss)

6. Fetch orders (open or date-filtered)

   • input: access token, account id, optional: state (Open/Closed/All), start date, end date
   • GET /accounts/{id}/orders?statuses={state}&startDate={start}&endDate={end}
   • output: array of order objects (id, symbol id, quantity, price, status, timestamp)

7. Fetch order detail

   • input: access token, account id, order id
   • GET /accounts/{id}/orders/{orderId}
   • output: full order object with fill history (legs, executions)

8. Fetch executions (fills, optional date range)

   • input: access token, account id, optional: start date, end date
   • GET /accounts/{id}/executions?startDate={start}&endDate={end}
   • output: array of execution objects (order id, symbol id, quantity, price, timestamp)

9. Fetch account activities (deposits, withdrawals, fees, max 30-day window)

   • input: access token, account id, start date, optional: end date (defaults to today)
   • validate date range is <= 30 days
   • GET /accounts/{id}/activities?startDate={start}&endDate={end}
   • output: array of activity objects (type, amount, timestamp)

10. Search symbols (by ticker prefix or company name)

    • input: access token, search query string
    • GET /symbols?prefix={query}
    • output: array of symbol objects (id, symbol, description, type, currency)

11. Fetch symbol metadata

    • input: access token, symbol id
    • GET /symbols/{id}
    • output: full symbol object (id, symbol, name, type, currency, isin, description)

12. Fetch Level 1 quote (single or batch)

    • input: access token, symbol id(s) (comma-separated)
    • GET /quotes?ids={id1},{id2},...
    • output: array of quote objects (id, symbol, bid, ask, bid_size, ask_size, last, last_size, volume, open, high, low, close, prev_close)

13. Fetch historical candles (OHLCV)

    • input: access token, symbol id, start date, optional: end date, interval (OneMinute/TwoMinutes/.../OneYear, default: OneDay)
    • GET /candles/{id}?startDate={start}&endDate={end}&interval={interval}
    • output: array of candle objects (open, high, low, close, volume, timestamp)

14. Fetch markets (list active markets)

    • input: access token
    • GET /markets
    • output: array of market objects (id, name, status, extended_hours_open, extended_hours_close, open, close)

15. Place order (requires partner API access; personal tokens will fail with 403)

    • input: access token, account id, side (buy/sell), symbol id, quantity, order type (Market/Limit/StopLimit), optional: limit price, stop price, force flag
    • fetch live quote for symbol to validate price sanity
    • construct order payload
    • if not force flag, display order summary (notional cost, bid/ask context) and prompt for y/n confirmation
    • POST /accounts/{id}/orders
    • output: order confirmation (order id, status)

16. Cancel order (requires partner API access; personal tokens will fail with 403)

    • input: access token, account id, order id
    • DELETE /accounts/{id}/orders/{orderId}
    • output: cancellation confirmation (status)

Decision Points

• if market data scope disabled (403 out of allowed OAuth scopes): quote and candles endpoints fail; account data commands (accounts, balances, positions, orders, executions, activities) still work. user must enable market data scope in Questrade API Centre and regenerate token.

• if credentials not found: check env vars (QUESTRADE_REFRESH_TOKEN), fall back to credentials file (~/.openclaw/credentials/questrade.json). if neither exists, exit with clear error message and setup instructions.

• if refresh token expired (>7 days without use): API returns 401 Unauthorized. user must manually regenerate token from Questrade API Centre and update credentials.

• if access token expired (~30 min): script auto-refreshes using stored refresh token (step 1). if refresh fails, token is invalid.

• if activities query exceeds 30-day window: reject with error; user must split into multiple 30-day queries.

• if no end date provided for activities: default end date to today.

• if symbol search returns empty: return empty array with note; user may try alternative search term or ticker.

• if candles/quote returns empty array: symbol may not have trading data or market data subscription is inactive.

• if order placement flagged read-only (QUESTRADE_READ_ONLY=true): block POST/DELETE calls and return error. user must set flag to false and confirm partner access.

• if order placement without force flag: always fetch live quote, display order summary (notional cost, bid/ask comparison for limit orders), and require y/n prompt. only submit if user confirms.

• if order placement returns 403 Forbidden: personal API token lacks order placement permission. user needs partner API access.

• if network timeout (>30 sec): retry up to 2 times with exponential backoff (2 sec, 4 sec). if all retries fail, return timeout error with endpoint and last response code.

• if rate limit hit (429 Too Many Requests): back off for 60 seconds, then retry. log rate limit hit.

Output Contract

success format:

all commands return structured JSON output with consistent schema:

{
  "status": "success",
  "data": <endpoint-specific array or object>,
  "meta": {
    "timestamp": "2026-02-15T14:32:00Z",
    "endpoint": "/accounts/{id}/balances",
    "responseTime": 234
  }
}

file output (if writing to disk):

• location: ~/.openclaw/questrade_cache/ (created on first run)
• format: JSON line-delimited (one record per line for batch queries)
• naming: {command}_{account_id}_{timestamp}.jsonl
• example: positions_12345678_2026-02-15T143200Z.jsonl

edge case outputs:

• empty result set: { "status": "success", "data": [], "meta": {...} }
• auth failure: { "status": "error", "code": "AUTH_FAILED", "message": "refresh token expired", "meta": {...} }
• rate limit: { "status": "error", "code": "RATE_LIMITED", "retryAfter": 60 }
• network timeout: { "status": "error", "code": "TIMEOUT", "message": "no response after 30s", "endpoint": "/..." }
• scope mismatch: { "status": "error", "code": "SCOPE_ERROR", "message": "403 out of allowed OAuth scopes", "hint": "enable market data in API Centre" }

Outcome Signal

the skill worked if:

1. credentials verified: refresh token successfully exchanged for access token; no 401/auth errors
2. data returned: requested endpoint returns non-empty or explicitly empty (but valid) JSON response
3. live quote fetch before order: buy/sell order shows live bid/ask and notional cost before confirmation
4. order summary displayed: user sees price sanity check warnings (e.g., "buy limit above ask") and can confirm/cancel
5. refresh token auto-saved: new refresh token persisted to credentials file or env (visible on next run, no token expiry within 7 days)
6. no network errors: all calls complete within 30-second timeout; retries succeed or fail gracefully
7. market data scope error clear: if quote/candles fail, error message explicitly states "403 out of allowed OAuth scopes" and directs user to API Centre
8. symbol search always precedes quote: user runs symbol-search first, gets symbol id, then calls quote with id (not ticker string)
9. activities window enforced: queries >30 days are rejected upfront with "max window 30 days" message
10. order placement blocked for personal tokens: order and cancel-order return clear error if QUESTRADE_READ_ONLY=true or partner access missing