# Wallet folders

> Group trading wallets into named, colored folders.

Folders group wallets so they can be selected and acted on together. The API calls them tags: the routes live under `/wallets/tags/` and a folder is referenced by `tag_id`.

A folder belongs to one network type and only holds wallets of that network. Folders are returned with [List wallets](/reference/wallets/#list-wallets) under `tags.svm` and `tags.evm`, and each wallet lists its folders in `tag_ids`. Archiving a folder hides it from the main list but keeps its wallets.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST /wallets/tags/create-tag`: Create a folder
- `POST /wallets/tags/update-tag`: Update a folder
- `POST /wallets/tags/delete-tag`: Delete a folder
- `POST /wallets/tags/tag-wallets`: Add wallets to a folder
- `POST /wallets/tags/untag-wallets`: Remove wallets from a folder

## The Folder object

A named group of wallets on one network type.

- `id` (integer): Folder ID (`tag_id` in requests). Unique per network type only.
- `name` (string): Folder name, at most 25 characters.
- `color` (string): Display color as a hex string, for example `#A6B1FF`.
- `archived` (boolean): Whether the folder is archived. Archived folders keep their wallets.

```json
{
  "id": 12,
  "name": "Snipers",
  "color": "#A6B1FF",
  "archived": false
}
```

### Create a folder

`POST /wallets/tags/create-tag`

Creates an empty folder on a network type. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Each call creates a new folder, even with a name already in use. Before retrying, call [List wallets](/reference/wallets/#list-wallets) and look for the folder in `tags`.

#### Body parameters

- `name` (string, required): Folder name, at most 25 characters.
- `color` (string, required): Display color as a hex string.
- `network_type` (enum, required): Network type of the wallets the folder will hold. Possible values: `svm`, `evm`.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.
- `tag_id` (integer): ID of the new folder.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Tag name too long` | `name` is longer than 25 characters. | Shorten `name` to 25 characters or fewer. |
| 400 | `bad_request` | `network_type is required ("svm" or "evm")` | `network_type` is missing. | Set `network_type` to `svm` or `evm`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/tags/create-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Snipers",
  "color": "#A6B1FF",
  "network_type": "svm"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully created tag",
  "tag_id": 12
}
```

### Update a folder

`POST /wallets/tags/update-tag`

Renames, recolors, archives or unarchives a folder. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Sending the same values again leaves the folder in the same state.

Omitted fields are left unchanged.

#### Body parameters

- `tag_id` (integer, required): ID of the folder.
- `new_name` (string, optional): New name, at most 25 characters.
- `new_color` (string, optional): New hex color.
- `archive` (boolean, optional): `true` to archive the folder, `false` to unarchive it.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Tag name too long` | `new_name` is longer than 25 characters. | Shorten `new_name` to 25 characters or fewer. |
| 500 | `internal_error` | `tag not found` | The folder is not on the account. Returned as a 500, not a 404. | Use a folder ID from the `tags` of [List wallets](/reference/wallets/#list-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/tags/update-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": 12,
  "new_name": "Snipers (old)",
  "archive": true
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully updated tag"
}
```

### Delete a folder

`POST /wallets/tags/delete-tag`

Deletes a folder. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat after a successful delete returns 500 `tag not found`.

#### Body parameters

- `tag_id` (integer, required): ID of the folder.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 500 | `internal_error` | `tag not found` | The folder is not on the account. Returned as a 500, not a 404. | Use a folder ID from the `tags` of [List wallets](/reference/wallets/#list-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/tags/delete-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": 12
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully deleted tag"
}
```

### Add wallets to a folder

`POST /wallets/tags/tag-wallets`

Adds wallets to a folder. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A wallet already in the folder is left as is.

The network is read from the address format, and the folder must belong to that network. Addresses that are not wallets of the account are skipped. The web app calls this after creating wallets, from the folder pickers, and after a marketplace order is delivered.

#### Body parameters

- `tag_id` (integer, required): ID of the folder.
- `pubkeys` (array<string>, required): Addresses to add, all on the folder's network.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `No pubkeys provided` | No address was sent. | Send at least one address in `pubkeys`. |
| 400 | `bad_request` | `Mixed evm + svm addresses are not allowed in a single tag operation` | SVM and EVM addresses were mixed. | Send SVM and EVM addresses in separate requests. |
| 400 | `bad_request` | `tag not found for this network` | The folder is not on the account for the addresses' network. | Use a folder of the same network from the `tags` of [List wallets](/reference/wallets/#list-wallets). |
| 400 | `bad_request` | `Invalid pubkey format for SVM tag` | For an SVM folder, an address is not a valid Solana address. | Check that every address is a valid base58 public key. |
| 400 | `bad_request` | `Invalid evm address` | For an EVM folder, an address is not a valid EVM address. | Check that every address is a valid `0x` address. |
| 400 | `bad_request` | `none of these wallets belong to this account` | None of the addresses is a wallet of the account. | Use addresses from [List wallets](/reference/wallets/#list-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/tags/tag-wallets" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": 12,
  "pubkeys": [
    "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully added tag to wallets"
}
```

### Remove wallets from a folder

`POST /wallets/tags/untag-wallets`

Removes wallets from a folder without deleting them. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A wallet that is not in the folder is left as is.

#### Body parameters

- `tag_id` (integer, required): ID of the folder.
- `pubkeys` (array<string>, required): Addresses to remove, all on the folder's network.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `No pubkeys provided` | No address was sent. | Send at least one address in `pubkeys`. |
| 400 | `bad_request` | `Mixed evm + svm addresses are not allowed in a single tag operation` | SVM and EVM addresses were mixed. | Send SVM and EVM addresses in separate requests. |
| 400 | `bad_request` | `tag not found for this network` | The folder is not on the account for the addresses' network. | Use a folder of the same network from the `tags` of [List wallets](/reference/wallets/#list-wallets). |
| 400 | `bad_request` | `Invalid pubkey format for SVM tag` | For an SVM folder, an address is not a valid Solana address. | Check that every address is a valid base58 public key. |
| 400 | `bad_request` | `Invalid evm address` | For an EVM folder, an address is not a valid EVM address. | Check that every address is a valid `0x` address. |
| 400 | `bad_request` | `none of these wallets belong to this account` | None of the addresses is a wallet of the account. | Use addresses from [List wallets](/reference/wallets/#list-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/tags/untag-wallets" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": 12,
  "pubkeys": [
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully removed tag from wallets"
}
```
