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; without it every route except GET /keys/status answers 403.
Reading secrets (list and export) is protected by the keys.export 2FA action, 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.
The Key object
A wallet of the license with its secret key.
Attributes
-
idinteger | nullWallet id, used as pagination cursor.nullfor EVM universal funders, which are not regular wallets. -
pubkeystringWallet address. -
secretstringSecret key in storage format: base58 of the 64-byte keypair on SVM, hex without0xon EVM. -
kindenumWallet kind.Possible valuesfreshagedfunderarchived -
namestring | nullWallet name. -
tag_idsarray<integer>Ids of the wallet's tags. -
created_atintegerCreation time, in Unix seconds. -
rolesarray<object>Roles of the wallet in the selected launches. Present only when the selector haslaunch_ext_ids.Child attributes 2
-
launchstringLaunch external id. -
roleenumRole in the launch. SVM usesfront_mevandback_mev, EVM usesmev.Possible valuesdevfunderfront_mevback_mevmevholdertemp_holder
-
The Key import result object
The outcome of one entry of an import, in the order of the submitted secrets.
Attributes
-
indexintegerPosition of the entry insecrets. -
statusenumimported: new key, or a watched wallet that receives its secret.restored: archived key set back toaged.already_present: nothing written, tags still applied.duplicate: same key earlier in the request.invalid: unreadable, seereason.Possible valuesimportedrestoredalready_presentduplicateinvalid -
pubkeystringWallet address, when the secret was readable. -
reasonstringWhy the entry is invalid.
Retrieve vault status
/keys/status Returns whether the license can manage keys and how long the unlock window stays open.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Parameters
No parameters.
Returns 200 OK · application/json
-
can_manage_keysbooleanWhether the license may use the keys vault. -
export_requires_2fabooleanWhether reading secrets currently needs akeys.exportchallenge. -
unlocked_for_secsintegerSeconds left in the unlock window,0when closed.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.
Web client proxima.keys.status() src/lib/proxima/endpoints/keys.ts
Unlock the vault
/keys/unlock Opens a 10-minute window in which secrets can be read without a new 2FA code.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
keys.exportwhen the user protects it. How it works - Retry
- Safe to retry Reopens the 10-minute window. When
keys.exportis protected, each call needs a new challenge.
Asks for the keys.export challenge when it is protected. Without 2FA the window opens directly.
Parameters
No parameters.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
export_requires_2fabooleanWhetherkeys.exportis protected. -
unlocked_for_secsintegerLength of the window, in seconds.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The license does not have can_manage_keys. Use a license with key management enabled. can_manage_keys on Retrieve the license tells you. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.keys.unlock() src/lib/proxima/endpoints/keys.ts
/keys/{network_type}/list Returns one page of wallets with their secret keys.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
keys.exportwhen the user protects it. How it works - Retry
- Safe to retry Read-only, but each call is written to the key export audit log. While the vault is locked and
keys.exportis 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).
Path parameters
-
network_typeenum RequiredNetwork. EVM wallets are shared by every EVM chain.Possible valuessvmevm
Body parameters application/json
-
pubkeysarray<string> OptionalOnly these wallets, up to 5,000. EVM addresses are case-insensitive. -
tag_idsarray<integer> OptionalWallets with at least one of these tags. -
kindsarray<string> OptionalWallet kinds amongfresh,aged,funderandarchived. -
launch_ext_idsarray<string> OptionalWallets of these launches, up to 200, all on the path's network. Addsrolesto each row. Numbers are accepted. -
include_archivedboolean OptionalInclude archived wallets. Implied whenkindscontainsarchived. -
cursorstring OptionalCursor from the previous page. Omit for the first page. A number is accepted. -
limitinteger OptionalPage size, up to 1,000. A numeric string is accepted.
Returns 200 OK · application/json
-
keysarray<object>List of Key objects. -
next_cursorinteger | nullCursor of the next page, ornullon the last page.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | {network_type} is not svm or evm. Use svm or evm. |
| 400 | bad_request | kinds contains an unknown kind. Use only fresh, aged, funder and archived. |
| 400 | bad_request | pubkeys has more than 5,000 entries. Split the selection into several calls. |
| 400 | bad_request | launch_ext_ids has more than 200 entries. Split the selection into several calls. |
| 400 | bad_request | A launch id in launch_ext_ids is malformed. Send launch ids as the API returns them. |
| 400 | bad_request | 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 is out of range. Send the next_cursor of the previous page. |
| 403 | forbidden | The license does not have can_manage_keys. Use a license with key management enabled. can_manage_keys on Retrieve the license tells you. |
| 404 | 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. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.keys.list(network, request) src/lib/proxima/endpoints/keys.ts
Export keys
/keys/{network_type}/export Downloads every selected wallet with its secret key as one JSON or CSV file.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Two-factor
- Step-up for
keys.exportwhen the user protects it. How it works - Retry
- Safe to retry Read-only, but each call is written to the key export audit log. While the vault is locked and
keys.exportis protected, each call needs a new challenge.
Takes the same selector as List keys. 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.
Path parameters
-
network_typeenum RequiredNetwork. EVM wallets are shared by every EVM chain.Possible valuessvmevm
Body parameters application/json
-
pubkeysarray<string> OptionalOnly these wallets, up to 5,000. EVM addresses are case-insensitive. -
tag_idsarray<integer> OptionalWallets with at least one of these tags. -
kindsarray<string> OptionalWallet kinds amongfresh,aged,funderandarchived. -
launch_ext_idsarray<string> OptionalWallets of these launches, up to 200, all on the path's network. Addsrolesto each row. Numbers are accepted. -
include_archivedboolean OptionalInclude archived wallets. Implied whenkindscontainsarchived. -
formatenum OptionalFile format.Possible valuesjsoncsv
Returns 200 OK · application/json
With format: "json", a JSON file; with format: "csv", a text/csv file.
-
networkenumExported network.Possible valuessvmevm -
countintegerNumber of keys. -
keysarray<object>List of Key objects.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | {network_type} is not svm or evm. Use svm or evm. |
| 400 | bad_request | kinds contains an unknown kind. Use only fresh, aged, funder and archived. |
| 400 | bad_request | pubkeys has more than 5,000 entries. Split the selection into several calls. |
| 400 | bad_request | launch_ext_ids has more than 200 entries. Split the selection into several calls. |
| 400 | bad_request | A launch id in launch_ext_ids is malformed. Send launch ids as the API returns them. |
| 400 | bad_request | 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 | The license does not have can_manage_keys. Use a license with key management enabled. can_manage_keys on Retrieve the license tells you. |
| 404 | 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 | The selection has more than 50,000 keys. Narrow it. Add filters, or split the export by tag, kind or launch. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token, 401 2fa_required and 429 when rate limited.
Web client proxima.keys.exportFile(network, { ...selector, format }) src/lib/proxima/endpoints/keys.ts
Import keys
/keys/{network_type}/import Adds wallets to the license from their secret keys.
- 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_presentand 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.
Path parameters
-
network_typeenum RequiredNetwork. EVM wallets are shared by every EVM chain.Possible valuessvmevm
Body parameters application/json
-
secretsarray<string | object> RequiredUp to 5,000 entries, each the secret alone or{ "secret": ..., "name": "..." }.nameis up to 25 characters. -
tag_idsarray<integer> OptionalTags applied to every valid key of the batch, including keys already present. -
dry_runboolean OptionalValidate and compute statuses without writing. -
on_existingenum OptionalWhat to do with a key that is present but archived.Possible valuesrestoreskip
Returns 200 OK · application/json
-
dry_runbooleanWhether nothing was written. -
countsobjectNumber of entries per status:imported,restored,already_present,duplicate,invalid. -
resultsarray<object>List of Key import result objects, in the order ofsecrets.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | {network_type} is not svm or evm. Use svm or evm. |
| 400 | bad_request | secrets is empty. Send at least one secret. |
| 400 | bad_request | secrets has more than 5,000 entries. Split the import into several calls. |
| 400 | bad_request | 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 | The license does not have can_manage_keys. Use a license with key management enabled. can_manage_keys on Retrieve the license tells you. |
| 422 | unprocessable | The import would exceed the license's wallet limit. Nothing is written. Import fewer keys, or archive wallets first. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client proxima.keys.import(network, request) src/lib/proxima/endpoints/keys.ts
Update wallets
/keys/{network_type}/update Renames wallets and adds or removes tags in one batch.
- 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.
Path parameters
-
network_typeenum RequiredNetwork. EVM wallets are shared by every EVM chain.Possible valuessvmevm
Body parameters application/json
-
walletsarray<object> RequiredWallets to edit, up to 5,000.Child attributes 2
-
pubkeystring RequiredWallet address. -
namestring OptionalNew name.""clears it.
-
-
add_tag_idsarray<integer> OptionalTags to add to every listed wallet. -
remove_tag_idsarray<integer> OptionalTags to remove from every listed wallet.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
updatedintegerWallets edited. -
renamedintegerWallets whose name changed.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | {network_type} is not svm or evm. Use svm or evm. |
| 400 | bad_request | wallets is empty. Send at least one wallet. |
| 400 | bad_request | wallets has more than 5,000 entries. Split the update into several calls. |
| 400 | bad_request | A name is longer than 25 characters after trimming. The message names the wallet. Shorten the name to 25 characters. |
| 400 | bad_request | A tag does not belong to the license. Send only ids of the license's wallet folders. |
| 403 | forbidden | The license does not have can_manage_keys. Use a license with key management enabled. can_manage_keys on Retrieve the license tells you. |
| 404 | not_found | A wallet is not in the license. Nothing is written. The message lists up to five missing addresses. Remove the listed addresses from wallets. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client proxima.keys.update(network, request) src/lib/proxima/endpoints/keys.ts