Execute trades and retrieve account data via the SnapTrade API using the snaptrade-python-sdk. Use this skill whenever OpenClaw needs to place a buy or sell...
---
name: snaptrade-trading
description: >
Execute trades and retrieve account data via the SnapTrade API using the
snaptrade-python-sdk. Use this skill whenever OpenClaw needs to place a buy
or sell order, check account balances, get current positions, retrieve order
history, fetch symbol quotes, cancel an open order, or refresh account
holdings through SnapTrade. Triggers on any trading action or account data
request routed through SnapTrade — even if the user just says "buy X shares",
"what's my balance", "check my positions", "cancel that order", or "did my
trade go through". Always use this skill when brokerage account interaction
of any kind is needed.
credentials:
- name: SNAPTRADE_CLIENT_ID
description: SnapTrade partner client ID. Used to authenticate all API requests. Treat as sensitive.
required: true
- name: SNAPTRADE_CONSUMER_KEY
description: SnapTrade partner consumer key. Used to sign all API requests. Treat as sensitive — do not share or log.
required: true
- name: SNAPTRADE_USER_ID
description: SnapTrade user ID for the connected brokerage user. Grants access to that user's account data and trading permissions.
required: true
- name: SNAPTRADE_USER_SECRET
description: SnapTrade user secret for the connected brokerage user. Acts as a per-user API key. Treat as sensitive — rotate via SnapTrade dashboard if compromised.
required: true
warnings:
- This skill can place real trades and cancel orders on connected brokerage accounts.
- Default to requiring user confirmation per trade. Automated mode is supported if explicitly configured — enforce symbol allowlists, notional caps, position limits, and daily loss limits before enabling.
- Use paper trading or a low-limit account during testing.
- Store credentials in a .env file or secret manager — never hardcode, log, or pass them through untrusted channels.
- Rotate SNAPTRADE_USER_SECRET immediately via the SnapTrade dashboard if there is any chance it was exposed.
- Prefer a dedicated SnapTrade user with limited brokerage permissions for automated trading rather than using your primary account credentials.
compatibility:
- python >= 3.8
- snaptrade-python-sdk == 11.0.187
- python-dotenv == 1.2.2
- Run scripts/setup.sh before first use
---
# SnapTrade Trading Skill
SnapTrade connects OpenClaw to the user's brokerage (IBKR, Questrade, Alpaca,
and more) through a unified API. This skill handles all account data retrieval
and order execution. For market price data and OHLCV bars, use the
`massive-data-feed` skill — SnapTrade does not provide chart data.
---
## Setup
Run once before first use:
```bash
bash scripts/setup.sh
source .venv-snaptrade/bin/activate
```
See `README.md` for full onboarding — how to get credentials, register a user,
and connect a brokerage account.
---
## SDK Initialization
Always run this first before any other call:
```python
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"]
```
---
## What to do next — read the right reference file
Each reference file covers one domain. Read only what you need.
| Task | Reference file |
|---|---|
| Get accounts, balances, positions, orders, historical value | `references/account-data.md` |
| Resolve a ticker to a symbol ID + get quotes | `references/symbol-resolution.md` |
| Place an equity trade (limit, market, bracket) | `references/place-orders.md` |
| Place an options order (single or multi-leg) | `references/options-trading.md` |
| Place a crypto order | `references/crypto-trading.md` |
| Cancel an order or refresh holdings | `references/cancel-refresh.md` |
| Get historical transactions / activity log | `references/historical-data.md` |
---
## Key constraints to keep in mind
- `trade_id` from an impact check expires in **5 minutes** — place the order immediately after getting it, don't do other work in between
- SnapTrade does **not** provide OHLCV or price history — use `massive-data-feed` for that
- Not all brokerages support trading — some are data-only connections
- Always resolve symbol IDs fresh — don't cache them long term, they can change
- After any order placement or cancellation, trigger a manual refresh so the account state stays current (see `references/cancel-refresh.md`)
don't have the plugin yet? install it then click "run inline in claude" again.
restructured original content into implexa's six-part format with explicit decision points for impact check expiry, automated vs manual confirmation, empty result sets, network retries, and read-only brokerages; clarified all inputs including env var setup and external api dependencies; added edge cases for timeout handling, credential rotation, and symbol id freshness; preserved original procedure and warnings intact.
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.
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
bash scripts/setup.sh before first use. activates virtual environment at .venv-snaptrade/bin/activate.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.
initialize the SDK
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"]
resolve symbol to ID (if placing a trade)
references/symbol-resolution.md for full details)perform account data retrieval or execute trade action
if retrieving account data:
references/account-data.md and references/historical-data.md for endpoint specifics.if placing an order (equity, options, or crypto):
references/place-orders.md, references/options-trading.md, and references/crypto-trading.md for trade-type specifics.if canceling an order or refreshing holdings:
references/cancel-refresh.md for details.trigger account refresh after order execution or cancellation
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.
on successful account data retrieval:
{"accounts": [{"account_id": "...", "balance": {...}}], "currency": "CAD"}.on successful order placement:
{"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": "cancelled", "order_id": "..."} or {"status": "refreshed", "holdings_updated_at": "2024-01-15T14:35:00Z"}.on error:
{"error": "<error message>", "code": "<error code>", "details": "..."}.INVALID_CREDENTIALS, SYMBOL_NOT_FOUND, INSUFFICIENT_FUNDS, TRADE_ID_EXPIRED, NETWORK_TIMEOUT, BROKERAGE_READONLY.file locations:
trades.log file (if configured).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:
SNAPTRADE_USER_SECRET immediately via SnapTrade dashboard if exposed.