# Wallets

> Create, list, delete and restore the trading wallets of your account, and manage watched addresses.

Wallets are the keypairs Proxima holds for your account and signs with. You generate them per network type (`svm` or `evm`), promote them from a launch, or buy them on the marketplace. [List wallets](#list-wallets) returns them per chain with their native balance, volume, PnL, [folders](/reference/wallet-folders/) and trade routing.

Deleting a wallet archives it instead of destroying the key: [List deleted wallets](#list-deleted-wallets) shows archived wallets and [Restore deleted wallets](#restore-deleted-wallets) brings them back within your license's wallet cap. Watch wallets are a separate list of external addresses you follow; Proxima holds no key for them.

Trade routing decides, per chain, which platform builds a wallet's trades. [Retrieve the routing config](#retrieve-the-routing-config) lists the platforms and [Set wallet routing](#set-wallet-routing) assigns wallets to them.

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

## Endpoints

- `GET /wallets/get/{chain_id}`: List wallets
- `GET /wallets/routing/config`: Retrieve the routing config
- `POST /wallets/routing/{chain_id}`: Set wallet routing
- `POST /wallets/{network_type}/add`: Create wallets
- `POST /wallets/remove`: Delete wallets
- `GET /wallets/deleted/{chain_id}`: List deleted wallets
- `POST /wallets/deleted/restore`: Restore deleted wallets
- `POST /wallets/add-from-launch`: Add wallets from a launch
- `POST /wallets/{network_type}/watch/add`: Add watch wallets
- `POST /wallets/rename`: Update a wallet
- `GET /wallets/watch/list`: List watch wallets
- `POST /wallets/watch/remove`: Remove watch wallets

## The Wallet object

A trading wallet of the account, with its stats on the requested chain. Per-chain maps are keyed by chain ID and only contain the chains the response covers.

- `pubkey` (string): Wallet address: a base58 public key on SVM, a `0x` address on EVM.
- `network_type` (enum): Network the wallet belongs to. Possible values: `svm`, `evm`.
- `created_at` (integer): Unix timestamp (seconds) at which the wallet was added to the account.
- `launches` (array<integer>): Launches the wallet has been used in.
- `tag_ids` (array<integer>): IDs of the [folders](/reference/wallet-folders/) the wallet belongs to.
- `funding_source` (string | null): How the wallet was funded: `None`, `Wallet` (a direct transfer), or the ID of the exchange that funded it, for example `binance`.
- `from_marketplace` (boolean): Whether the wallet was delivered by a marketplace order.
- `native_balances` (object): Native balance per chain ID, in base units (lamports or wei), as decimal strings.
- `tx_count` (object): Number of transactions per chain ID: an integer string on Solana, a number on EVM chains.
- `volume` (object): Traded volume per chain ID, in native base units, as decimal strings.
- `pnl_native` (object): PnL per chain ID, in native base units, as decimal strings. On Solana, a loss reads `"0"`; on EVM chains, the value keeps its sign.
- `pnl_usd` (object): PnL per chain ID, in micro-USD. On Solana, an integer string; a loss reads `"0"`. On EVM chains, always the number `0`: USD PnL is not tracked there.
- `pnl_usd_total` (integer): PnL across chains, in micro-USD, as a JSON number. A loss reads `0`, and EVM wallets always read `0`.
- `funded_at` (object): Unix timestamp (seconds) of the last funding per chain ID; `0` when never funded.
- `routing` (string): ID of the platform the wallet's trades are built through on the requested chain. `direct` by default. See [Retrieve the routing config](#retrieve-the-routing-config).

```json
{
  "pubkey": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
  "network_type": "svm",
  "created_at": 1792051200,
  "launches": [
    4821
  ],
  "tag_ids": [
    12
  ],
  "funding_source": "Wallet",
  "from_marketplace": false,
  "native_balances": {
    "sol": "1250000000"
  },
  "tx_count": {
    "sol": 42
  },
  "volume": {
    "sol": "18400000000"
  },
  "pnl_native": {
    "sol": "35000000"
  },
  "pnl_usd": {
    "sol": "7"
  },
  "pnl_usd_total": 7,
  "funded_at": {
    "sol": 1792054800
  },
  "routing": "direct"
}
```

## The Watch wallet object

An external address on your watchlist. Proxima holds no key for it, so it cannot sign or be withdrawn from.

- `pubkey` (string): Watched address.
- `network_type` (enum): Network of the address. Possible values: `svm`, `evm`.
- `name` (string | null): Label, at most 25 characters.
- `icon` (string | null): Short text icon (for example an emoji), at most 20 characters.
- `image_link` (string | null): URL of the uploaded avatar image.
- `is_bookmark` (boolean): Whether the address is bookmarked.
- `created_at` (integer): Unix timestamp (seconds) at which the address was added.

```json
{
  "pubkey": "DD4FUCY8FRnqJWxXg3UJ7PsouHXGjkkLmPa2YSwr4bVh",
  "network_type": "svm",
  "name": "Whale 1",
  "icon": null,
  "image_link": null,
  "is_bookmark": true,
  "created_at": 1792310400
}
```

### List wallets

`GET /wallets/get/{chain_id}`

Returns the active wallets of the account on the network of a chain, with their stats on that chain. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Wallets of the chain's network type are returned (all SVM wallets for `sol`, all EVM wallets for an EVM chain), with balances and stats for `chain_id`. Folders are returned alongside: the list for the chain's network is filled, the other is empty. The web app calls this to render the Wallets page, the delete-wallets flow and the sell-all-tokens flow.

#### Path parameters

- `chain_id` (enum, required): Chain ID. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.

#### Returns 200 OK

- `funding_status` (enum): Status of the account's wallet funding. Possible values: `None`, `Running`, `Failed`.
- `wallets` (array<object>): List of [Wallet](#object-wallet) objects.
- `tags` (object): Folders of the account, by network type.
  - `svm` (array<object>): SVM folders. See the [Folder](/reference/wallet-folders/#object-folder) object.
  - `evm` (array<object>): EVM folders.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unsupported chain: <chain_id>` | The chain is not supported. | Use a supported `chain_id`; `monad` is no longer accepted. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/wallets/get/sol" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "funding_status": "None",
  "wallets": [
    {
      "pubkey": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
      "network_type": "svm",
      "created_at": 1792051200,
      "launches": [
        4821
      ],
      "tag_ids": [
        12
      ],
      "funding_source": "Wallet",
      "from_marketplace": false,
      "native_balances": {
        "sol": "1250000000"
      },
      "tx_count": {
        "sol": 42
      },
      "volume": {
        "sol": "18400000000"
      },
      "pnl_native": {
        "sol": "35000000"
      },
      "pnl_usd": {
        "sol": "7"
      },
      "pnl_usd_total": 7,
      "funded_at": {
        "sol": 1792054800
      },
      "routing": "direct"
    }
  ],
  "tags": {
    "svm": [
      {
        "id": 12,
        "name": "Snipers",
        "color": "#A6B1FF",
        "archived": false
      }
    ],
    "evm": []
  }
}
```

### Retrieve the routing config

`GET /wallets/routing/config`

Lists every platform a wallet's trades can be built through, with its fee and chains. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The first platform is always `direct` (shown as Proxima), available on every chain; the other platforms build trades on `sol` only. The web app loads it for the trade routing modals and filters platforms by `chains`.

#### Returns 200 OK

- `default` (string): Platform a wallet uses when none is set: `direct`.
- `platforms` (array<object>): Available platforms.
  - `id` (string): Platform ID used as a key in [Set wallet routing](#set-wallet-routing). `direct` is Proxima's own route.
  - `label` (string): Display name.
  - `fee_bps` (integer): Fee a trade routed this way pays the platform, in basis points of its quote leg.
  - `fee_pct` (number): `fee_bps` as a percentage.
  - `chains` (array<string>): Chain IDs the platform builds trades on.

#### Example request

```bash
curl "https://api-mig.proxima.tools/wallets/routing/config" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "default": "direct",
  "platforms": [
    {
      "id": "direct",
      "label": "Proxima",
      "fee_bps": 0,
      "fee_pct": 0,
      "chains": [
        "sol",
        "bsc",
        "base",
        "eth",
        "robinhood",
        "arc",
        "xlayer"
      ]
    },
    {
      "id": "axiom",
      "label": "Axiom",
      "fee_bps": 100,
      "fee_pct": 1,
      "chains": [
        "sol"
      ]
    }
  ]
}
```

### Set wallet routing

`POST /wallets/routing/{chain_id}`

Sets the platform each listed wallet trades through on a chain. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Wallets not listed keep their routing, so sending the same body again leaves the same state.

The body maps platform IDs to the addresses that should trade through them. Platform IDs are matched case-insensitively, and routing a wallet to `direct` removes its routing. Wallets not listed keep their current routing. The web app sends it from the per-wallet routing modal and from the bulk trades-routing modal, which splits the selection across platforms by share.

#### Path parameters

- `chain_id` (enum, required): Chain the routing applies to. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.

#### Body parameters

- `<platform_id>` (array<string>, required): One key per platform ID from the routing config; the value lists the wallet addresses to route through it. Only `direct` builds trades outside `sol`. At least one address is required overall.

#### Returns 200 OK

- `ok` (boolean): `true` on success.
- `routing` (object): Platform ID now set for each address, keyed by address. EVM addresses come back lowercase.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unsupported chain: <chain_id>` | `chain_id` is not a chain the API serves. | Use a supported `chain_id`; `monad` is no longer accepted. |
| 400 | `bad_request` | `invalid body: <path>: <cause>` | The body is not a JSON object whose values are arrays of address strings. | Send an object mapping platform IDs to arrays of addresses. |
| 400 | `bad_request` | `<platform_id> does not build trades on <chain_id>` | A key is not a platform ID, or names a platform that does not build trades on the chain. The whole batch is refused. | Use platform IDs whose `chains` include the chain in [Retrieve the routing config](/reference/wallets/#retrieve-the-routing-config). |
| 400 | `bad_request` | `<address> is no <chain_id> address` | An address is not a valid address of the chain. The whole batch is refused. | Send Solana addresses for `sol` and `0x` addresses for EVM chains. |
| 400 | `bad_request` | `<address> is listed under two platforms` | An address appears twice in the body, under two platforms or twice under one. The whole batch is refused. | List each address once. |
| 400 | `bad_request` | `no wallet to route` | The body lists no address. | Send at least one address. |
| 400 | `bad_request` | `not wallets of this license: <addresses>` | Some addresses are not wallets of the account; the message lists them. The whole batch is refused. | Route only wallets from [List wallets](/reference/wallets/#list-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/routing/sol" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "axiom": [
    "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
  ],
  "direct": [
    "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "routing": {
    "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44": "axiom",
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4": "axiom",
    "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF": "direct"
  }
}
```

### Create wallets

`POST /wallets/{network_type}/add`

Generates new wallets on a network type and optionally adds them to folders. (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 generates new wallets. Before retrying, call [List wallets](/reference/wallets/#list-wallets) and check whether the new wallets are already there.

> The web app only generates wallets with this endpoint and never sends `secret_keys`; it imports keys through the Keys API.

#### Path parameters

- `network_type` (enum, required): Network type: `svm` (Solana) or `evm` (every EVM chain). Possible values: `svm`, `evm`.

#### Body parameters

- `amount_to_generate` (integer, required): Number of new keypairs to generate.
- `secret_keys` (array<string>, optional): Private keys to import alongside the generated wallets. Requires key-management rights on the license.
- `tag_ids` (array<integer>, optional): IDs of folders to add the new wallets to.

#### Returns 200 OK

- `wallets` (array<string>): Addresses of the wallets added.
- `tag_ids` (array<integer>): Folder IDs the wallets were added to.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown network_type: <network_type>` | `network_type` is not `svm` or `evm`. | Use `svm` or `evm` as `network_type`. |
| 400 | `bad_request` | `Invalid keypairs provided` | On SVM, an entry of `secret_keys` is not a valid keypair. | Check that every entry of `secret_keys` is a valid Solana secret key. |
| 400 | `bad_request` | `invalid private key: <error>` | On EVM, an entry of `secret_keys` is not a valid private key. | Check that every entry of `secret_keys` is a valid hex private key. |
| 400 | `bad_request` | `Some tags not found or unauthorized` | A folder in `tag_ids` is not on the account. | Use folder IDs from the `tags` of [List wallets](/reference/wallets/#list-wallets). |
| 400 | `bad_request` | `nothing to add` | On EVM, `amount_to_generate` is 0 and no `secret_keys` were sent. | Set `amount_to_generate` above 0 or send `secret_keys`. |
| 403 | `forbidden` | `Unauthorized to add custom wallets` | `secret_keys` was sent and the license cannot import keys. | Remove `secret_keys`, or use a license with key-management rights. |
| 422 | `unprocessable` | `Exceeded max wallet limit` | The request would exceed the license's wallet limit. On EVM, only an import of more than 5,000 keys is refused. | Generate fewer wallets, or remove unused ones with [Delete wallets](/reference/wallets/#delete-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/svm/add" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_to_generate": 3,
  "tag_ids": [
    12
  ]
}'
```

#### Example response

```json
{
  "wallets": [
    "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
    "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
  ],
  "tag_ids": [
    12
  ]
}
```

### Delete wallets

`POST /wallets/remove`

Archives wallets so they no longer appear in the wallet list. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Deleting a wallet that is already deleted changes nothing.

The network is read from the address format: `0x` addresses are EVM, anything else is SVM. On SVM, a wallet that still holds a withdrawable balance cannot be deleted. EVM wallets are archived without a balance check.

> Deletion is a soft delete: the key is kept and the wallet can be brought back with [Restore deleted wallets](#restore-deleted-wallets).

#### Body parameters

- `pubkeys` (array<string>, required): Addresses of the wallets to delete, all on the same 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 SVM + EVM pubkeys in one request — split by chain or use /wallets/{network_type}/remove` | SVM and EVM addresses were mixed. | Send SVM and EVM addresses in separate requests. |
| 400 | `bad_request` | `Invalid pubkey format` | A non-`0x` address is not a valid Solana address. | Check that every SVM address is a valid base58 public key. |
| 422 | `unprocessable` | `At least one wallet have some funds` | An SVM wallet still holds funds above the dust floor. EVM wallets are not checked. | Move the funds out with [Execute a withdrawal](/reference/withdrawals/#execute-a-withdrawal) before deleting the wallet. |
| 422 | `upstream_failure` | `rpc api issue: <error>` | The SVM balance check could not read balances from the RPC. | Retry after a short wait. |

#### Example request

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

#### Example response

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

### List deleted wallets

`GET /wallets/deleted/{chain_id}`

Returns the archived wallets of the account on the network of a chain. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Path parameters

- `chain_id` (enum, required): Chain ID. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.

#### Returns 200 OK

Returns a list of [Wallet](#object-wallet) objects.

- `wallets` (array<object>): Deleted wallets.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unsupported chain: <chain_id>` | The chain is not supported. | Use a supported `chain_id`; `monad` is no longer accepted. |
| 422 | `upstream_failure` | `rpc api issue: <error>` | On `sol`, reading the balances of the deleted wallets from the RPC failed. | Retry after a short wait. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/wallets/deleted/sol" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "wallets": [
    {
      "pubkey": "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
      "network_type": "svm",
      "created_at": 1792051200,
      "launches": [
        4821
      ],
      "tag_ids": [],
      "funding_source": "Wallet",
      "from_marketplace": false,
      "native_balances": {
        "sol": "0"
      },
      "tx_count": {
        "sol": 42
      },
      "volume": {
        "sol": "18400000000"
      },
      "pnl_native": {
        "sol": "35000000"
      },
      "pnl_usd": {
        "sol": "7"
      },
      "pnl_usd_total": 7,
      "funded_at": {
        "sol": 1792054800
      },
      "routing": "direct"
    }
  ]
}
```

### Restore deleted wallets

`POST /wallets/deleted/restore`

Makes deleted wallets active again. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Wallets already restored are no longer deleted; once none is left, a repeat returns 404.

The network is read from the address format. Addresses that are not deleted wallets of the account are ignored.

#### Body parameters

- `pubkeys` (array<string>, required): Addresses to restore, all on the same network. At most 5,000 per call.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.
- `restored` (array<string>): Addresses that were restored.

#### 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` | `at most 5000 wallets per call` | More than 5,000 addresses were sent. | Split the addresses into batches of 5,000 or fewer. |
| 400 | `bad_request` | `Mixed SVM + EVM pubkeys in one request` | SVM and EVM addresses were mixed. | Send SVM and EVM addresses in separate requests. |
| 404 | `not_found` | `No deleted wallets found` | None of the addresses is a deleted wallet of the account. | Use addresses from [List deleted wallets](/reference/wallets/#list-deleted-wallets). |
| 422 | `unprocessable` | `Exceeded max wallet limit: <active> active, <adding> to restore, <max> allowed` | Restoring would exceed the license's wallet limit. | Restore fewer wallets, or delete active ones first. |

#### Example request

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

#### Example response

```json
{
  "ok": true,
  "restored": [
    "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
  ]
}
```

### Add wallets from a launch

`POST /wallets/add-from-launch`

Adds wallets used in a launch to the account's trading wallets. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. On Solana, a wallet already added is refused with 409, so a repeat cannot add it twice.

The web app calls this from a launch's wallet list and from the wallets export menu.

#### Body parameters

- `launch_id` (string, required): Launch ID. The client sends the numeric ID as a string.
- `pubkeys` (array<string>, required): Addresses of launch wallets to add.
- `tag_ids` (array<integer>, optional): IDs of folders to add the wallets to.

#### Returns 200 OK

- `wallets` (array<string>): Addresses added.
- `tag_ids` (array<integer>): Folder IDs the wallets were added to.

#### 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` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Send the launch's numeric ID as a string. |
| 404 | `not_found` | `launch not found` | The launch is not on the account. | Use the ID of one of your launches. |
| 400 | `bad_request` | `EVM addresses sent to an SVM launch — check the launch_id chain` | EVM addresses were sent for a Solana launch. | Send addresses of the launch's own chain. |
| 400 | `bad_request` | `SVM pubkey sent to an EVM launch — check the launch_id chain` | Solana addresses were sent for an EVM launch. | Send addresses of the launch's own chain. |
| 400 | `bad_request` | `Invalid pubkey format` | For a Solana launch, 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 launch, an address is not a valid EVM address. | Check that every address is a valid `0x` address. |
| 400 | `bad_request` | `At least one selected wallet is not in launch wallets` | An address is not a wallet of the launch. | Send only wallets of this launch. |
| 409 | `conflict` | `At least one selected wallet is already an aged wallet` | On Solana, a wallet is already one of the account's trading wallets. | Remove the wallets already listed by [List wallets](/reference/wallets/#list-wallets) from `pubkeys`. |
| 404 | `not_found` | `Some selected wallets not found in database` | On Solana, a launch wallet has no stored key. | Send only wallets of this launch. |
| 404 | `not_found` | `Some tags not found or unauthorized` | A folder in `tag_ids` is not on the account. | Use folder IDs from the `tags` of [List wallets](/reference/wallets/#list-wallets). |
| 400 | `bad_request` | `group has no plan yet` | For an EVM multi-launch, the launch group has no plan yet. | Save the launch plan first, then retry. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/add-from-launch" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "launch_id": "101734002558731",
  "pubkeys": [
    "91Xgc8gCBPK92v2i3CPnoMLNT8BJBRbL9WZ9ouiL5NVy",
    "AqaW1YghutnQEhjycn8m26Rr4RzZuZAoaNYsFjRP5NDp"
  ],
  "tag_ids": [
    12
  ]
}'
```

#### Example response

```json
{
  "wallets": [
    "91Xgc8gCBPK92v2i3CPnoMLNT8BJBRbL9WZ9ouiL5NVy",
    "AqaW1YghutnQEhjycn8m26Rr4RzZuZAoaNYsFjRP5NDp"
  ],
  "tag_ids": [
    12
  ]
}
```

### Add watch wallets

`POST /wallets/{network_type}/watch/add`

Adds external addresses to the watchlist. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Adding an address that is already watched updates its name, image and icon instead of duplicating it.

`names`, `images` and `icons` are parallel to `pubkeys`: entry *i* applies to address *i*, and `null` leaves it unset. The web app calls this from the Watchlist, from a live launch, and after a marketplace checkout.

#### Path parameters

- `network_type` (enum, required): Network type of the addresses. Possible values: `svm`, `evm`.

#### Body parameters

- `pubkeys` (array<string>, required): Addresses to watch. At most 100 per request.
- `names` (array<string | null>, optional): Label per address, at most 25 characters, or `null`. Optional; when sent, it must have one entry per address.
- `images` (array<string | null>, optional): Base64-encoded avatar image per address (at most 2 MB), or `null`. Optional; when sent, it must have one entry per address.
- `icons` (array<string | null>, optional): Short text icon per address, at most 20 characters, or `null`. Optional; when sent, it must have one entry per address.
- `is_bookmark` (array<boolean>, optional): Bookmark flag per address. Ignored unless it has one entry per address.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown network_type: <network_type>` | `network_type` is not `svm` or `evm`. | Use `svm` or `evm` as `network_type`. |
| 400 | `bad_request` | `No pubkeys provided` | On SVM, no address was sent. | Send at least one address in `pubkeys`. |
| 400 | `bad_request` | `No addresses provided` | On EVM, no address was sent. | Send at least one address in `pubkeys`. |
| 400 | `bad_request` | `Maximum 100 wallets per request` | More than 100 addresses were sent. | Split the addresses into batches of 100 or fewer. |
| 400 | `bad_request` | `Names array must match pubkeys length` | `names` does not have one entry per address. | Send one `names` entry per address, `null` for none. |
| 400 | `bad_request` | `Name must be 25 characters or less` | A name is longer than 25 characters. | Shorten the name to 25 characters or fewer. |
| 400 | `bad_request` | `Images array must match pubkeys length` | `images` does not have one entry per address. | Send one `images` entry per address, `null` for none. |
| 400 | `bad_request` | `Icons array must match pubkeys length` | `icons` does not have one entry per address. | Send one `icons` entry per address, `null` for none. |
| 400 | `bad_request` | `Icon must be 20 characters or less` | An icon is longer than 20 characters. | Shorten the icon to 20 characters or fewer. |
| 400 | `bad_request` | `Invalid pubkey: <pubkey>` | On SVM, an address is not a valid Solana address. | Check that every address is a valid base58 public key. |
| 400 | `bad_request` | `Invalid evm address: <pubkey>` | On EVM, an address is not a valid EVM address. | Check that every address is a valid `0x` address. |
| 400 | `bad_request` | `Invalid base64 image at index <i>` | An image is not valid base64. | Send each image as base64-encoded bytes. |
| 400 | `bad_request` | `Image at index <i> too large (max 2MB)` | An image is larger than 2 MB once decoded. | Send images of 2 MB or less. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/svm/watch/add" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "pubkeys": [
    "DD4FUCY8FRnqJWxXg3UJ7PsouHXGjkkLmPa2YSwr4bVh"
  ],
  "names": [
    "Whale 1"
  ],
  "images": [
    null
  ],
  "icons": [
    null
  ],
  "is_bookmark": [
    true
  ]
}'
```

#### Example response

```json
{
  "ok": true
}
```

### Update a wallet

`POST /wallets/rename`

Sets the name, icon, image or bookmark flag of a wallet or watched address. (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 wallet in the same state.

Omit a field to leave it unchanged; send `null` to clear it. The network is read from the address format. The web app uses it to edit watchlist entries and to toggle bookmarks.

#### Body parameters

- `pubkey` (string, required): Address to update.
- `name` (string | null, optional): New label, 1 to 25 characters. `null` clears it.
- `icon` (string | null, optional): New text icon, at most 20 characters. `null` clears it.
- `image` (string | null, optional): New avatar as base64-encoded image data, at most 2 MB. `null` removes it.
- `is_bookmark` (boolean, optional): Bookmark flag.

#### Returns 200 OK

- `ok` (boolean): Always `true` on success.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Invalid pubkey` | `pubkey` is not a valid address. | Send a valid Solana or `0x` address. |
| 400 | `bad_request` | `Name must be 25 characters or less` | `name` is longer than 25 characters. | Shorten `name` to 25 characters or fewer. |
| 400 | `bad_request` | `Name cannot be empty, use null to clear` | `name` is an empty string. | Send `null` to clear the name. |
| 400 | `bad_request` | `Icon must be 20 characters or less` | `icon` is longer than 20 characters. | Shorten `icon` to 20 characters or fewer. |
| 400 | `bad_request` | `Invalid base64 image data` | `image` is not valid base64. | Send `image` as base64-encoded bytes. |
| 422 | `unprocessable` | `Image too large (max 2MB)` | The image is larger than 2 MB. | Send an image of 2 MB or less. |
| 500 | `internal_error` | `Wallet not found` | The address is not a wallet of the account. Returned as a 500, not a 404. | Use an address from [List wallets](/reference/wallets/#list-wallets) or [List watch wallets](/reference/wallets/#list-watch-wallets). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/rename" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "pubkey": "DD4FUCY8FRnqJWxXg3UJ7PsouHXGjkkLmPa2YSwr4bVh",
  "name": "Whale 1",
  "is_bookmark": true
}'
```

#### Example response

```json
{
  "ok": true
}
```

### List watch wallets

`GET /wallets/watch/list`

Returns every watched address of the account, SVM and EVM, most recent first. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Returns 200 OK

Returns a list of [Watch wallet](#object-watch-wallet) objects.

- `wallets` (array<object>): Watched addresses.

#### Example request

```bash
curl "https://api-mig.proxima.tools/wallets/watch/list" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "wallets": [
    {
      "pubkey": "DD4FUCY8FRnqJWxXg3UJ7PsouHXGjkkLmPa2YSwr4bVh",
      "network_type": "svm",
      "name": "Whale 1",
      "icon": null,
      "image_link": null,
      "is_bookmark": true,
      "created_at": 1792310400
    }
  ]
}
```

### Remove watch wallets

`POST /wallets/watch/remove`

Removes addresses from the watchlist. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Addresses that are not watched are skipped, so a repeat returns `removed: 0`.

#### Body parameters

- `pubkeys` (array<string>, required): Addresses to stop watching. SVM and EVM addresses can be mixed.

#### Returns 200 OK

- `removed` (integer): Number of watched wallets removed. Addresses that were not watched are skipped.

#### 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` | `Invalid pubkey: <pubkey>` | An address is neither a `0x` address nor a valid Solana address. | Check every address in `pubkeys`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/wallets/watch/remove" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "pubkeys": [
    "DD4FUCY8FRnqJWxXg3UJ7PsouHXGjkkLmPa2YSwr4bVh"
  ]
}'
```

#### Example response

```json
{
  "removed": 2
}
```
