An agent skill for trading on SimpleFX — Forex, Crypto, Stocks, Commodities, and Indices. Works with any SKILL.md-compatible agent platform (Claude Code, Cursor, OpenClaw, and others).

This skill lets AI agents trade on your behalf through SimpleFX's public REST API. You provide your API credentials, and the agent can:

• Check prices — real-time quotes for any instrument
• Open trades — market orders with optional take-profit and stop-loss
• Manage positions — view, update TP/SL, partial close, close all
• Place pending orders — limit/stop orders that trigger at a target price
• View history — closed positions and past trades
• Analyze markets — OHLCV candles, instrument search, all prices
• Monitor accounts — balance, equity, margin, free margin

Supports both DEMO and LIVE accounts. Defaults to DEMO for safety.

Log in to the SimpleFX Web App, go to Settings → API Keys, and create a new key pair. Make sure to enable the required permissions (at minimum: account read, trading, and market data). You'll get an API Key ID and an API Secret.

export SIMPLEFX_API_KEY_ID="your-api-key-id"
export SIMPLEFX_API_SECRET="your-api-secret"

Option A — via CLI:

GitHub shorthand:

npx skills add SimpleFXcom/simplefx-trading-skill -g -y

Or full GitHub URL:

npx skills add https://github.com/SimpleFXcom/simplefx-trading-skill -g -y

Option B — manual install:

Clone or copy this repo to your agent platform's skill directory:

On first use, the agent will run account.ts list to find your trading accounts. Pick one and set:

export SIMPLEFX_LOGIN="1233456"       # your account number
export SIMPLEFX_REALITY="DEMO"       # DEMO or LIVE

Just talk to your agent naturally:

User: "What's the price of Bitcoin?"
Agent: BTCUSD — Bid: 97,150.20, Ask: 97,185.50

User: "Buy 0.01 BTC"
Agent: Opening BUY 0.01 BTCUSD at ~97,185.50. Confirm?
User: "Yes"
Agent: Done! Position #12345 opened at 97,183.40. Margin used: $97.18

User: "Set stop loss at 95,000"
Agent: Updated position #12345 — SL set to 95,000.00

User: "Show my positions"
Agent: 1 open position:
  #12345 BTCUSD BUY 0.01 @ 97,183.40 | P/L: +$12.30 | SL: 95,000

User: "Close it"
Agent: Closed position #12345 at 97,195.70. Profit: +$12.30

The skill consists of TypeScript scripts that the agent runs via npx tsx. Each script handles one area:

simplefx-trading-skill/
├── SKILL.md              # Agent instructions — commands, logic, safety rules
├── _meta.json            # Package metadata
├── references/
│   └── errors.md         # Error codes and recovery guide
└── scripts/
    ├── lib/
    │   ├── api.ts        # HTTP client, auth, multi-server routing
    │   └── output.ts     # Structured JSON output helpers
    ├── account.ts        # List accounts, check status
    ├── market.ts         # Instruments, prices, candles
    ├── trade.ts          # Open market orders, update TP/SL
    ├── pending.ts        # Place/modify/cancel pending orders
    └── positions.ts      # Active positions, history, close operations

Every script outputs structured JSON:

{"ok": true, "data": { "quotes": [...] }}

{"ok": false, "error": "MISSING_ENV", "error_message": "..."}

The agent reads SKILL.md, maps your request to the right script, runs it, and interprets the result.

• Node.js 18+ (for npx tsx and built-in fetch)
• A SimpleFX account with API key and secret

No other dependencies. The scripts use only Node.js built-in modules (fs, os, path). The tsx TypeScript runner is fetched automatically by npx on first use.

• DEMO by default — the skill defaults to your demo account, so you can't accidentally trade real money
• Confirmation prompts — the agent always confirms before executing trades on LIVE accounts
• Hedging mode — FIFO is off by default, so new trades won't close your existing positions
• Token security — the auth token is cached in a temp file with 0600 permissions (owner-only access) and expires after 55 minutes
• No withdrawal API — SimpleFX API keys cannot withdraw funds; they can only trade
• Context window protection — all list outputs are capped by default to prevent flooding the agent's context

SimpleFX offers CFD trading on:

Apache License 2.0