# Keys

> List, export, import and batch-edit the secret keys of a license's wallets.

The keys vault gives a license direct access to its wallets' secret keys, one network at a time (`svm` or `evm`; EVM wallets are shared by every EVM chain). It is only available to licenses with `can_manage_keys` on the [License](/reference/licenses/#object-license); without it every route except `GET /keys/status` answers `403`.

Reading secrets (`list` and `export`) is protected by the `keys.export` [2FA action](/reference/two-factor/), on by default once 2FA is enabled. A passed challenge unlocks the session for the current license for 10 minutes, so further pages and exports need no new code; any change to the user's 2FA settings closes the window. `POST /keys/unlock` opens the window up front and `GET /keys/status` reports the time left. Importing and editing never require 2FA.

Every call is recorded in the activity history (`keys.unlock`, `keys.list`, `keys.export`, `keys.import`, `keys.update`) with pubkeys, IP and user agent, never secrets.

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

## Endpoints

- `GET /keys/status`: Retrieve vault status
- `POST /keys/unlock`: Unlock the vault
- `POST /keys/{network_type}/list`: List keys
- `POST /keys/{network_type}/export`: Export keys
- `POST /keys/{network_type}/import`: Import keys
- `POST /keys/{network_type}/update`: Update wallets

## The Key object

A wallet of the license with its secret key.

- `id` (integer | null): Wallet id, used as pagination cursor. `null` for EVM universal funders, which are not regular wallets.
- `pubkey` (string): Wallet address.
- `secret` (string): Secret key in storage format: base58 of the 64-byte keypair on SVM, hex without `0x` on EVM.
- `kind` (enum): Wallet kind. Possible values: `fresh`, `aged`, `funder`, `archived`.
- `name` (string | null): Wallet name.
- `tag_ids` (array<integer>): Ids of the wallet's tags.
- `created_at` (integer): Creation time, in Unix seconds.
- `roles` (array<object>): Roles of the wallet in the selected launches. Present only when the selector has `launch_ext_ids`.
  - `launch` (string): Launch external id.
  - `role` (enum): Role in the launch. SVM uses `front_mev` and `back_mev`, EVM uses `mev`. Possible values: `dev`, `funder`, `front_mev`, `back_mev`, `mev`, `holder`, `temp_holder`.

```json
{
  "id": 48211,
  "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F",
  "secret": "3xYp8RkVb2NqTz7HcWm5Ld9GsJf4Ae6KuQ1Bt3Ew8Mh2Zn5Vr7Cy4Pk9Ds2Gx6Lb3Hq8Wt5Jm1Nf4Re7Uz2Ka9Vb",
  "kind": "aged",
  "name": "sniper 1",
  "tag_ids": [
    12
  ],
  "created_at": 1792404000,
  "roles": [
    {
      "launch": "101453179751265",
      "role": "holder"
    }
  ]
}
```

## The Key import result object

The outcome of one entry of an import, in the order of the submitted `secrets`.

- `index` (integer): Position of the entry in `secrets`.
- `status` (enum): `imported`: new key, or a watched wallet that receives its secret. `restored`: archived key set back to `aged`. `already_present`: nothing written, tags still applied. `duplicate`: same key earlier in the request. `invalid`: unreadable, see `reason`. Possible values: `imported`, `restored`, `already_present`, `duplicate`, `invalid`.
- `pubkey` (string): Wallet address, when the secret was readable.
- `reason` (string): Why the entry is invalid.

```json
{
  "index": 0,
  "status": "imported",
  "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F"
}
```

### Retrieve vault status

`GET /keys/status`

Returns whether the license can manage keys and how long the unlock window stays open. (Bearer JWT)

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

> Not called by the current web app.

#### Returns 200 OK

- `can_manage_keys` (boolean): Whether the license may use the keys vault.
- `export_requires_2fa` (boolean): Whether reading secrets currently needs a `keys.export` challenge.
- `unlocked_for_secs` (integer): Seconds left in the unlock window, `0` when closed.

#### Example request

```bash
curl "https://api-mig.proxima.tools/keys/status" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "can_manage_keys": true,
  "export_requires_2fa": true,
  "unlocked_for_secs": 412
}
```

### Unlock the vault

`POST /keys/unlock`

Opens a 10-minute window in which secrets can be read without a new 2FA code. (Bearer JWT · 2FA step-up)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `keys.export` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. Reopens the 10-minute window. When `keys.export` is protected, each call needs a new challenge.

Asks for the `keys.export` challenge when it is protected. Without 2FA the window opens directly.

> Not called by the current web app.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `export_requires_2fa` (boolean): Whether `keys.export` is protected.
- `unlocked_for_secs` (integer): Length of the window, in seconds.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 403 | `forbidden` | `keys_not_enabled` | The license does not have `can_manage_keys`. | Use a license with key management enabled. `can_manage_keys` on [Retrieve the license](/reference/licenses/#retrieve-license) tells you. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/keys/unlock" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Example response

```json
{
  "ok": true,
  "export_requires_2fa": true,
  "unlocked_for_secs": 600
}
```

### List keys

`POST /keys/{network_type}/list`

Returns one page of wallets with their secret keys. (Bearer JWT · 2FA step-up)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `keys.export` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. Read-only, but each call is written to the key export audit log. While the vault is locked and `keys.export` is protected, each call needs a new challenge.

Without filters, returns every wallet of the license that has a secret, archived ones excluded. Each filter narrows the selection. For the next page, send the same selector with `cursor` set to `next_cursor`. EVM universal funders are returned on the first page only, and not when filtering by tag or launch.

The web app uses it to reveal a single wallet's private key (`pubkeys: [pubkey]`, `limit: 1`).

> A 2FA challenge is bound to the exact request body, so a new `cursor` would need a new code. Unlock the vault (or pass the first challenge) to page freely for 10 minutes.

#### Path parameters

- `network_type` (enum, required): Network. EVM wallets are shared by every EVM chain. Possible values: `svm`, `evm`.

#### Body parameters

- `pubkeys` (array<string>, optional): Only these wallets, up to 5,000. EVM addresses are case-insensitive.
- `tag_ids` (array<integer>, optional): Wallets with at least one of these tags.
- `kinds` (array<string>, optional): Wallet kinds among `fresh`, `aged`, `funder` and `archived`.
- `launch_ext_ids` (array<string>, optional): Wallets of these launches, up to 200, all on the path's network. Adds `roles` to each row. Numbers are accepted.
- `include_archived` (boolean, optional, default "false"): Include archived wallets. Implied when `kinds` contains `archived`.
- `cursor` (string, optional): Cursor from the previous page. Omit for the first page. A number is accepted.
- `limit` (integer, optional, default "1000"): Page size, up to 1,000. A numeric string is accepted.

#### Returns 200 OK

- `keys` (array<object>): List of [Key](#object-key) objects.
- `next_cursor` (integer | null): Cursor of the next page, or `null` on the last page.

#### 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`. |
| 400 | `bad_request` | `unknown kind '<kind>', expected one of fresh, aged, funder, archived` | `kinds` contains an unknown kind. | Use only `fresh`, `aged`, `funder` and `archived`. |
| 400 | `bad_request` | `at most 5000 pubkeys per call` | `pubkeys` has more than 5,000 entries. | Split the selection into several calls. |
| 400 | `bad_request` | `at most 200 launches per call` | `launch_ext_ids` has more than 200 entries. | Split the selection into several calls. |
| 400 | `bad_request` | `invalid launch id format` | A launch id in `launch_ext_ids` is malformed. | Send launch ids as the API returns them. |
| 400 | `bad_request` | `launch <launch_id> is not on <network_type>` | A launch in `launch_ext_ids` is on the other network than `{network_type}`. | Remove the launch, or call the endpoint of the launch's network. |
| 400 | `bad_request` | `cursor out of range` | `cursor` is out of range. | Send the `next_cursor` of the previous page. |
| 403 | `forbidden` | `keys_not_enabled` | The license does not have `can_manage_keys`. | Use a license with key management enabled. `can_manage_keys` on [Retrieve the license](/reference/licenses/#retrieve-license) tells you. |
| 404 | `not_found` | `launch not found` | A launch in `launch_ext_ids` does not exist or does not belong to the license. | Remove the launch from `launch_ext_ids`. |

#### Example request

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

#### Example response

```json
{
  "keys": [
    {
      "id": 48211,
      "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F",
      "secret": "3xYp8RkVb2NqTz7HcWm5Ld9GsJf4Ae6KuQ1Bt3Ew8Mh2Zn5Vr7Cy4Pk9Ds2Gx6Lb3Hq8Wt5Jm1Nf4Re7Uz2Ka9Vb",
      "kind": "aged",
      "name": "sniper 1",
      "tag_ids": [
        12
      ],
      "created_at": 1792404000
    }
  ],
  "next_cursor": null
}
```

### Export keys

`POST /keys/{network_type}/export`

Downloads every selected wallet with its secret key as one JSON or CSV file. (Bearer JWT · 2FA step-up)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `keys.export` when the user protects it (`401 2fa_required`).
- Retry: Safe to retry. Read-only, but each call is written to the key export audit log. While the vault is locked and `keys.export` is protected, each call needs a new challenge.

Takes the same selector as [List keys](#list). The response is a file with a `Content-Disposition: attachment` header (for example `keys-svm-20261102-100000.json`). The CSV columns are `pubkey,secret,kind,name,tag_ids,created_at,roles`, with `tag_ids` and `roles` (`launch:role`) separated by spaces.

The web app exports JSON for selected wallets or a folder and rewrites the rows as `{ name, pubkey, privatekey }` before saving them.

> The file contains private keys in clear. Anyone holding it controls the funds of those wallets.

#### Path parameters

- `network_type` (enum, required): Network. EVM wallets are shared by every EVM chain. Possible values: `svm`, `evm`.

#### Body parameters

- `pubkeys` (array<string>, optional): Only these wallets, up to 5,000. EVM addresses are case-insensitive.
- `tag_ids` (array<integer>, optional): Wallets with at least one of these tags.
- `kinds` (array<string>, optional): Wallet kinds among `fresh`, `aged`, `funder` and `archived`.
- `launch_ext_ids` (array<string>, optional): Wallets of these launches, up to 200, all on the path's network. Adds `roles` to each row. Numbers are accepted.
- `include_archived` (boolean, optional, default "false"): Include archived wallets. Implied when `kinds` contains `archived`.
- `format` (enum, optional, default "json"): File format. Possible values: `json`, `csv`.

#### Returns 200 OK

With `format: "json"`, a JSON file; with `format: "csv"`, a `text/csv` file.

- `network` (enum): Exported network. Possible values: `svm`, `evm`.
- `count` (integer): Number of keys.
- `keys` (array<object>): List of [Key](#object-key) objects.

#### 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`. |
| 400 | `bad_request` | `unknown kind '<kind>', expected one of fresh, aged, funder, archived` | `kinds` contains an unknown kind. | Use only `fresh`, `aged`, `funder` and `archived`. |
| 400 | `bad_request` | `at most 5000 pubkeys per call` | `pubkeys` has more than 5,000 entries. | Split the selection into several calls. |
| 400 | `bad_request` | `at most 200 launches per call` | `launch_ext_ids` has more than 200 entries. | Split the selection into several calls. |
| 400 | `bad_request` | `invalid launch id format` | A launch id in `launch_ext_ids` is malformed. | Send launch ids as the API returns them. |
| 400 | `bad_request` | `launch <launch_id> is not on <network_type>` | A launch in `launch_ext_ids` is on the other network than `{network_type}`. | Remove the launch, or call the endpoint of the launch's network. |
| 403 | `forbidden` | `keys_not_enabled` | The license does not have `can_manage_keys`. | Use a license with key management enabled. `can_manage_keys` on [Retrieve the license](/reference/licenses/#retrieve-license) tells you. |
| 404 | `not_found` | `launch not found` | A launch in `launch_ext_ids` does not exist or does not belong to the license. | Remove the launch from `launch_ext_ids`. |
| 422 | `unprocessable` | `more than 50000 keys selected, narrow the selection` | The selection has more than 50,000 keys. Narrow it. | Add filters, or split the export by tag, kind or launch. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/keys/svm/export" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "pubkeys": [
    "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F",
    "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh"
  ],
  "format": "json"
}'
```

#### Example response

```json
{
  "network": "svm",
  "count": 1,
  "keys": [
    {
      "id": 48211,
      "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F",
      "secret": "3xYp8RkVb2NqTz7HcWm5Ld9GsJf4Ae6KuQ1Bt3Ew8Mh2Zn5Vr7Cy4Pk9Ds2Gx6Lb3Hq8Wt5Jm1Nf4Re7Uz2Ka9Vb",
      "kind": "aged",
      "name": "sniper 1",
      "tag_ids": [
        12
      ],
      "created_at": 1792404000
    }
  ]
}
```

### Import keys

`POST /keys/{network_type}/import`

Adds wallets to the license from their secret keys. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A key that is already present comes back as `already_present` and is not added twice.

Accepted secrets: on SVM, base58 of a 64-byte keypair or a 32-byte seed, or a byte array (the content of a `solana-keygen` file, as an array or as text); on EVM, 32-byte hex with or without `0x`. Send `dry_run: true` first to get the report without writing anything, then the same body without it.

The Import keys modal of the wallets page calls this, and refreshes the wallet lists when anything was imported or restored.

> The batch is written in one transaction: either every valid key is saved or none is. The request body is limited to 4 MB.

#### Path parameters

- `network_type` (enum, required): Network. EVM wallets are shared by every EVM chain. Possible values: `svm`, `evm`.

#### Body parameters

- `secrets` (array<string | object>, required): Up to 5,000 entries, each the secret alone or `{ "secret": ..., "name": "..." }`. `name` is up to 25 characters.
- `tag_ids` (array<integer>, optional): Tags applied to every valid key of the batch, including keys already present.
- `dry_run` (boolean, optional, default "false"): Validate and compute statuses without writing.
- `on_existing` (enum, optional, default "restore"): What to do with a key that is present but archived. Possible values: `restore`, `skip`.

#### Returns 200 OK

- `dry_run` (boolean): Whether nothing was written.
- `counts` (object): Number of entries per status: `imported`, `restored`, `already_present`, `duplicate`, `invalid`.
- `results` (array<object>): List of [Key import result](#object-key-import-result) objects, in the order of `secrets`.

#### 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`. |
| 400 | `bad_request` | `nothing to import` | `secrets` is empty. | Send at least one secret. |
| 400 | `bad_request` | `at most 5000 keys per call` | `secrets` has more than 5,000 entries. | Split the import into several calls. |
| 400 | `bad_request` | `Some tags not found or unauthorized` | A tag in `tag_ids` does not belong to the license. Nothing is written. | Send only ids of the license's wallet folders. |
| 403 | `forbidden` | `keys_not_enabled` | The license does not have `can_manage_keys`. | Use a license with key management enabled. `can_manage_keys` on [Retrieve the license](/reference/licenses/#retrieve-license) tells you. |
| 422 | `unprocessable` | `Exceeded max wallet limit: <active> active, <adding> to add, <max> allowed` | The import would exceed the license's wallet limit. Nothing is written. | Import fewer keys, or archive wallets first. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/keys/svm/import" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "secrets": [
    "3xYp8RkVb2NqTz7HcWm5Ld9GsJf4Ae6KuQ1Bt3Ew8Mh2Zn5Vr7Cy4Pk9Ds2Gx6Lb3Hq8Wt5Jm1Nf4Re7Uz2Ka9Vb",
    {
      "secret": "[12,201,4,...]",
      "name": "sniper 1"
    },
    "not-a-key"
  ],
  "tag_ids": [
    12
  ],
  "dry_run": true
}'
```

#### Example response

```json
{
  "dry_run": true,
  "counts": {
    "imported": 2,
    "restored": 0,
    "already_present": 0,
    "duplicate": 0,
    "invalid": 1
  },
  "results": [
    {
      "index": 0,
      "status": "imported",
      "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F"
    },
    {
      "index": 1,
      "status": "imported",
      "pubkey": "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh"
    },
    {
      "index": 2,
      "status": "invalid",
      "reason": "invalid base58"
    }
  ]
}
```

### Update wallets

`POST /keys/{network_type}/update`

Renames wallets and adds or removes tags in one batch. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Names and tags are set, not toggled, so repeating the call changes nothing.

For `name`, a value sets it, `""` clears it and an absent field leaves it unchanged. `add_tag_ids` and `remove_tag_ids` apply to every listed wallet. To archive wallets use the wallets endpoints; a wallet's secret cannot be replaced.

> Not called by the current web app.

#### Path parameters

- `network_type` (enum, required): Network. EVM wallets are shared by every EVM chain. Possible values: `svm`, `evm`.

#### Body parameters

- `wallets` (array<object>, required): Wallets to edit, up to 5,000.
  - `pubkey` (string, required): Wallet address.
  - `name` (string, optional): New name. `""` clears it.
- `add_tag_ids` (array<integer>, optional): Tags to add to every listed wallet.
- `remove_tag_ids` (array<integer>, optional): Tags to remove from every listed wallet.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `updated` (integer): Wallets edited.
- `renamed` (integer): Wallets whose name changed.

#### 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`. |
| 400 | `bad_request` | `no wallets given` | `wallets` is empty. | Send at least one wallet. |
| 400 | `bad_request` | `at most 5000 wallets per call` | `wallets` has more than 5,000 entries. | Split the update into several calls. |
| 400 | `bad_request` | `Name must be 25 characters or less (<pubkey>)` | A `name` is longer than 25 characters after trimming. The message names the wallet. | Shorten the name to 25 characters. |
| 400 | `bad_request` | `Some tags not found or unauthorized` | A tag does not belong to the license. | Send only ids of the license's wallet folders. |
| 403 | `forbidden` | `keys_not_enabled` | The license does not have `can_manage_keys`. | Use a license with key management enabled. `can_manage_keys` on [Retrieve the license](/reference/licenses/#retrieve-license) tells you. |
| 404 | `not_found` | `<count> wallet(s) not found on this license: <pubkeys>` | A wallet is not in the license. Nothing is written. The message lists up to five missing addresses. | Remove the listed addresses from `wallets`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/keys/svm/update" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "wallets": [
    {
      "pubkey": "9fGhT2kWm4Ys7QpRn3DxEb6ZcVa8Jt5LuN1HwKq2Ms7F",
      "name": "renamed"
    },
    {
      "pubkey": "DkR4mWq7TzY2bNc9HvJ3sLp8XfGa5Ue6Kt1Qw2Ey4Mh",
      "name": ""
    },
    {
      "pubkey": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P"
    }
  ],
  "add_tag_ids": [
    14
  ],
  "remove_tag_ids": [
    12
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "updated": 3,
  "renamed": 2
}
```
