MetaScalp API

MetaScalp exposes a local API that lets your scripts and bots interact with connected exchanges. Use HTTP REST endpoints for request/response operations and WebSocket for real-time streaming of orders, positions, balances, trades, and order book data.

• Host: 127.0.0.1 (localhost only)
• HTTP port range: 17845–17855 (first available)
• WebSocket: Same port as HTTP (upgrade requests accepted automatically)
• Content-Type: application/json
• CORS: All responses include Access-Control-Allow-Origin: *.

Overview

HTTP REST endpoints

Use HTTP to discover connections, query data, and execute trades:

WebSocket streaming

Connect via WebSocket to receive real-time updates for your exchange connections.

• Connect to ws://127.0.0.1:{port}/ (same port as HTTP — scan 17845–17855)
• Connection-level: Send subscribe with a connection ID to receive order, position, balance, and finres updates
• Market data: Send trade_subscribe, orderbook_subscribe, mark_price_subscribe, or funding_subscribe with connection ID + ticker to receive trade, order book, mark price, or funding updates
• Signal level subscriptions: Send signal_level_subscribe to receive signal level events (no connection ID required)
• You can subscribe to multiple connections and tickers simultaneously
• All subscriptions are automatically cleaned up when you disconnect

Getting started

1. Launch MetaScalp — both HTTP and WebSocket servers start automatically.

2. Discover the port — scan 17845–17855 with GET /ping.

3. List connections — call GET /api/connections to see available exchange connections.

4. Execute operations — use a connection ID for REST queries or WebSocket subscriptions.

Typical REST client flow

GET /ping                                         → find MetaScalp
GET /api/connections                              → list active connections
GET /api/connections/{id}/tickers                 → get available tickers
GET /api/connections/{id}/balance                 → check balances
GET /api/connections/{id}/orders?Ticker=BTCUSDT   → view open orders
POST /api/connections/{id}/orders                 → place an order
POST /api/connections/{id}/orders/cancel          → cancel an order
POST /api/connections/{id}/orders/cancel-all      → cancel all orders for a ticker
GET  /api/connections/{id}/cluster-snapshot        → get cluster snapshot data
GET  /api/connections/{id}/signal-levels?Ticker=   → list signal levels
POST /api/connections/{id}/signal-levels           → place a signal level
DELETE /api/connections/{id}/signal-levels/{slId}  → remove a signal level
GET  /api/connections/{id}/orderbook-settings?Ticker= → get orderbook settings
PUT  /api/connections/{id}/orderbook-settings?Ticker= → update orderbook settings

Typical WebSocket client flow

1. Connect
ws = new WebSocket("ws://127.0.0.1:17845/")

2. Subscribe to a connection (orders, positions, balances, finres)
ws.send('{"Type":"subscribe","Data":{"ConnectionId":1}}')
← {"Type":"subscribed","Data":{"ConnectionId":1}}

3. Subscribe to market data for a specific ticker
ws.send('{"Type":"trade_subscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","ZoomIndex":1}}')
← {"Type":"trade_subscribed","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","ZoomIndex":1}}
ws.send('{"Type":"orderbook_subscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","ZoomIndex":0,"DepthLevels":50,"DepthPercent":0.5}}')
← {"Type":"orderbook_subscribed","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","ZoomIndex":0,"DepthLevels":50,"DepthPercent":0.5}}
ws.send('{"Type":"mark_price_subscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
← {"Type":"mark_price_subscribed","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}
ws.send('{"Type":"funding_subscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
← {"Type":"funding_subscribed","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}

4. Subscribe to signal levels
ws.send('{"Type":"signal_level_subscribe","Data":{}}')
← {"Type":"signal_level_subscribed","Data":{}}
← {"Type":"signal_levels_snapshot","Data":{"SignalLevels":[...]}}

5. Receive real-time updates
← {"Type":"order_update","Data":{"ConnectionId":1,"OrderId":123,...}}
← {"Type":"position_update","Data":{"ConnectionId":1,...}}
← {"Type":"balance_update","Data":{"ConnectionId":1,"Balances":[...]}}
← {"Type":"finres_update","Data":{"ConnectionId":1,"Finreses":[...]}}
← {"Type":"trade_update","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","Trades":[...]}}
← {"Type":"orderbook_snapshot","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","Asks":[...],"Bids":[...],...}}
← {"Type":"orderbook_update","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","Updates":[...]}}
← {"Type":"mark_price_update","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","MarkPrice":65123.5}}
← {"Type":"funding_update","Data":{"ConnectionId":1,"Ticker":"BTCUSDT","FundingRate":0.0001,"FundingTime":"2026-03-16T16:00:00+00:00"}}
← {"Type":"signal_level_placed","Data":{"Id":1,"ConnectionId":1,"Ticker":"BTCUSDT","Price":95000,...}}
← {"Type":"signal_level_triggered","Data":{"Id":1,"TriggerTime":"2026-04-13T..."}}

6. Unsubscribe when done
ws.send('{"Type":"signal_level_unsubscribe","Data":{}}')
ws.send('{"Type":"trade_unsubscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
ws.send('{"Type":"orderbook_unsubscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
ws.send('{"Type":"mark_price_unsubscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
ws.send('{"Type":"funding_unsubscribe","Data":{"ConnectionId":1,"Ticker":"BTCUSDT"}}')
ws.send('{"Type":"unsubscribe","Data":{"ConnectionId":1}}')
← {"Type":"unsubscribed","Data":{"ConnectionId":1}}

WebSocket message reference

Messages you send

Messages you receive

For complete endpoint documentation with request/response details, field descriptions, and integration examples, see the interactive panels above or download the Markdown file.