Documentation
About stateXchange
stateXchange is an algorithmic trading platform for MCX commodities. It connects your TradingView strategies to your broker for automated trade execution.
Created by traders who code, stateXchange started as our own trading engine and is now available to traders who value execution as much as strategy.
Supported Instruments: All MCX futures including GOLD, GOLDM, SILVER, SILVERM, CRUDEOIL, NATURALGAS, COPPER, and more.
Supported Brokers: Sharekhan.
How It Works
stateXchange uses a simple flow:
- TradingView sends a webhook alert when your strategy generates a signal
- Signal receives the webhook and routes it to connected algos
- Algo checks if it should trade (position state, running status)
- Broker executes the order (live) or simulates it (paper)
Each component is independent: one signal can trigger multiple algos, each algo tracks its own position, and you can mix live and paper trading.
Step 1: Sign In
Click Continue with Replit on the landing page. This uses your Replit account (which supports Google, GitHub, etc.).
First-time users get a 7-day free trial to explore all features.
Step 2: Setup Broker Credentials
Go to Setup (click your initials in the top right, then "Setup").
Enter your Sharekhan API credentials:
- Sharekhan: API Key, Secret Key, Customer ID
Click Save Account to store your credentials securely.
Step 3: Connect Broker (Daily Login)
After saving credentials, you must connect to your broker. This is required daily before trading.
- Click Login button on the Setup page
- Complete login on Sharekhan website
- You'll be redirected back automatically
When connected, you'll see a green status indicator. Sessions expire at midnight and you'll need to reconnect the next day.
Step 4: Create a Signal
Go to Signals page from the top menu.
- Click + Create Signal
- Enter a descriptive name (e.g., "Gold Breakout Strategy")
- Click Create
Each signal gets a unique Webhook URL. Copy this URL - you'll paste it into TradingView.
Step 5: Create an Algo
Go to Algo page from the top menu.
- Click + Create Algo
- Fill in the settings:
| Signal | Select which signal triggers this algo |
| Broker | Sharekhan or Paper Trading |
| Instrument | MCX commodity (GOLDM, SILVERM, etc.) |
| Contract | Specific expiry date |
| Side | Long (profit when price rises) or Short (profit when price falls) |
| Lot Size | Number of lots per trade |
Click Create. The algo starts in Stopped status.
Step 6: Start the Algo
Click on your algo card to open it, then click Start Algo.
Status changes from "Stopped" to "Running". The algo is now ready to receive signals and execute trades.
Step 7: Configure TradingView
See the detailed TradingView Setup section below.
Important: TradingView paid subscription (Essential, Plus, or Premium) is required. Free accounts cannot use webhooks.
Signals
A Signal is the entry point for TradingView alerts. It has a unique webhook URL that receives incoming alerts.
Signal Status
| Active | Signal is enabled and will process incoming webhooks. Alerts are forwarded to connected algos. |
| Inactive | Signal is disabled. Incoming webhooks are ignored. Use this to pause a strategy without deleting it. |
Key Concepts
- One signal, multiple algos: A single signal can trigger multiple algos. For example, one TradingView strategy can trade GOLDM on multiple contracts simultaneously.
- Webhook URL: Unique URL for each signal. Never share this publicly.
- Alert Log: Every incoming webhook is logged for debugging.
How to Activate/Deactivate
On the Signals page, use the toggle switch next to each signal to activate or deactivate it. Inactive signals show a muted appearance.
Algos
An Algo is a trading configuration that links a signal to an instrument and broker. Each algo independently manages its position.
Algo Status
| Running | Algo is active and will execute trades when signals arrive. Shows green indicator. |
| Stopped | Algo is paused. Signals are ignored. No trades will execute. Shows gray indicator. |
Algo Settings
| Signal | Which webhook triggers this algo |
| Broker | Where to execute trades (Sharekhan or Paper) |
| Instrument | What to trade (GOLDM, SILVERM, CRUDEOIL, etc.) |
| Contract | Which expiry to trade |
| Side | Long (BUY to enter, SELL to exit) or Short (SELL to enter, BUY to exit) |
| Lot Size | Number of lots per trade |
When Can You Edit an Algo?
- Stopped + No Position: You can edit all settings
- Stopped + Has Position: Limited editing (cannot change instrument/contract)
- Running: Cannot edit. Stop the algo first.
Algo Actions
| Start | Begin accepting signals and executing trades |
| Stop | Pause the algo. Open positions remain open. |
| Reset | Only appears when algo status is "Error". Resets the algo back to "Stopped" status so you can start it again. |
| Delete | Remove the algo. Cannot delete if running or has open position. |
When Does Reset Appear?
The Reset button only appears when an algo encounters an error during execution (status shows "Error"). This can happen due to broker connectivity issues or order failures. After clicking Reset, the algo returns to "Stopped" status and you can start it again.
Positions & P&L
When an algo executes an ENTRY trade, a Position is created.
Position Information
- Entry Price: Price at which position was opened
- Entry Time: When the position was opened (IST)
Closing Positions
- Signal Exit: TradingView sends EXIT signal, algo closes position automatically
- Manual SqOff: Click "SqOff" button on the position to close manually
Position Actions
| SqOff | Square off (close) an open position manually. Places an exit order with the broker. |
| Retry | Only appears when position status is "Error". Attempts to re-place the failed order. Limited to 3 retries. |
When Does Retry Appear?
The Retry button only appears when an order fails to execute (position status shows "Error"). This can happen due to:
- Broker connectivity issues
- Insufficient margin
- Order rejection by exchange
Click Retry to attempt placing the order again. Each position has a maximum of 3 retry attempts. If all retries fail, you may need to place the order manually through your broker terminal.
Realized P&L
When a position is closed, the final P&L is calculated and stored. View historical P&L on the Reports page.
Reports
The Reports page shows your trading history and performance analytics.
Filters
- Date Range: Last 3 days, 7 days, MTD, YTD, or custom
- Instrument: Filter by specific commodity
- Mode: Live trades only, Paper trades only, or both
Summary Stats
- Total Trades: Number of completed round-trip trades
- Win Rate: Percentage of profitable trades
- Total P&L: Sum of all realized profits and losses
- Profit Factor: Gross profit / Gross loss
Trade Log
Detailed table of all trades with entry/exit prices, P&L, and timestamps. Download as CSV for further analysis.
Paper Trading (Forward Testing)
Test strategies without risking real money.
How It Works
- When you create an algo, select Paper Trading as the broker
- No broker connection required
- Trades are simulated at current market prices
- Positions and P&L are tracked separately from live trades
Use Cases
- Test a new strategy before going live
- Validate TradingView webhook setup
- Compare strategy performance across instruments
- Learn the platform without financial risk
Note: TradingView paid subscription is still required for webhooks even in paper mode.
TradingView Setup
Requirement: TradingView Essential, Plus, or Premium subscription. Free accounts cannot use webhooks.
Step 1: Modify Your PineScript
Add comment to your strategy entry and exit:
// For Long entries
strategy.entry("Long", strategy.long, comment="entry")
// For Long exits
strategy.close("Long", comment="exit")
Step 2: Create Alert
- On TradingView, right-click your chart and select Add Alert
- In Condition, select your strategy
- Select "Order fills only" as the trigger
- Check Webhook URL
- Paste your signal's webhook URL from stateXchange
Step 3: Set Alert Message
In the Message field, paste:
{"comment":"{{strategy.order.comment}}"}
Testing
After saving the alert, wait for your strategy to generate a signal. Check the Alert Log on the Signals page to verify webhooks are arriving.
Signal Flow
Understanding how signals are processed:
Entry Signal
- TradingView sends webhook with "entry" action
- Signal receives webhook (must be Active)
- Each connected algo checks:
- Is algo Running? If not, skip
- Does algo already have position? If yes, skip (no duplicate entries)
- Is broker connected? (for live mode)
- If all checks pass, order is placed
- Position is created when order fills
Exit Signal
- TradingView sends webhook with "exit" action
- Signal receives webhook (must be Active)
- Each connected algo checks:
- Is algo Running? If not, skip
- Does algo have an open position? If not, skip (nothing to exit)
- If checks pass, exit order is placed
- Position is closed, P&L is calculated
Why Signals Get Ignored
- Signal is Inactive
- Algo is Stopped
- ENTRY received but algo already has position
- EXIT received but algo has no position
- Broker not connected (live mode only)
Daily Routine
For live trading, follow this daily routine:
Before Market Opens (Before 9:00 AM IST)
- Log in to stateXchange
- Go to Setup
- Connect your broker (OAuth for Sharekhan)
- Verify green status indicator
- Check that your algos are Running
During Market Hours
- Monitor positions on Algo page
- Check Alert Log if trades aren't executing
- Use manual SqOff if needed
After Market Close
- Review closed positions
- Check Reports for daily P&L
At Midnight
Broker sessions expire automatically. You'll need to reconnect the next morning.
MCX Trading Hours: 9:00 AM - 11:30 PM IST (Monday to Friday)
FAQ
Why is my signal being ignored?
- Signal is Inactive: Activate the signal on Signals page
- Algo is Stopped: Start the algo on Algo page
- Duplicate Entry: Algo already has position, ignores second entry
- Exit without position: No position to close
Why did my order fail?
- Broker not connected: Connect via Setup
- Insufficient margin: Add funds to trading account
- Market closed: MCX: 9:00 AM - 11:30 PM IST
- Invalid contract: Contract may have expired, update in algo settings
What is Long vs Short?
- Long: BUY to enter, SELL to exit. Profit when price goes UP.
- Short: SELL to enter, BUY to exit. Profit when price goes DOWN.
Can I run multiple algos on same signal?
Yes. One signal can trigger multiple algos. Each algo manages its position independently. Use this to trade same strategy on different brokers or instruments.
How do I close a position manually?
Open the algo, find the position card, and click SqOff (Square Off).
Do I need TradingView paid plan?
Yes. Webhook alerts require TradingView Essential ($14.95/month), Plus, or Premium subscription.
How often do I need to login?
Broker sessions expire at midnight IST. Connect every morning before trading.
What happens if I sign out of stateXchange?
Your broker session stays connected. Signing out of stateXchange does not disconnect your broker. Sessions only reset at midnight.
Can I edit a running algo?
No. Stop the algo first, make changes, then start it again.