SnapTrade API Skill

intent

this skill executes trades and retrieves account data from the user's connected brokerage via the SnapTrade API. use it whenever you need to place buy or sell orders, check account balances, retrieve positions, pull order history, get symbol quotes, cancel open orders, or refresh account holdings. triggers on any trading action or account data request routed through SnapTrade, even casual user phrases like "buy X shares", "what's my balance", "check my positions", "cancel that order", or "did my trade go through". always invoke this skill when brokerage account interaction of any kind is needed. does not provide OHLCV or price history data; use massive-data-feed skill for chart data instead.

inputs

environment variables (required)

• SNAPTRADE_CLIENT_ID: SnapTrade partner client ID. used to authenticate all API requests. treat as sensitive.
• SNAPTRADE_CONSUMER_KEY: SnapTrade partner consumer key. used to sign all API requests. treat as sensitive, do not share or log.
• SNAPTRADE_USER_ID: SnapTrade user ID for the connected brokerage user. grants access to that user's account data and trading permissions.
• SNAPTRADE_USER_SECRET: SnapTrade user secret for the connected brokerage user. acts as a per-user API key. treat as sensitive, rotate via SnapTrade dashboard if compromised.

setup and dependencies

• python >= 3.8
• snaptrade-python-sdk == 11.0.187
• python-dotenv == 1.2.2
• run bash scripts/setup.sh before first use. activates virtual environment at .venv-snaptrade/bin/activate.
• store all credentials in a .env file or secret manager. never hardcode, log, or pass through untrusted channels.

brokerage connections SnapTrade supports IBKR, Questrade, Alpaca, and other brokerages. account must be registered and connected via SnapTrade dashboard before this skill can execute trades or retrieve data.

external API SnapTrade API endpoint (implicit in SDK). subject to rate limits and request timeouts. no published rate limit docs, but assume conservative throttling on order placement endpoints.

procedure

1. initialize the SDK

   • input: environment variables (SNAPTRADE_CONSUMER_KEY, SNAPTRADE_CLIENT_ID, SNAPTRADE_USER_ID, SNAPTRADE_USER_SECRET)
   • import and instantiate SnapTrade client:

     import os
     from snaptrade_client import SnapTrade
     
     snaptrade = SnapTrade(
         consumer_key=os.environ["SNAPTRADE_CONSUMER_KEY"],
         client_id=os.environ["SNAPTRADE_CLIENT_ID"],
     )
     user_id = os.environ["SNAPTRADE_USER_ID"]
     user_secret = os.environ["SNAPTRADE_USER_SECRET"]
     

   • output: instantiated SnapTrade client object, user_id string, user_secret string ready for subsequent calls.

2. resolve symbol to ID (if placing a trade)

   • input: ticker symbol (e.g., "AAPL"), user_id, user_secret
   • call symbol resolution endpoint via SDK (see references/symbol-resolution.md for full details)
   • output: symbol ID string (unique identifier for that security on SnapTrade), currency, exchange, and quote data.
   • note: do not cache symbol IDs long term; they can change. resolve fresh on each trade request.

3. perform account data retrieval or execute trade action

   • choose branch based on user intent (see decision points below).

4. if retrieving account data:

   • input: user_id, user_secret
   • call appropriate account endpoint (accounts list, balances, positions, orders, historical value, or transaction history) via SDK methods.
   • output: structured JSON response containing requested account state.
   • see references/account-data.md and references/historical-data.md for endpoint specifics.

5. if placing an order (equity, options, or crypto):

   • input: user_id, user_secret, symbol ID (from step 2), order type (market, limit, bracket), quantity, side (buy or sell), price (if limit), expiry (if limit)
   • call impact check endpoint first to validate the order and get a trade_id (valid for 5 minutes only).
   • output: impact check response containing trade_id, estimated cost, margin impact, and validation warnings.
   • user confirms (or automated mode validates against symbol allowlist, notional cap, position limits, daily loss limits).
   • immediately place the order using the trade_id before the 5-minute window expires.
   • output: order confirmation with order ID, status, and execution details.
   • see references/place-orders.md, references/options-trading.md, and references/crypto-trading.md for trade-type specifics.

6. if canceling an order or refreshing holdings:

   • input: user_id, user_secret, order_id (if canceling)
   • call cancel endpoint or manual refresh endpoint via SDK.
   • output: cancellation or refresh confirmation.
   • see references/cancel-refresh.md for details.

7. trigger account refresh after order execution or cancellation

   • input: user_id, user_secret
   • call manual refresh endpoint to sync account state immediately.
   • output: refresh status and updated account holdings.

decision points

• if user intent is "retrieve data" (balance, positions, orders, history): skip symbol resolution and order placement. proceed directly to step 4 (account data retrieval).

• if user intent is "place a trade": resolve symbol ID in step 2, then perform impact check in step 5. if impact check fails validation (insufficient funds, symbol not tradable, daily loss exceeded), halt and return error without placing order.

• if automated mode is enabled: validate order against allowlist (approved symbols), notional cap (max dollar amount per trade), position limits (max shares or contracts held), and daily loss limit before placing. if any constraint is violated, block the trade and log the rejection. if all constraints pass, skip manual confirmation and place the order automatically.

• if user confirmation is required (default mode): present impact check results (cost, margin, warnings) and wait for explicit user approval before placing. if user declines, do not place the order.

• if trade_id from impact check has expired (> 5 minutes): do not attempt to place the order. return error and ask user to retry. trigger a fresh impact check and trade_id.

• if brokerage does not support trading (data-only connection): return error message indicating the account is read-only. permit account data retrieval only.

• if API request returns timeout or network error: retry up to 3 times with exponential backoff (1s, 2s, 4s). if all retries fail, return error and suggest checking network connectivity and SnapTrade API status.

• if credentials are invalid or expired: return authentication error. user must re-enter or rotate credentials via SnapTrade dashboard.

• if account data response is empty (no positions, no orders, no balance history): this is valid. return empty result set, not an error.

output contract

on successful account data retrieval:

• structured JSON object containing requested data (accounts, balances, positions, orders, or transaction history).
• example balance response: {"accounts": [{"account_id": "...", "balance": {...}}], "currency": "CAD"}.

on successful order placement:

• order confirmation object: {"order_id": "...", "status": "pending", "symbol_id": "...", "side": "buy", "quantity": 10, "price": 150.25, "created_at": "2024-01-15T14:30:00Z"}.

on successful order cancellation or refresh:

• status confirmation: {"status": "cancelled", "order_id": "..."} or {"status": "refreshed", "holdings_updated_at": "2024-01-15T14:35:00Z"}.

on error:

• error object: {"error": "<error message>", "code": "<error code>", "details": "..."}.
• common error codes: INVALID_CREDENTIALS, SYMBOL_NOT_FOUND, INSUFFICIENT_FUNDS, TRADE_ID_EXPIRED, NETWORK_TIMEOUT, BROKERAGE_READONLY.

file locations:

• all responses logged to stdout or a trades.log file (if configured).
• no file artifacts generated; skill returns data in-memory to caller.

outcome signal

• user sees order confirmation message with order ID, side, quantity, price, and status. order appears in account positions or order history within 1-2 minutes (depending on brokerage).

• user sees updated account balance or positions after data retrieval call completes. numbers match brokerage dashboard (with minor delay for data sync).

• user sees "order cancelled" message with order ID and timestamp after cancellation request succeeds. order no longer appears as open in account order list.

• user sees "holdings refreshed" message after manual refresh triggers. latest account state is fetched from brokerage.

• error message appears on screen if order is rejected, credentials are invalid, network fails, or constraints are violated. user can retry or contact support.

note on reference files: full procedure details are split across reference files for maintainability. consult references/account-data.md, references/symbol-resolution.md, references/place-orders.md, references/options-trading.md, references/crypto-trading.md, references/cancel-refresh.md, and references/historical-data.md as needed for your specific use case.

setup instructions: run bash scripts/setup.sh once before first use. see README.md for full onboarding on how to obtain credentials, register a user, and connect a brokerage account.

security reminders:

• this skill can place real trades and cancel orders on connected brokerage accounts. default to requiring user confirmation per trade. automated mode is supported only if explicitly configured and constraints are enforced.
• use paper trading or a low-limit account during testing.
• rotate SNAPTRADE_USER_SECRET immediately via SnapTrade dashboard if exposed.
• prefer a dedicated SnapTrade user with limited brokerage permissions for automated trading rather than your primary account credentials.