# Copiers

> Create a copier for a master account. Rename, pause, resume or delete it, with or without its open copies, and see what gets copied.

A copier watches one master account and copies the master's trades to the copier's [followers](/docs/followers). To read copiers, your API key needs the `copiers:read` scope. To create, change or delete them, it needs `copiers:write`.

## Create a copier [#create-a-copier]

```bash
curl https://api.algotradertools.com/v1/copiers \
  -H "Authorization: Bearer $ATT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Gold strategy", "master_id": "4f6c2a1e-8b3d-4e7a-9c5f-1d2e3a4b5c6d" }'
```

| Field       | Required | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `name`      | Yes      | Up to 64 characters                               |
| `master_id` | Yes      | The ID of the account whose trades are copied     |
| `is_active` | No       | `false` creates the copier paused. Default `true` |

The response is `201 Created` with the copier, which has no followers yet. Add them with [`POST /v1/copiers/{copier_id}/followers`](/docs/followers#attach-a-follower).

The master must be one of your accounts. It must also:

* be `connected`. An account that is still connecting, or was released, fails with `account_not_connected`.
* not be a follower of any copier (`account_is_follower`). An account is a master or a follower, never both.
* be a hedging account. All MT4 accounts are. MT5 netting accounts fail with `netting_account`. The netting check asks the account's terminal. If the terminal doesn't answer, the request fails with `503 terminal_unavailable`. Try again shortly.

If the master doesn't meet a requirement, the response is `400 validation_failed`, and the code of the `master_id` error tells you which one. A master can be connected with its investor password. One master can also serve several copiers, for example to copy it with different rules to different groups of followers.

If you send `POST /v1/copiers` and get no response, a retry can create a second copier. List your copiers before you retry.

## The copier object [#the-copier-object]

```json
{
  "id": "c7d1e5f2-3a4b-4c6d-8e9f-0a1b2c3d4e5f",
  "object": "copier",
  "name": "Gold strategy",
  "is_active": true,
  "master_id": "4f6c2a1e-8b3d-4e7a-9c5f-1d2e3a4b5c6d",
  "master": {
    "id": "4f6c2a1e-8b3d-4e7a-9c5f-1d2e3a4b5c6d",
    "name": "Gold master",
    "platform": "mt5",
    "server": "ICMarketsSC-Demo",
    "login": 51234567,
    "status": "connected"
  },
  "followers": [],
  "open_copies": 3,
  "created_at": "2026-10-25T14:08:30.512Z",
  "updated_at": "2026-10-25T14:08:30.512Z"
}
```

| Field                      | Description                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `id`                       | The copier's ID, a UUID                                                                   |
| `name`                     | Its name                                                                                  |
| `is_active`                | `false` while it is paused                                                                |
| `master_id`                | The master account's ID                                                                   |
| `master`                   | A summary of the master account: `id`, `name`, `platform`, `server`, `login` and `status` |
| `followers`                | Its [followers](/docs/followers#the-follower-object), with their rules and live status    |
| `open_copies`              | How many copies are open across all followers right now                                   |
| `created_at`, `updated_at` | When it was created and last changed                                                      |

## List and read copiers [#list-and-read-copiers]

`GET /v1/copiers` lists your copiers, oldest first, in the [list format](/docs/limits#pagination). `GET /v1/copiers/{copier_id}` returns one copier with every follower and its status. Use it when you want to see what a copier is doing.

```bash
curl https://api.algotradertools.com/v1/copiers/c7d1e5f2-3a4b-4c6d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $ATT_API_KEY"
```

## Rename a copier [#rename-a-copier]

```bash
curl -X PATCH https://api.algotradertools.com/v1/copiers/c7d1e5f2-3a4b-4c6d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $ATT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Gold strategy (London)" }'
```

`PATCH` can change two fields, `name` and `is_active`, and changes only the ones you send. The master can't be changed: sending `master_id` fails with `validation_failed` and the code `immutable`. To copy another master, create a new copier. Read-only fields such as `id` or `followers` are ignored. A field that copiers don't have is refused with `unknown_field`.

## Pause and resume [#pause-and-resume]

```bash
curl -X PATCH https://api.algotradertools.com/v1/copiers/c7d1e5f2-3a4b-4c6d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $ATT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'
```

* **Pausing** stops new copies for every follower. Copies that are already open stay open, and still close and change when the master's positions do.
* **Resuming** (`"is_active": true`) copies only what the master opens from then on. Positions it opened and orders it placed while the copier was paused stay uncopied, also with `copy_existing`.

To pause or resume a single follower instead, set `is_active` on the [follower](/docs/followers#pause-and-resume-a-follower).

## Delete a copier [#delete-a-copier]

```bash
curl -X DELETE "https://api.algotradertools.com/v1/copiers/c7d1e5f2-3a4b-4c6d-8e9f-0a1b2c3d4e5f?close_positions=true" \
  -H "Authorization: Bearer $ATT_API_KEY"
```

| Query parameter   | Description                                                                                                                                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `close_positions` | `true` (or `1`) closes every copy this copier opened, at market, before the copier is deleted. Default `false` (or `0`): the copies stay open on the followers as ordinary positions. Any other value fails with `validation_failed` |

With `close_positions=true`, the delete works through the followers one at a time. It pauses each follower, so nothing new is copied to it, and then closes its copies. If a terminal refuses to close a copy, the request stops there and fails with `close_failed` (`502`, `503` or `504`). Nothing is deleted. The followers handled up to that point stay paused, and all of them except the last one already have their copies closed. Try the delete again, or resume the followers.

When the delete succeeds, the response is `204 No Content`. Deleting a copier also deletes its [events](/docs/events). Its accounts stay connected and can be used by other copiers.

## What gets copied [#what-gets-copied]

* **Market positions:** opens, full closes, partial closes (in proportion to what the master closed), and changes to stop loss and take profit.
* **Pending orders:** by default, a master's pending order is copied when it fills, as a market order. A follower with `copy_pending` gets a pending order of its own instead, which moves, is cancelled and expires with the master's. See [Pending orders](/docs/followers#pending-orders).
* **Each copy is tagged:** it carries the follower's `magic` number and the comment `att:` followed by the master's ticket in base 36. That's how the copier tells its copies apart from trades you place by hand on the follower, even after a restart.

Most of the time a copy takes is the follower broker's own execution, about 50 to 300 ms. Each copy event records its timings. See [Copy events](/docs/events#timings). The full list of what isn't copied, and why, is in [Limits](/docs/limits#copying-limits).