@farazirfan/costar-server-executor 1.7.26 → 1.7.28

package/skills/saxo/references/api-reference.md

@@ -0,0 +1,332 @@
+# Saxo API Reference
+
+> Agent-editable. Add notes about endpoints, quirks, rate limits as you discover them.
+
+Complete reference for Saxo OpenAPI endpoints using `saxo_openapi` Python package.
+
+## Client Setup
+
+```python
+import saxo_openapi
+import os
+
+client = saxo_openapi.API(
+    access_token=os.environ['SAXO_ACCESS_TOKEN'],
+    environment='simulation'  # or 'live'
+)
+```
+
+## Root Services (Account Info)
+
+### User Details
+
+Get authenticated user information:
+
+```python
+import saxo_openapi.endpoints.rootservices as rs
+
+r = rs.user.UserDetails()
+client.request(r)
+
+# Returns:
+# - ClientKey
+# - Name
+# - Accounts (list with AccountKey, AccountType, Currency)
+```
+
+### Client Details
+
+```python
+r = rs.client.ClientDetails(ClientKey=client_key)
+client.request(r)
+```
+
+## Portfolio Endpoints
+
+### Account Balances
+
+```python
+import saxo_openapi.endpoints.portfolio as pf
+
+r = pf.balances.AccountBalances(params={'ClientKey': client_key})
+client.request(r)
+
+# Returns:
+# - TotalValue
+# - CashBalance
+# - MarginAvailableForTrading
+# - MarginUtilizationPct
+# - UnrealizedPositionsValue
+```
+
+### Positions
+
+```python
+# All positions
+r = pf.positions.PositionsMe()
+client.request(r)
+
+# Specific position
+r = pf.positions.PositionDetails(PositionId=position_id)
+client.request(r)
+
+# Returns:
+# - PositionId
+# - Uic, AssetType
+# - Amount (positive = long, negative = short)
+# - OpenPrice, CurrentPrice
+# - ProfitLossOnTrade
+# - MarginUsedIncludingPendingOrders
+```
+
+### Exposure
+
+```python
+# Net exposure across all positions
+r = pf.netpositions.NetPositionsMe()
+client.request(r)
+```
+
+## Trading Endpoints
+
+### Place Order
+
+```python
+import saxo_openapi.endpoints.trading as tr
+
+order_data = {
+    'AccountKey': account_key,
+    'Uic': 21,
+    'AssetType': 'FxSpot',
+    'BuySell': 'Buy',
+    'Amount': 10000,
+    'OrderType': 'Market',
+    'OrderDuration': {'DurationType': 'DayOrder'}
+}
+
+r = tr.orders.Order(data=order_data)
+client.request(r)
+
+# Success: status_code 201
+# Response contains OrderId
+```
+
+### Order Status
+
+```python
+# All orders
+r = tr.orders.OrdersMe()
+client.request(r)
+
+# Specific order
+r = tr.orders.OrderDetails(OrderId=order_id)
+client.request(r)
+
+# Returns:
+# - OrderId
+# - Status: Working, Filled, Cancelled, Rejected
+# - FilledAmount
+# - ExecutionTimeOpen
+```
+
+### Cancel Order
+
+```python
+r = tr.orders.CancelOrder(AccountKey=account_key, OrderId=order_id)
+client.request(r)
+
+# Success: status_code 200 or 202
+```
+
+### Modify Order
+
+```python
+# Update order price or duration
+r = tr.orders.ModifyOrder(
+    AccountKey=account_key,
+    OrderId=order_id,
+    data={'OrderPrice': 1.0860}
+)
+client.request(r)
+```
+
+### Info Prices (Real-Time Quotes)
+
+```python
+r = tr.prices.InfoPrice(Uic=21, AssetType='FxSpot')
+client.request(r)
+
+# Returns:
+# - Quote: {Bid, Ask, Mid}
+# - PriceInfo: {High, Low, NetChange}
+# - InstrumentPriceDetails: {IsMarketOpen, ValueDate}
+```
+
+## Reference Data
+
+### Search Instruments
+
+```python
+import saxo_openapi.endpoints.referencedata as rd
+
+params = {
+    'Keywords': 'EURUSD',
+    'AssetTypes': 'FxSpot',
+    'limit': 20
+}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+
+# Returns array with:
+# - Identifier (Uic)
+# - Symbol
+# - Description
+# - AssetType
+# - ExchangeId
+```
+
+### Instrument Details
+
+```python
+r = rd.instruments.InstrumentDetails(Uic=21, AssetType='FxSpot')
+client.request(r)
+
+# Returns:
+# - MinimumTradeSize
+# - TickSize
+# - ContractSize
+# - TradingStatus
+# - Format (price decimals)
+```
+
+### Exchanges
+
+```python
+r = rd.exchanges.ExchangeList()
+client.request(r)
+```
+
+## Chart Data
+
+### Historical Candles
+
+```python
+import saxo_openapi.endpoints.chart as ch
+
+params = {
+    'Uic': 21,
+    'AssetType': 'FxSpot',
+    'Horizon': 60,  # 1-hour candles
+    'Count': 100    # Last 100 candles
+}
+r = ch.charts.Charts(params=params)
+client.request(r)
+
+# Returns array of candles with:
+# - Time (Unix timestamp)
+# - Open, High, Low, Close
+# - Volume (if available)
+```
+
+**Horizon Values:**
+- `1` — 1 minute
+- `5` — 5 minutes
+- `15` — 15 minutes
+- `60` — 1 hour
+- `1440` — 1 day
+- `10080` — 1 week
+
+## Request/Response Format
+
+All API calls follow the same pattern:
+
+```python
+# 1. Create request object
+r = module.endpoint.Method(params={...})
+
+# 2. Execute request
+client.request(r)
+
+# 3. Check status
+if r.status_code == 200:  # or 201 for orders
+    data = r.response
+else:
+    error = r.response  # Error details
+```
+
+## Error Handling
+
+```python
+try:
+    client.request(r)
+except saxo_openapi.exceptions.OpenAPIError as e:
+    print(f"API Error: {e}")
+    print(f"Status: {e.status_code}")
+    print(f"Message: {e.message}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Common Errors
+
+| Error Code | Message | Cause | Solution |
+|-----------|---------|-------|----------|
+| 401 | Unauthorized | Invalid/expired token | Refresh token |
+| 400 | Bad Request | Invalid parameters | Check order data |
+| 403 | Forbidden | Insufficient permissions | Check account permissions |
+| 429 | Too Many Requests | Rate limit exceeded | Slow down requests |
+| 500 | Internal Server Error | Saxo server issue | Retry with backoff |
+
+## Rate Limits
+
+Saxo enforces rate limits per endpoint category:
+
+| Category | Limit | Window |
+|----------|-------|--------|
+| **Trading** (orders) | 100 req | 1 minute |
+| **Portfolio** | 300 req | 1 minute |
+| **Prices** | 100 req | 1 minute |
+| **Chart** | 50 req | 1 minute |
+
+**Best Practices:**
+- Cache instrument searches (Uic lookup)
+- Batch position/order queries when possible
+- Use WebSocket for real-time prices (not polling)
+- Implement exponential backoff on 429 errors
+
+## WebSocket Streaming (Advanced)
+
+For real-time price feeds, use WebSocket streaming:
+
+```python
+# TODO: Agent should research and implement WebSocket streaming
+# when polling becomes a bottleneck or rate limits are hit.
+# See saxo_openapi documentation for streaming setup.
+```
+
+## Response Caching
+
+Cache responses that don't change frequently:
+
+```python
+# Cache instrument details (rarely change)
+instrument_cache = {}
+
+def get_instrument_details(uic, asset_type):
+    key = f"{uic}:{asset_type}"
+    if key not in instrument_cache:
+        r = rd.instruments.InstrumentDetails(Uic=uic, AssetType=asset_type)
+        client.request(r)
+        instrument_cache[key] = r.response
+    return instrument_cache[key]
+```
+
+## Agent Evolution Notes
+
+*(Add discoveries here as you use the API)*
+
+- Which endpoints are most rate-limited?
+- Best practices for batching requests?
+- WebSocket setup and benefits
+- Caching strategies that work
+- Error patterns and how to handle them

package/skills/saxo/references/asset-classes.md

@@ -0,0 +1,249 @@
+# Saxo Asset Classes
+
+> Agent-editable. Add notes about instruments you trade, quirks, best practices.
+
+Saxo covers 71,000+ instruments across all major asset classes except crypto.
+
+## Asset Type Codes
+
+Saxo uses string codes for asset types. Always specify the correct `AssetType` in orders and queries.
+
+| Asset Type Code | Description | Examples |
+|----------------|-------------|----------|
+| `FxSpot` | Spot Forex | EURUSD, GBPJPY, XAUUSD, XAGUSD |
+| `FxForwards` | Forex Forwards | Long-dated forex contracts |
+| `Stock` | Individual Stocks | AAPL, TSLA, VOO |
+| `StockIndex` | Stock Indexes | S&P 500, DAX |
+| `CfdOnStock` | Stock CFDs | Leveraged stock trading |
+| `CfdOnIndex` | Index CFDs | Leveraged index trading |
+| `CfdOnFutures` | Futures CFDs | Oil, gold futures |
+| `Bond` | Bonds | US Treasuries, corporate bonds |
+| `StockOption` | Equity Options | Call/put options on stocks |
+| `FxOption` | FX Options | Currency options |
+| `ContractFutures` | Futures Contracts | Commodities, indexes |
+
+## Forex (FxSpot)
+
+**Trading Hours:** 24/5 (Sunday 5pm ET — Friday 5pm ET)
+
+### Major Pairs (Highest Liquidity)
+
+| Pair | Uic | Description | Typical Spread | Sessions |
+|------|-----|-------------|---------------|----------|
+| EURUSD | 21 | Euro vs US Dollar | 0.1-0.5 pips | All |
+| GBPUSD | 22 | British Pound vs USD | 0.5-1.5 pips | London, NY |
+| USDJPY | 23 | US Dollar vs Japanese Yen | 0.2-0.8 pips | Tokyo, NY |
+| USDCHF | 24 | USD vs Swiss Franc | 0.5-1.5 pips | All |
+
+### Commodities (via FxSpot)
+
+| Pair | Uic | Description | Contract Size | Notes |
+|------|-----|-------------|--------------|-------|
+| XAUUSD | 1639 | Gold vs USD | 1 troy ounce | Most liquid |
+| XAGUSD | 1640 | Silver vs USD | 1 troy ounce | Higher volatility |
+| XPTUSD | — | Platinum vs USD | 1 troy ounce | Lower liquidity |
+| XPDUSD | — | Palladium vs USD | 1 troy ounce | Lower liquidity |
+
+**Key Points:**
+- Amount is in base currency units (EURUSD 10000 = 10k EUR)
+- Price quoted to 4-5 decimal places (pipettes)
+- Leverage typically 50:1 to 500:1 (check account settings)
+- Spreads widen during low liquidity (Asian session, holidays, news)
+- Best execution during session overlaps (London/NY)
+
+**Search Example:**
+```python
+params = {'Keywords': 'EURUSD', 'AssetTypes': 'FxSpot'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+## Stocks
+
+**Trading Hours:** Exchange-specific (NYSE: 9:30am-4pm ET, etc.)
+
+### Search by Exchange
+
+```python
+# Search US stocks
+params = {'Keywords': 'AAPL', 'AssetTypes': 'Stock', 'ExchangeId': 'NASDAQ'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Key Points:**
+- Amount is number of shares (integer for most, can be fractional for some)
+- Price in exchange currency (USD for US stocks, EUR for EU, etc.)
+- Leverage typically 4:1 to 10:1 (much lower than forex)
+- Commissions per trade (not just spread)
+- Check market hours — many exchanges have breaks or early closes
+- Extended hours available for some exchanges (pre-market, after-hours)
+
+**Common Exchanges:**
+- `NASDAQ` — US tech stocks (AAPL, MSFT, TSLA)
+- `NYSE` — US stocks (traditional companies)
+- `XETRA` — German stocks (DAX components)
+- `LSE` — London Stock Exchange
+
+## CFDs (Contracts for Difference)
+
+CFDs allow leveraged trading without owning the underlying asset.
+
+### Stock CFDs
+
+```python
+params = {'Keywords': 'AAPL', 'AssetTypes': 'CfdOnStock'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Key Points:**
+- Higher leverage than stocks (up to 20:1)
+- No ownership — purely price speculation
+- Overnight financing costs (rollover fees)
+- Lower capital requirements
+- Some jurisdictions restrict CFD trading
+
+### Index CFDs
+
+Trade stock indexes with leverage:
+
+```python
+params = {'Keywords': 'S&P 500', 'AssetTypes': 'CfdOnIndex'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Popular Indexes:**
+- SPX500 (S&P 500)
+- NAS100 (Nasdaq 100)
+- US30 (Dow Jones)
+- GER40 (DAX)
+
+## Bonds
+
+Fixed-income securities. Lower volatility than stocks or forex.
+
+```python
+params = {'Keywords': 'US Treasury', 'AssetTypes': 'Bond'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Key Points:**
+- Price quoted as percentage of par value
+- Yields move inverse to prices
+- Lower leverage (typically 2:1 to 5:1)
+- Less volatile — good for capital preservation
+- Interest rate sensitivity (duration)
+
+## Options
+
+Complex derivatives. High risk, high reward.
+
+### Stock Options
+
+```python
+params = {'Keywords': 'AAPL', 'AssetTypes': 'StockOption'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Key Points:**
+- Call = right to buy, Put = right to sell
+- Strike price and expiration date critical
+- Theta decay — options lose value over time
+- Implied volatility affects pricing
+- Can lose 100% of premium
+- Require options trading approval
+
+### FX Options
+
+```python
+params = {'Keywords': 'EURUSD', 'AssetTypes': 'FxOption'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+## Futures
+
+Contracts for future delivery of assets.
+
+```python
+params = {'Keywords': 'Crude Oil', 'AssetTypes': 'ContractFutures'}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+```
+
+**Key Points:**
+- Expiration dates — must close or roll before expiry
+- High leverage (10:1 to 50:1)
+- Margin calls if position moves against you
+- Contango/backwardation in commodity futures
+- Each contract has specific size (e.g., 1000 barrels of oil)
+
+## Instrument Discovery
+
+Always search before trading to get correct Uic:
+
+```python
+import saxo_openapi.endpoints.referencedata as rd
+
+# General search
+params = {
+    'Keywords': 'gold',
+    'AssetTypes': 'FxSpot,CfdOnFutures',
+    'limit': 20
+}
+r = rd.instruments.Instruments(params=params)
+client.request(r)
+
+# Get instrument details
+for inst in r.response['Data']:
+    print(f"{inst['Symbol']}: Uic={inst['Identifier']}, Type={inst['AssetType']}")
+```
+
+## Product Details
+
+Before trading any instrument, check its details:
+
+```python
+import saxo_openapi.endpoints.referencedata as rd
+
+r = rd.instruments.InstrumentDetails(Uic=21, AssetType='FxSpot')
+client.request(r)
+
+# Returns:
+# - MinimumTradeSize
+# - TickSize (price increment)
+# - ContractSize
+# - TradingStatus
+# - TradingHours
+# - MarginRequirement
+```
+
+## Session Times (Critical for Forex/Commodities)
+
+| Session | Hours (ET) | Best For |
+|---------|-----------|----------|
+| **Tokyo** | 7pm - 4am | JPY pairs |
+| **London** | 3am - 12pm | EUR, GBP pairs |
+| **New York** | 8am - 5pm | USD pairs |
+| **Overlap (London/NY)** | 8am - 12pm | Highest liquidity |
+
+**Avoid:**
+- Sunday open (5pm ET) — low liquidity, wide spreads
+- Friday close (5pm ET) — position squaring, unpredictable
+- Major holidays — Christmas, New Year, etc.
+- Low-liquidity hours — 5pm-7pm ET (Sydney only)
+
+## Agent Evolution Notes
+
+*(Add discoveries here as you trade different instruments)*
+
+- Best instruments for each strategy
+- Liquidity patterns: which sessions, which instruments?
+- Spread behavior: when do spreads widen?
+- Margin surprises: instruments with unexpectedly high requirements?
+- Correlation discoveries: which instruments move together?
+- Session-specific edges: patterns that only work in certain sessions?