> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Copy settings

> GET and POST /v1/copy-trading/settings: switch copying of a trader on or off for one of your users, and set the amount per buy, a cap, buys only or buys and sells, and the slippage.

A user's [copy trading](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md) settings, one set per trader in their [Trade Feed](https://docs.cabalspy.xyz/cabalspy-id/trade-feed.md). They apply to the trader's next trade from the moment you save them; instructions already sent are not changed.

The user is a [platform user](https://docs.cabalspy.xyz/cabalspy-id/white-label.md) (by `external_id` or `csid_id`) or a person who signed in to your app with the scope `trade_feed` (by `csid_id`), within your plan's user limit.

| Setting | Values | Default | Effect |
| - | - | - | - |
| `enabled` | `true` or `false` | `false` | Copy this trader. |
| `mode` | `fixed_usd` or `percent` | `fixed_usd` | How buys are sized. |
| `amount_usd` | Above 0, at most 1,000,000 | 50 | `fixed_usd`: every copied buy is this many USD. |
| `percent` | Above 0, at most 1,000 | 100 | `percent`: every copied buy is this share of the trader's buy in USD. 100 is the same size as the trader. |
| `max_usd` | Above 0, at most 1,000,000, or null | null | Cap per copied buy, in both modes. `null` or `0` removes the cap. |
| `sides` | `buys` or `both` | `both` | `both`: buys and sells are copied. `buys`: only buys. |
| `slippage_bps` | Whole number, 1 to 5,000 | 300 | The price limit sent with every instruction, in basis points: 300 = 3 %. |

Copied buys below \$1 are not sent. Sells are copied as a share of the user's copied position, see [Sizing](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#sizing).

## Read the settings

`GET /v1/copy-trading/settings`

All traders in the user's Trade Feed with their copy settings, those copied first, then newest first. With `trader`, only that one trader as a single object.

### Query Parameters

**external\_id** `string`

The user, by your own user id. Alternatively pass csid\_id.

**csid\_id** `string`

The user's CabalSpy ID. Required unless you pass external\_id.

**trader** `string`

Only this trader: a handle (with or without @) or a csid\_id. Alternatively pass trader\_external\_id for one of your own platform users.

**trader\_external\_id** `string`

Only this trader, by your own user id of a platform user.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/copy-trading/settings?external_id=user_8412" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

r = requests.get("https://api-id.cabalspy.xyz/v1/copy-trading/settings",
                 params={"csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718", "trader": "MazeCCC"},
                 headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"]["copy"])
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ external_id: "user_8412" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/copy-trading/settings?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
for (const t of (await res.json()).data) {
  console.log(t.trader.username, t.copy.enabled, t.managed_by_other_platform);
}
```

### Response

**data** `array`

One entry per trader in the user's Trade Feed, or a single entry when you passed `trader`.

**entry**

**trader** `object`

csid\_id, username, name, image\_url, kol and profile\_url. username and profile\_url are null for platform users.

**copy** `object`

enabled, mode, amount\_usd, percent, max\_usd, sides, slippage\_bps and updated\_at (when the copy settings were last changed, or null).

**managed\_by\_other\_platform** `boolean`

`true` when another platform copies this trader for this user. You cannot switch copying on until it is switched off there, see [One platform at a time](https://docs.cabalspy.xyz/cabalspy-id/copy-trading.md#one-platform-at-a-time).

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "trader": {
        "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09",
        "username": "MazeCCC",
        "name": "Maze",
        "image_url": "https://pbs.twimg.com/profile_images/1/maze_normal.jpg",
        "kol": true,
        "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
      },
      "copy": {
        "enabled": true,
        "mode": "fixed_usd",
        "amount_usd": 25.0,
        "percent": 100.0,
        "max_usd": 20.0,
        "sides": "both",
        "slippage_bps": 300,
        "updated_at": "2026-11-01T17:58:40Z"
      },
      "managed_by_other_platform": false
    }
  ],
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-11-01T18:00:00Z" }
}
```

The same `copy` object is also part of each trader's `settings` in [GET /v1/trade-feed/traders](https://docs.cabalspy.xyz/cabalspy-id/trade-feed-api.md#list-traders).

### Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | Neither csid\_id nor external\_id was passed. |
| 400 | invalid\_parameter | csid\_id is not a valid id. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | [consent\_required](https://docs.cabalspy.xyz/cabalspy-id/errors.md#consent_required) | The user has not granted your app the scope `trade_feed`, or is beyond your plan's user limit. |
| 403 | [plan\_user\_limit](https://docs.cabalspy.xyz/cabalspy-id/errors.md#plan_user_limit) | The user signed in beyond your plan's user limit. |
| 404 | [platform\_user\_not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#platform_user_not_found) | No platform user with this external\_id or trader\_external\_id. |
| 404 | [trader\_not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#trader_not_found) | No CabalSpy ID trader with this handle or csid\_id. |
| 404 | [not\_in\_trade\_feed](https://docs.cabalspy.xyz/cabalspy-id/errors.md#not_in_trade_feed) | The trader is not in the user's Trade Feed. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

## Change the settings

`POST /v1/copy-trading/settings`

Changes the copy settings of one user for one trader. Send only the settings you want to change, at least one of them. If the trader is not in the user's Trade Feed yet, they are added first (with the user's default alert settings) and the response has status **201**; otherwise **200**.

Switching copying on (`"enabled": true`) makes your instance the platform that copies this trader for this user. While another platform copies the trader for the user, the request is refused with 409 `copy_managed_elsewhere`.

Each call counts towards the user's Trade Feed changes, at most 120 per hour.

### Body

**external\_id** `string`

The user, by your own user id. Alternatively pass csid\_id.

**csid\_id** `string`

The user's CabalSpy ID. Required unless you pass external\_id.

**trader** `string` *required*

The trader to copy: a handle (with or without @) or a csid\_id. Alternatively pass trader\_external\_id.

**trader\_external\_id** `string`

The trader, by your own user id of one of your platform users.

**enabled** `boolean`

`true` to copy this trader, `false` to stop.

**mode** `string`

`fixed_usd` or `percent`.

**amount\_usd** `number`

USD per copied buy in `fixed_usd` mode. Above 0, at most 1,000,000.

**percent** `number`

Share of the trader's buy in `percent` mode. Above 0, at most 1,000.

**max\_usd** `number`

Cap per copied buy. Above 0, at most 1,000,000. `null` or `0` removes the cap.

**sides** `string`

`buys` or `both`.

**slippage\_bps** `integer`

Whole number from 1 to 5,000.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/copy-trading/settings" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412", "trader": "MazeCCC", "enabled": true, "mode": "fixed_usd", "amount_usd": 25, "max_usd": 20}'
```

```python Python theme={null}
import requests

# copy 10 % of every buy, no cap, buys only
r = requests.post("https://api-id.cabalspy.xyz/v1/copy-trading/settings",
                  json={"csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718", "trader": "MazeCCC",
                        "enabled": True, "mode": "percent", "percent": 10, "max_usd": None, "sides": "buys"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.status_code, r.json()["data"]["copy"])
```

```javascript JavaScript theme={null}
// stop copying
const res = await fetch("https://api-id.cabalspy.xyz/v1/copy-trading/settings", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412", trader: "MazeCCC", enabled: false }),
});
console.log((await res.json()).data.copy.enabled);
```

### Response

The trader's entry as in [Read the settings](#read-the-settings): `trader`, `copy` and `managed_by_other_platform`.

```json Response theme={null}
{
  "success": true,
  "data": {
    "trader": {
      "csid_id": "7c2e9a14-6b3d-4f81-9e0a-5d4c3b2a1f09",
      "username": "MazeCCC",
      "name": "Maze",
      "image_url": "https://pbs.twimg.com/profile_images/1/maze_normal.jpg",
      "kol": true,
      "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
    },
    "copy": {
      "enabled": true,
      "mode": "fixed_usd",
      "amount_usd": 25.0,
      "percent": 100.0,
      "max_usd": 20.0,
      "sides": "both",
      "slippage_bps": 300,
      "updated_at": "2026-11-01T17:58:40Z"
    },
    "managed_by_other_platform": false
  },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-11-01T17:58:40Z" }
}
```

### Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | No user, no trader, or none of the settings was sent (`parameter` is then `enabled`). |
| 400 | invalid\_parameter | A setting has the wrong type or is out of range. `parameter` names it. |
| 400 | [cannot\_add\_self](https://docs.cabalspy.xyz/cabalspy-id/errors.md#cannot_add_self) | The user and the trader are the same person. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | [consent\_required](https://docs.cabalspy.xyz/cabalspy-id/errors.md#consent_required) | The user has not granted your app the scope `trade_feed`, or is beyond your plan's user limit. |
| 403 | [trading\_private](https://docs.cabalspy.xyz/cabalspy-id/errors.md#trading_private) | The trader keeps their trading private. |
| 404 | [platform\_user\_not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#platform_user_not_found) | No platform user with this external\_id or trader\_external\_id. |
| 404 | [trader\_not\_found](https://docs.cabalspy.xyz/cabalspy-id/errors.md#trader_not_found) | No CabalSpy ID trader with this handle or csid\_id. |
| 409 | [copy\_managed\_elsewhere](https://docs.cabalspy.xyz/cabalspy-id/errors.md#copy_managed_elsewhere) | Another platform copies this trader for this user. It has to be switched off there first. |
| 409 | [trade\_feed\_full](https://docs.cabalspy.xyz/cabalspy-id/errors.md#trade_feed_full) | The trader would have to be added, and the user's Trade Feed already has 300 traders. |
| 429 | [rate\_limited](https://docs.cabalspy.xyz/cabalspy-id/errors.md#rate_limited) | More than 120 Trade Feed changes for this user in an hour. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.