Engine (Aries Trading Platform API) Skill

Product summary

Engine is a REST and WebSocket API for building trading applications with OAuth2-secured access to user accounts, order execution, real-time market data, and financial analytics. Agents use this skill to help users integrate trading functionality, place orders, fetch account balances, stream market data, and access supplemental analytics. The primary documentation is at https://finance.dev. Key endpoints: https://api.aries.com/v1/ for REST, wss://api.aries.com/v1/market/ws and wss://api.aries.com/v1/accounts/ws for WebSockets. SDKs available for JavaScript, Python, and Go. All requests require OAuth2 authentication with access tokens.

When to use

Reach for this skill when:

• A user wants to build a trading app or integrate with a brokerage account
• You need to place, modify, or cancel orders
• You need to fetch account balances, positions, or order history
• You need real-time market quotes, historical data, or analytics (top gainers, ratings, sector data)
• You need to stream live market data or account updates via WebSocket
• You need to preview orders before execution to check costs
• You need to implement OAuth2 authentication for a trading platform
• You need to access supplemental data (company profiles, financials, options chains, news, ESG, transcripts)

Quick reference

Core API Endpoints

Task	Endpoint	Method	Scope Required
Get user accounts	/v1/users/me/accounts	GET	account:information
Get account balances	/v1/accounts/{id}/balances	GET	account:information
Get positions	/v1/accounts/{id}/positions	GET	position:information
Get order history	/v1/accounts/{id}/orders	GET	order:information
Place order	/v1/orders	POST	order:execution
Preview order	/v1/orders/preview	POST	order:execution
Update order	/v1/orders/{id}	PUT	order:execution
Cancel order	/v1/orders/{id}	DELETE	order:execution
Search symbols	/v1/marketdata/search	GET	market:information
Get quotes	/v1/chart/quotes	GET	market:information
Get historical bars	/v1/chart/bars	GET	market:information

OAuth2 Scopes

Scope	Access
user:information	User profile and personal details
account:information	Account balances, positions, transaction history
order:execution	Place, modify, cancel orders
order:information	View order history and status
position:information	View current positions and holdings
market:information	Live and historical market data
calendar:information	Earnings, economic events, market schedules
options:information	Options chains, Greeks, expiration data
analytics:information	Analytics, ratings, market insights
market:supplemental	News, company profiles, financials, filings, ETF data, technical analysis

Order Types

Type	Use Case	Required Fields
market	Execute immediately at current price	symbol, quantity, side
limit	Execute at specific price or better	symbol, quantity, side, price
stop	Trigger market order when price reached	symbol, quantity, side, stopPrice
stop_limit	Trigger limit order when stop price reached	symbol, quantity, side, stopPrice, price

Time-in-Force Options

Value	Meaning
day	Order expires at end of trading day
gtc	Good-til-canceled (remains until filled or manually canceled)
ioc	Immediate-or-cancel (fill what can be filled, cancel rest)
fok	Fill-or-kill (all-or-nothing, cancel if can't fill completely)

WebSocket Endpoints

Purpose	URL	Use For
Market Data	wss://api.aries.com/v1/market/ws	Real-time quotes, trades, Level 2, Greeks
Account Updates	wss://api.aries.com/v1/accounts/ws	Orders, positions, balances, watchlist
Charting	wss://api.aries.com/v1/charts/ws	TradingView-compatible quotes and trades

Rate Limits

Category	Limit
Authentication	10 requests/minute
User Management	100 requests/minute
Market Data	1,000 requests/minute
Trading	50 requests/minute

Decision guidance

When to use REST vs WebSocket

Scenario	Use REST	Use WebSocket
One-time data fetch (quote, balance)	✓
Polling for updates every few seconds	✓
Real-time streaming (live quotes, order updates)		✓
Building a live trading dashboard		✓
Batch operations (search, analytics)	✓
Minimal latency required		✓

When to use Authorization Code vs PKCE flow

Scenario	Use Authorization Code	Use PKCE
Server-side backend (can store client_secret)	✓
Single-page app (SPA)		✓
Mobile app		✓
Desktop app with backend	✓
Public client (no backend)		✓

When to preview vs place order directly

Scenario	Preview First	Place Directly
User-initiated trades	✓
Algorithmic/automated trading		✓
Large orders (cost verification)	✓
High-frequency trading		✓
First-time user	✓

Workflow

1. Set up authentication

1. Go to Client Center → API section
2. Click "Generate Key"
3. Fill in: Client name, Redirect URI (https://mcp.aries.com/auth/callback for MCP), Scopes
4. Copy Client ID and Client Secret (shown only once)
5. Store credentials in environment variables (never hardcode)

2. Implement OAuth2 flow

1. Redirect user to https://app.aries.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=...&state=RANDOM_STRING
2. User logs in and approves scopes
3. Aries redirects back with authorization code
4. Exchange code for tokens: POST https://api.aries.com/v1/oauth2/token with client_id, client_secret, code, redirect_uri
5. Store access_token and refresh_token securely
6. Use access_token in Authorization: Bearer header for all API requests

3. Fetch account data

1. Get user accounts: GET /v1/users/me/accounts
2. Extract account ID from response
3. Fetch balances: GET /v1/accounts/{id}/balances
4. Fetch positions: GET /v1/accounts/{id}/positions
5. Fetch order history: GET /v1/accounts/{id}/orders

4. Place an order

1. Search for symbol: GET /v1/marketdata/search?query=AAPL
2. Get current quote: GET /v1/chart/quotes?symbols=AAPL
3. Preview order: POST /v1/orders/preview with symbol, quantity, side, orderType, price (if limit)
4. Verify estimated cost and commission
5. Place order: POST /v1/orders with same parameters
6. Store order ID and monitor status

5. Stream real-time data

1. Connect to WebSocket: wss://api.aries.com/v1/market/ws
2. Send auth message with access token
3. Wait for authSuccess response
4. Subscribe to symbols: {"type": "subscribe", "payload": [{"symbol": "AAPL", "quoteFields": ["bidPrice", "askPrice", "lastPrice"]}]}
5. Process incoming messages (NDJSON format)
6. Implement ping/pong every 30-60 seconds to keep connection alive
7. Implement exponential backoff reconnection on disconnect

6. Handle token refresh

1. Check token expiration time (expires_in from initial exchange)
2. Before expiry, call: POST /v1/oauth2/token with grant_type=refresh_token, refresh_token, client_id, client_secret
3. Store new tokens (refresh_token may be reissued)
4. If using SDK, enable autoRefresh: true to handle automatically

Common gotchas

• Hardcoding credentials: Never hardcode client_secret or tokens in source code. Use environment variables or secrets manager.
• Redirect URI mismatch: The redirect_uri must match exactly (including protocol, path, trailing slashes) with what's registered in Client Center. Character-for-character match required.
• Authorization code expiry: Authorization codes expire after 10 minutes and are single-use. Exchange immediately after receiving.
• Scope typos: Scope names are case-sensitive. Verify against the Available Scopes table.
• Missing account ID: Always fetch accounts first before making account-specific calls. Account ID is required for balances, positions, orders.
• Order preview not checked: Placing orders without previewing can result in unexpected costs or insufficient buying power. Always preview first for user-initiated trades.
• WebSocket authentication timing: Don't subscribe until you receive authSuccess response. Subscribing before auth will fail silently.
• Token expiration in WebSocket: WebSocket connections don't auto-refresh tokens. Reconnect with a fresh token if connection drops.
• Rate limit headers ignored: Check X-RateLimit-Remaining and X-RateLimit-Reset headers. Implement exponential backoff for 429 responses.
• Forgetting to handle 401 errors: Access tokens expire. Catch 401 errors and refresh the token, then retry the request.
• WebSocket NDJSON parsing: Messages arrive as newline-delimited JSON. Split on \n and parse each line separately.
• Insufficient scopes: If a request returns 403, verify the access token has the required scope. Regenerate with correct scopes.
• Market hours: Some endpoints (quotes, orders) behave differently during market hours vs after-hours. Check market status first.

Verification checklist

Before submitting work with Engine integration:

• OAuth2 credentials stored in environment variables, not hardcoded
• Redirect URI registered in Client Center matches exactly (including protocol and path)
• All required scopes requested and granted (check token response)
• Access token included in Authorization: Bearer header for all API requests
• Token refresh logic implemented (check for 401, refresh, retry)
• Account ID fetched before making account-specific calls
• Orders previewed before placement (for user-initiated trades)
• Error handling for 429 (rate limit) with exponential backoff
• WebSocket connections authenticate before subscribing
• WebSocket messages parsed as NDJSON (split on newlines)
• Ping/pong implemented for WebSocket keep-alive
• Reconnection logic with exponential backoff for WebSocket
• Market data scopes verified for real-time endpoints
• Order parameters validated (symbol exists, quantity > 0, price valid for order type)

Resources

• Comprehensive page listing: https://finance.dev/llms.txt
• Quick Start Guide: https://finance.dev/api-reference/quickstart (5-minute walkthrough of OAuth2, token exchange, and first API call)
• OAuth2 Guide: https://finance.dev/api-reference/oauth2/guide (flows, scopes, security best practices, troubleshooting)
• SDKs Overview: https://finance.dev/sdks/overview (JavaScript, Python, Go with built-in token management)

---

For additional documentation and navigation, see: https://finance.dev/llms.txt