MT Paste API Doc

Enabling the Paste API

The Paste API is off by default. Two conditions must both be true, or pasted JSON is silently ignored (see Results and errors):

• Premium subscription. The Paste API, like all of Medved Trader's APIs, requires a Premium subscription. A trial subscription includes it. Without it, the Paste API section of the settings page is greyed out.
• Enable PASTE API is checked in Medved Trader Settings → App → API. To change settings on that page you have to enter your Medved Trader account password (or your PIN, if you log in with a social login).

Once it is enabled, the Copy for Paste API item appears on the hotkey list's right-click menu.

How a payload is processed

1. Delivery. The text arrives at one trading window, by clipboard paste or WM_COPYDATA. After leading and trailing whitespace is trimmed, it must start with { or [. Anything else is treated as an ordinary paste, e.g. a symbol.
2. Gate. The window must be a trading window: Chart, Level II, DOM, Trade Ticket or Account. The Paste API must also be enabled. If either condition fails, the JSON is dropped without any message.
3. Password. Every statement must carry a valid Pwd.
4. Echo. If the statement asks for it, the window's current state is sent back to you. This happens before any command runs (see EchoTo).
5. Split. The payload is split into statements and commands. Disabled commands are removed. Orders for a different account or symbol are separated out, so each can be sent to its own account (see Order).
6. Evaluate and run. Vars are evaluated against the window's current state. Then each command's expressions are evaluated, and the commands run in order.

Commands run asynchronously on a background hotkey thread. Nothing is returned to the caller except the WM_COPYDATA accept/reject result and any echo you asked for. Errors are shown to the user in the target window.

Clipboard paste

Put the JSON on the clipboard as text (CF_UNICODETEXT / CF_TEXT). Then make MT paste it into a trading window by doing either of the following:

• Give the window focus and send Ctrl+V (or whatever key is assigned to the Paste keyboard shortcut).
• Use the window's Paste context-menu item, where it has one (Chart).

The paste goes to the window that has focus. On Trade Ticket and Level II windows, if the cursor is in a text box of the ticket (quantity, price…), the paste goes into that box as ordinary text. It is not treated as a Paste API payload.

WM_COPYDATA

Send a WM_COPYDATA (0x004A) message straight to the trading window's handle. The window does not need focus.

Use the normal Win32 enumeration functions (EnumWindows, FindWindow, matching on the window caption). Once you have talked to a window, the handle field of any echo gives you its handle. A handle stays valid until the window is closed; it is not preserved across layout reloads or restarts.

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
struct COPYDATASTRUCT { public IntPtr dwData; public int cbData; public string lpData; }

[DllImport("user32.dll", CharSet = CharSet.Unicode)]
static extern IntPtr SendMessage(IntPtr hWnd, int msg, IntPtr wParam, ref COPYDATASTRUCT cds);
const int WM_COPYDATA = 0x004A;

static bool SendPaste(IntPtr mtWindow, string json)
{
    var cds = new COPYDATASTRUCT { dwData = (IntPtr)1, cbData = (json.Length + 1) * 2, lpData = json };
    return SendMessage(mtWindow, WM_COPYDATA, IntPtr.Zero, ref cds) == (IntPtr)1;
}

Password (Pwd)

Every pasted payload must authenticate:

• A single-object payload carries "Pwd" at its top level.
• An array payload needs "Pwd" in every element.

The value is the password you use to log into Medved Trader. If you log in with a social login, which has no application password, it is your PIN instead.

• A wrong password rejects the whole payload after a 1-second delay, and the window shows "PASTE Error : Invalid Password".
• For a social login, three consecutive failures lock the API out until Medved Trader is restarted or you log in again. Until then even the correct PIN is refused.
• A valid Pwd also takes the place of the per-account trading authorization prompt, but only for the next second. If a payload has Delay steps that push an order past that second, the user may be prompted to authorize the account.

Results and errors

The Paste API has no response channel. Here is what you can observe:

• Rejected before processing (not enabled, not a trading window, not JSON): nothing happens. WM_COPYDATA returns 0.
• Password or payload errors: an error tooltip on the target window, e.g. "PASTE Error : Invalid Password" or "Hotkey Error: …".
• Command errors, e.g. an invalid expression, quantity 0, or an account that is not started: an error tooltip on the window. If the window is gone, a notification pop-up appears instead.
• Order outcome: watch it the same way you would for a manual order, in the Account window. Or use the WebSocket API's tradeCommandUpdate / transactionsUpdate.

If EchoTo is set, the echo tells you the payload got past the password check. That is the only confirmation you get back.

Statements

A payload is one statement object, a JSON array of statements, or several statement objects placed one after another. A statement is exactly what the Hotkey editor saves for one hotkey.

Separate, SeparateSym and ALREADYAUTH are reserved for internal use. Do not send them.

{
  "Pwd": "mypassword",
  "Command": {
    "Disabled": false,
    "Order": {
      "Send": "true",
      "Legs": [ { "Action": "Buy", "OrderType": "Limit", "Quantity": "100", "LimitPrice": "Ask" } ]
    }
  }
}

Command objects

Each command object holds one action key (Order, Cancel, TradeQty, …), plus these optional envelope keys:

Value types

Almost every value is a string, even numbers and booleans ("Quantity": "100", "Drop": "true"). Nearly every string value is an expression that MT evaluates against the window's current state. So "Ask+0.05", "round(PosAbs/2)" and "100" are all valid quantities or prices.

Send and Drop accept either a string ("true", "false", "CancelThenSend"…, in any letter case) or a JSON boolean (true / false).

Key names are case-sensitive, e.g. LimitPrice, not limitprice. Write enumeration values in order legs (Action, OrderType, TIF, ConditionalType) exactly as they are listed under Enumerations. Variable and function names inside expressions are not case-sensitive.

Order

Builds an order and drops it into the window, sends it to the broker, or both.

• On Trade Ticket and Level II windows, an Order must have Drop or Send. A payload may drop at most one order there.
• If the window has trading disabled (no account selected), any command that uses the window's account is refused.

Order Legs

Conditional orders. In a conditional order (OTA, OTOCA…), a secondary leg's price can be an offset from the main leg's limit or stop price. For a main leg with no price (Market…), the base is the last trade.

Leave a field out rather than writing "Default"; the Hotkey editor never writes "Default" into a leg.

Cancel

{ "Pwd": "mypassword", "Command": { "Disabled": false, "Cancel": { "Open": "All", "Unsent": "None" } } }

Flatten

Cancels the working orders and closes the position with a market order.

ChangeOrder

Modifies existing orders or dropped capsules in the window. Its expressions are evaluated once for each order the change applies to. While they are evaluated, these variables are set from that order: OrderQty, OrderPrice, OrderType, OrderIsBuy, OrderIsSell, OrderIsUnsent, CurrentTIF.

{ "Pwd": "mypassword", "Command": { "Disabled": false,
  "ChangeOrder": { "AppliesTo": "All", "NewPrice": "+0.02", "Send": "true" } } }

TradeQty / Account / Symbol

These change the window itself. Each takes a single string value, directly on the command object:

A symbol or account change can itself trigger an echo.

Other actions

Chart-only actions

{ "Pwd": "mypassword", "Command": { "ShowFills": "toggle" } }

Account-only actions

These work only on an Account window. Sent anywhere else, including the global hotkey window, they are refused with "TransFilter only works on the Account window."

{ "Pwd": "mypassword", "Command": { "TransFilter": { "Status": "AllOpen" } } }

Syntax

String values are evaluated as C#-style expressions (+ - * / %, comparisons, && || !, ? :). The syntax is relaxed:

• A leading = is optional: "=Ask+0.01" and "Ask+0.01" are the same.
• if A then B else C is allowed, and must be complete. and, or and not are allowed. = means equality, and <> means not-equal.
• Strings may use single quotes: 'Buy'. Dates can be written as M/d/yyyy.
• Variable and function names are not case-sensitive.
• A bare word that is not a variable is taken as text. This is how symbol, route and TIF names pass through unchanged.

Numbers are decimals. A condition is true when it is non-zero.

Offsets and pegs

A price expression without a sign is an absolute price: "Bid-0.01" is a price, while "-0.01" is an offset.

Functions

Variables

Variables come from the target window's current symbol, account and state. Mouse and capsule variables only make sense on a Chart or DOM with the mouse over it; outside that they are 0, and an order that uses them is refused.

Vars and If

Vars declares your own variables, which the commands can then use by name. They are evaluated in order, so a later variable can use an earlier one. Global Vars defined in the Hotkey editor are evaluated first. An optional If member (one object or an array) sets variables conditionally:

"Vars": {
  "Half": "round(PosAbs/2)",
  "Side": "if Pos > 0 then 'Sell' else 'Buy'",
  "If": [
    { "Condition": "PreMarket or AfterMarket", "Then": { "Tif": "'Day_ext'" }, "Else": { "Tif": "'Day'" } }
  ]
}

Inside Then / Else, values must be strings: "5", not 5. Numeric JSON values there are ignored.

EchoTo

A statement can ask the target window to report its current state back to you. That report is the echo. It is produced when the statement has passed the password check, and before its commands run.

For "hwnd", MT sends (not posts) WM_COPYDATA with dwData = 1 and lpData = the echo JSON as a NUL-terminated UTF-16 string. Handle it promptly, because MT's window waits while you process it.

A payload that MT splits into several statements (for example, orders for several accounts) can produce more than one echo.

{ "Pwd": "mypassword", "EchoTo": "hwnd", "hwnd": 3148874, "EchoClientMsg": { "id": "q1" },
  "Command": { "Disabled": false, "TradeQty": "DefaultQty" } }

A statement needs at least one command that is not disabled, or it is dropped before any echo is made. Setting TradeQty to DefaultQty changes nothing, so it works as a harmless placeholder command.

Change notifications

Add a Change list to a statement that has EchoTo and EchoClientMsg. It can contain any of Symbol, Account, TradeQty, or All, e.g. "Change": "Symbol,TradeQty". From then on, whenever a trading window's symbol, account or trade quantity changes, it sends an echo to the same destination, with "Change" set to "symbol", "account" or "tradeqty".

• The subscription is global. It covers every trading window, not just the one you pasted into.
• Only one subscription exists at a time: the latest EchoTo received replaces it.
• To stop notifications, send a statement with EchoTo and "Change": "None".
• Subscriptions do not survive a Medved Trader restart.

Echo payload

{
  "window": "LevelIIWindow", "handle": "2951610", "symbol": "BAC",
  "data": { "sym": "BAC", "companyName": "Bank of America Corp", "bid": "46.12", "ask": "46.13", "last": "46.12", "…": "…" },
  "tradeAccount": { "tradingSite": "SCHWAB", "accountID": "12345678", "accountName": "Main", "accountKey": "SCHWAB:12345678" },
  "TradeQty": 100,
  "Change": "symbol",
  "ClientMsg": { "id": "q1" }
}

Per-window behaviour

Examples

{
  "Pwd": "mypassword",
  "Vars": { "Half": "round(PosAbs/2)" },
  "Command": { "Disabled": false, "Order": { "Send": "true",
    "Legs": [ { "Action": "Sell", "OrderType": "Limit", "Quantity": "Half", "LimitPrice": "Ask-0.01", "TIF": "Day" } ] } }
}

{
  "Pwd": "mypassword",
  "Command": { "Disabled": false, "Order": { "Send": "CancelThenSend", "ConditionalType": "OTOCA",
    "Legs": [
      { "Action": "Buy",  "OrderType": "Limit",      "Quantity": "DefaultQty", "LimitPrice": "Ask" },
      { "Action": "Sell", "OrderType": "Limit",      "LimitPrice": "+0.50" },
      { "Action": "Sell", "OrderType": "StopMarket", "StopPrice": "-0.25" }
    ] } }
}

{
  "Pwd": "mypassword",
  "Command": [
    { "Disabled": false, "Symbol": "AAPL" },
    { "Disabled": false, "TradeQty": "50" },
    { "Disabled": false, "Order": { "Drop": "true", "Send": "false",
      "Legs": [ { "Action": "Buy", "OrderType": "Limit", "LimitPrice": "Bid" } ] } }
  ]
}

{ "Pwd": "mypassword", "Command": { "Disabled": false,
  "Flatten": { "Account": "SCHWAB:12345678", "Symbol": "AllSymbols", "Position": "Both" } } }

Enumerations