Copy trading
Copy positions from one of your accounts to another, ticket by ticket, on the gateway's own terminals: stops follow, partial closes follow, risk caps and a daily guard protect the receiving account, and every step is an event.
Updated
What it does
- A leader account's positions are copied to a master account of the same client. Each leader position opens exactly one position on the master; that pair is a link with a leader ticket, a master ticket and a status. There is no netting of several leader positions into one.
- Leader and master can be on different brokers and servers: a symbol map translates the symbol names, and the volume is rounded to the master symbol's own step.
- The gateway's own terminals read the leader and trade the master. Nothing runs on your side — no EA, no script, no terminal — and copying continues while your software is offline.
- The master must be a hedging account (several positions per symbol), because every copy is its own position. Netting accounts are refused.
Register a master
PUT /v1/copy/masters/{accountId} turns one of your accounts into a copy master. The account must use the HEDGING margin mode and the gateway must already know it — run a check (or activate the account) before registering it; an account whose margin mode is unknown or NETTING is refused. Copies trade with the master password, so the account needs it stored (an investor password can read, not trade).
| Field | Rule |
|---|---|
status | ACTIVE (copies open and are followed), CLOSE_ONLY (existing copies are followed and closed, none opens) or DISABLED. |
dailyLossLimit | In the account currency, or null. When the master's loss since the start of its day reaches it, the master goes CLOSE_ONLY until the next day (dayStartBalance / dayStartAt in the answer show the running day). |
maxTotalLots | The most lots all open copies on this master may add up to, or null. A copy that would exceed it is SKIPPED_CAP. |
- Only the fields you send change. A PUT with the limits alone never re-opens a master the daily guard closed: send
statusexplicitly to change it. GET /v1/copy/mastersandGET /v1/copy/masters/{accountId}return each master with itsaccount(login, platform, server, states, currency, marginMode) andlinkscounters (open, closed, failed, skipped, openLots).
# register (or change) a copy master; only the fields you send change
curl -X PUT https://api.propmetaapi.com/v1/copy/masters/$MASTER_ID -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{
"status": "ACTIVE",
"dailyLossLimit": 500,
"maxTotalLots": 5
}'
# → { "accountId": "…", "status": "ACTIVE", "dailyLossLimit": 500, "maxTotalLots": 5,
# "dayStartBalance": 10000, "dayStartAt": "2026-10-28T00:00:00.000Z",
# "account": { "login": "123456", "platform": "MT5", "server": "Broker-Live", "desiredState": "ACTIVE",
# "runtimeState": "CONNECTED", "currency": "USD", "marginMode": "HEDGING" },
# "links": { "open": 0, "closed": 0, "failed": 0, "skipped": 0, "openLots": 0 }, … }
curl https://api.propmetaapi.com/v1/copy/masters -H "Authorization: Bearer $GW_KEY" # every master, with account and links counters
curl https://api.propmetaapi.com/v1/copy/masters/$MASTER_ID -H "Authorization: Bearer $GW_KEY"Allocations
An allocation says which leader is copied to which master and how. PUT /v1/copy/allocations/{externalId} creates or changes it under an id you choose:
| Field | Rule |
|---|---|
leaderAccountId | required — the account whose positions are copied (any of your accounts, also an investor-password one). |
masterAccountId | required — a registered copy master. Leader ≠ master; no cycles (a master of this allocation cannot lead back to its leader). |
volumeRatio | required, > 0 — copy lots = leader lots × ratio (0.25, 1, 2 …), rounded to the master symbol's volumeStep and never below its volumeMin (else SKIPPED_TOO_SMALL). |
reverse | false (default) or true: a leader BUY opens a SELL on the master and the other way round. |
copySlTp | true (default): the leader's stop loss and take profit are set on the copy and followed. false: the copy runs without stops. |
symbolInclude | Leader symbols to copy (array, empty = all). Names as on the leader's server. |
symbolExclude | Leader symbols never copied (array). Checked after symbolInclude. |
maxOpenLots | The most lots this allocation may keep open on the master at once, or null (SKIPPED_CAP when reached). |
maxSlippagePoints | The copy is refused (FAILED) when the master's price at the moment of the order moved more than this many points from the leader's open price. null: no check. |
mode | ACTIVE, CLOSE_ONLY (default for a new allocation) or PAUSED — see Modes below. |
version | required, integer — your version of these settings. It must increase on every change: the same version is a no-op (200, nothing changes), an older one is 409 STATE_CONFLICT. |
leaderAccountIdandmasterAccountIdcannot change while the allocation has open copies (409 STATE_CONFLICT withopenLinks): switch it CLOSE_ONLY, wait for the copies to close, then change them.- Several allocations may share a leader (one leader → many masters) or a master (many leaders → one master); each one has its own counters and caps, and the master's
maxTotalLotscaps all of them together.
# copy a quarter of the leader's lots, stops included, majors only, at most 2 lots open, refuse a copy 30 points away
curl -X PUT https://api.propmetaapi.com/v1/copy/allocations/alloc-1 -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{
"leaderAccountId": "$LEADER_ID",
"masterAccountId": "$MASTER_ID",
"volumeRatio": 0.25,
"reverse": false,
"copySlTp": true,
"symbolInclude": ["EURUSD", "GBPUSD", "USDJPY"],
"symbolExclude": [],
"maxOpenLots": 2,
"maxSlippagePoints": 30,
"mode": "ACTIVE",
"version": 1
}'
# → { "id": "…", "externalId": "alloc-1", "mode": "ACTIVE", "activatedAt": "2026-10-28T09:15:02.311Z", "version": 1,
# "links": { "open": 0, "closed": 0, "failed": 0, "skipped": 0, "openLots": 0 }, … }
# the same body with "version": 1 again: 200, nothing changes; "version": 0: 409 STATE_CONFLICT
curl "https://api.propmetaapi.com/v1/copy/allocations?master=$MASTER_ID&mode=ACTIVE" -H "Authorization: Bearer $GW_KEY" # filters: leader, master, mode
curl https://api.propmetaapi.com/v1/copy/allocations/alloc-1 -H "Authorization: Bearer $GW_KEY"Modes
POST /v1/copy/allocations/{externalId}/mode switches the mode without touching the other settings or the version. A new allocation starts CLOSE_ONLY unless you send mode ACTIVE in the PUT. Switching to ACTIVE records activatedAt: only leader positions opened after that moment are copied — positions the leader already had are never picked up.
curl -X POST https://api.propmetaapi.com/v1/copy/allocations/alloc-1/mode -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{ "mode": "CLOSE_ONLY" }'
# ACTIVE new leader positions (opened from now on) are copied; open copies are followed
# CLOSE_ONLY open copies are still followed and closed with the leader; nothing new opens
# PAUSED nothing happens at all — open copies are not followed eitherGET /v1/copy/allocations lists them (filters leader, master, mode), GET /v1/copy/allocations/{externalId} reads one, DELETE removes one:
# only without open copies; otherwise 409 with the open links in "openLinks"
curl -X DELETE https://api.propmetaapi.com/v1/copy/allocations/alloc-1 -H "Authorization: Bearer $GW_KEY"
# Its links go with it; the copy log stays.Link lifecycle
A link is created the moment the gateway sees a new leader position and ends in one of the terminal states. GET /v1/copy/links shows them with leader and master tickets, volumes (opened and closed), the last confirmed stops, retries and error.
| Status | Meaning |
|---|---|
PENDING_OPEN | The leader opened a position and the order for the copy is on its way to the master. |
OPEN | The copy is open on the master (masterPositionId) and is followed. |
PENDING_CLOSE | The leader closed (part of) the position; the close is on its way to the master. |
CLOSED | The copy was closed because the leader closed its position (the OUT deal in the leader's history proves the close). |
CLOSED_BY_MASTER | The master position was closed on its own side — by its stop loss / take profit, by hand in a terminal or by another API call — proven by an OUT deal on the master. The leader position is left alone. |
FAILED | The open or the close could not be done, e.g. LOST_BEFORE_SEND (the leader position was already gone when the order was about to be sent), a slippage refusal or a broker error code in error. |
ORPHANED | No leader data for 5 minutes (the leader's terminal is disconnected). The copy stays open; nothing is closed automatically. The link returns to OPEN when the leader's data is back. |
SKIPPED | Not copied on purpose. error says why: SKIPPED_FILTER (symbol filter), SKIPPED_SYMBOL (no symbol spec on the master — add a symbol map), SKIPPED_TOO_SMALL (below volumeMin after rounding), SKIPPED_CAP (maxOpenLots / maxTotalLots), SKIPPED_RISK_BLOCKED (a risk rule blocks trading on the master). |
The usual path is PENDING_OPEN → OPEN → (PENDING_CLOSE) → CLOSED. PENDING_OPEN, OPEN, PENDING_CLOSE and ORPHANED are the "open" states a DELETE of the allocation refuses on; CLOSED, CLOSED_BY_MASTER, FAILED and SKIPPED are final.
What is followed while a copy is open
- Stop loss / take profit. With
copySlTpthe leader's SL/TP changes are sent to the master; once the master confirms them the link'slastSl/lastTpandslTpVersionmove and COPY_MODIFIED is raised. A failed modify is retried after a minute with a new version. - Partial closes. When the leader closes part of the position, the same fraction is closed on the master, rounded to the master symbol's volumeStep.
leaderClosedVolumeandmasterClosedVolumeon the link add up what was closed so far. - The full close. The OUT deal in the leader's history proves the close (a position that merely disappears from the list is not enough); the master position is then closed and the link is CLOSED.
- A close on the master side. When the copy is closed on the master — by its own SL/TP, by hand or by another call — the OUT deal on the master is detected, the link becomes CLOSED_BY_MASTER and COPY_CLOSED carries reason CLOSED_BY_MASTER. The leader position is not touched.
- The master's daily guard. When the master's loss since its day start reaches
dailyLossLimit, the master goes CLOSE_ONLY for the rest of the day: open copies are still followed and closed, nothing new opens.
Symbol maps
When leader and master are on different servers, the same instrument often has different names (XAUUSD vs GOLD, EURUSD vs EURUSD.m). A symbol map translates them per client: one list for all your allocations, keyed by the servers. Without a matching entry the leader's symbol name is used as is; when the master's server has no such symbol the copy is SKIPPED_SYMBOL.
# the symbol map of your client; without an entry the same symbol name is used
curl -X PUT https://api.propmetaapi.com/v1/copy/symbol-maps -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{
"items": [
{ "fromServer": "BrokerA-Live", "fromSymbol": "XAUUSD", "toServer": "BrokerB-Real", "toSymbol": "GOLD" },
{ "fromServer": "BrokerA-Live", "fromSymbol": "EURUSD", "toServer": "BrokerB-Real", "toSymbol": "EURUSD.m" }
]
}'Events and reconciliation
Every step raises an event. The payload carries allocation (the externalId), leaderPosition, masterPosition and, where it applies, reason:
| Event | When / payload |
|---|---|
COPY_OPENED | The copy is open: allocation, leaderPosition, masterPosition, symbol, side, volume. |
COPY_MODIFIED | The master confirmed a stop change: sl, tp, version — sent once per confirmed change, not per attempt. |
COPY_CLOSED | The copy is closed. reason: null (the leader closed), ALREADY_CLOSED (it was gone when the close was sent) or CLOSED_BY_MASTER. |
COPY_SKIPPED | The leader position was not copied; reason is one of the SKIPPED_* codes above. |
COPY_FAILED | The open or close failed; reason is the error (LOST_BEFORE_SEND, a broker code …). |
{
"id": "48311", "type": "COPY_CLOSED", "accountId": "$MASTER_ID", "occurredAt": "2026-10-28T11:40:19.207Z",
"allocation": "alloc-1", "leaderPosition": "51234567", "masterPosition": "88811223", "reason": null
}Deliver them with a webhook or read them from GET /v1/events. For reconciliation, page through GET /v1/copy/links (limit ≤ 500, pass nextCursor back as cursor; status takes one status or a comma-separated list) and the copy log GET /v1/copy/logs (the request sent to the terminal, its answer and the latency of every open, modify and close): oldest first with after / nextAfter so a feed never misses a line, or newest first with order=desc and before / nextBefore for the latest lines (limit ≤ 500):
# open copies of one allocation
curl "https://api.propmetaapi.com/v1/copy/links?allocation=alloc-1&status=OPEN&limit=100" -H "Authorization: Bearer $GW_KEY"
# → { "items": [ { "id": "…", "allocation": "alloc-1", "leaderPositionId": "51234567", "masterPositionId": "88811223",
# "status": "OPEN", "symbol": "EURUSD", "side": "BUY",
# "leaderVolume": 1, "leaderClosedVolume": 0, "masterVolume": 0.25, "masterClosedVolume": 0,
# "lastSl": 1.0790, "lastTp": 1.0900, "slTpVersion": 2, "retries": 0, "error": null,
# "openedAt": "…", "closedAt": null, "createdAt": "…", "updatedAt": "…" } ],
# "nextCursor": null }
# every link, page by page (limit ≤ 500); filters: allocation, status, leaderPosition, master, leader
curl "https://api.propmetaapi.com/v1/copy/links?limit=500" -H "Authorization: Bearer $GW_KEY"
curl "https://api.propmetaapi.com/v1/copy/links?limit=500&cursor=$NEXT_CURSOR" -H "Authorization: Bearer $GW_KEY"
# every live copy in one request: several statuses, comma-separated
curl "https://api.propmetaapi.com/v1/copy/links?status=PENDING_OPEN,OPEN,PENDING_CLOSE,ORPHANED&limit=200" -H "Authorization: Bearer $GW_KEY"
# the copy log: what the gateway sent and what the terminal answered, oldest first; "after" = the last id you saw
curl "https://api.propmetaapi.com/v1/copy/logs?allocation=alloc-1&after=$LAST_ID" -H "Authorization: Bearer $GW_KEY"
# → { "items": [ { "id": "…", "allocation": "alloc-1", "linkId": "…", "action": "OPEN", "request": { … }, "result": { … },
# "latencyMs": 412, "createdAt": "…" } ], "nextAfter": "…" }
# the latest 100 lines (newest first); page further back with before=$NEXT_BEFORE until it is null
curl "https://api.propmetaapi.com/v1/copy/logs?order=desc&limit=100" -H "Authorization: Bearer $GW_KEY"Permissions
- Registering or changing a master, an allocation, its mode or the symbol map (PUT, POST, DELETE) needs a key with
manageandtradethat is not limited to some accounts — copying touches two accounts at once. - The GET routes (masters, allocations, links, logs) need
read, again on an unrestricted key: a key limited to some accounts is refused on every /v1/copy route.
A complete walk-through
# 1) register the master (a HEDGING account whose margin mode the gateway knows: run a check first)
curl -X PUT https://api.propmetaapi.com/v1/copy/masters/$MASTER_ID -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" \
-d '{ "status": "ACTIVE", "dailyLossLimit": 500, "maxTotalLots": 5 }'
# 2) create the allocation, already ACTIVE, version 1 — only leader positions opened from now on are copied
curl -X PUT https://api.propmetaapi.com/v1/copy/allocations/alloc-1 -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{
"leaderAccountId": "$LEADER_ID", "masterAccountId": "$MASTER_ID",
"volumeRatio": 1, "copySlTp": true, "mode": "ACTIVE", "version": 1
}'
# 3) watch the copies (or subscribe a webhook to COPY_OPENED, COPY_MODIFIED, COPY_CLOSED, COPY_SKIPPED, COPY_FAILED)
curl "https://api.propmetaapi.com/v1/copy/links?allocation=alloc-1&limit=100" -H "Authorization: Bearer $GW_KEY"
# 4) stop opening new copies but keep following the open ones
curl -X POST https://api.propmetaapi.com/v1/copy/allocations/alloc-1/mode -H "Authorization: Bearer $GW_KEY" -H "Content-Type: application/json" -d '{ "mode": "CLOSE_ONLY" }'
# 5) remove the allocation once every copy is closed (409 with "openLinks" while some are open)
curl -X DELETE https://api.propmetaapi.com/v1/copy/allocations/alloc-1 -H "Authorization: Bearer $GW_KEY"Every field and answer is in the API reference (group Copy trading); the error codes in Errors & limits.