Skip to main content
Version: release (v0.77)

JSON-RPC Wallet API


client.connect_wallet​

This method initiates a connection between a wallet and a third-party application.

The user has to review the request, and, if they accept it, select the wallet they want to use for this connection.

Supported connections:

  • Multiple wallets connected for the same hostname.
  • A single wallet connected to multiple hostnames.
  • Combination of the above setups.

However, it's not possible to have multiple connections on the same wallet for the same hostname. The previous connection will be terminated and a new one will be initiated.

This method should be the entry point of every third-party application.

Parameters​

None required

Result: Success​

Errors​

  • User error (3000): the user closed the connection
  • Application error (2001): the application cancelled the request
  • User error (3001): the user rejected the wallet connection
  • User error (3002): the user cancelled the request
  • User error (3002): the user cancelled the request

Examples​

Accepting a connection from "vega.xyz"​

The third-party application "vega.xyz" requests a connection to a wallet and the user accepts.

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.connect_wallet",
"params": []
}
Result​
{
"name": "Success",
"value": "null"
}

client.disconnect_wallet​

This method ends the connection between the third-party application and the wallet.

Parameters​

None required

Examples​

Disconnection from "vega.xyz"​

The third-party application "vega.xyz" requests a disconnection to a wallet.

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.disconnect_wallet",
"params": []
}
Result​
{
"name": "Success",
"value": null
}

client.list_keys​

This method returns the keys the user has allowed the third-party application to have access to.

It requires a read access on public_keys.

Parameters​

None required

Result: Success​

Result keyTypeDescriptionExample
keysarray--

Examples​

List keys allowed on "vega.xyz"​

The third-party application "vega.xyz" wants to list the public keys it has access to.

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.list_keys",
"params": []
}
Result​
{
"name": "Success",
"value": {
"keys": [
{
"name": "Key 1",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
},
{
"name": "Key 2",
"publicKey": "988eae323a07f12363c17025c23ee58ea32ac3912398e16bb0b56969f57adc52"
}
]
}
}

client.sign_transaction​

This method signs a transaction and returns it to the third-party application, without sending it to the network. What happens with the transaction is up to the third-party application.

The user has to review the transaction.

Parameters​

Parameter nameTypeDescription
publicKeystringThe Vega public key to use.
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

Errors​

  • Network error (1000): no healthy node available
  • Network error (1000): could not get the chain ID from the node
  • Network error (1000): could not get information about the last block on the network
  • Application error (2000): the public key is not allowed to be used
  • User error (3000): the user closed the connection
  • User error (3001): the user rejected the wallet connection
  • User error (3002): the user cancelled the request
  • Application error (2000): the transaction will break the network's spam rules
  • Application error (2000): the block height is too historic
  • Application error (2000): the transaction per block limit has been reached

Examples​

Signing a transaction for "vega.xyz"​

The third-party application "vega.xyz" requests to sign a transaction and the user accepts.

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.sign_transaction",
"params": {
"publicKey": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80",
"sendingMode": "TYPE_SYNC",
"transaction": {}
}
}
Result​
{
"name": "Success",
"value": {
"receivedAt": "2021-02-18T21:54:42.123Z",
"sentAt": "2021-02-18T21:54:42.123Z",
"txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3"
}
}

client.send_transaction​

This method sends a transaction to the network.

The user has to review the transaction.

Parameters​

Parameter nameTypeDescription
publicKeystringThe Vega public key to use.
sendingModestringThe chosen mode to send the transaction:
- TYPE_SYNC returns the result of running the transaction.
- TYPE_ASYNC returns right away without waiting to hear if the transaction is even valid.
- TYPE_COMMIT waits until the transaction is committed in a block, or until some timeout is reached, or returns return right away if the transaction is not valid.
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
receivedAtstringThe date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
sentAtstringThe date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
transactionHashstringThe hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

Errors​

  • Network error (1000): no healthy node available
  • Network error (1000): could not get the chain ID from the node
  • Network error (1000): could not get information about the last block on the network
  • Network error (1001): the transaction failed
  • User error (3000): the user closed the connection
  • User error (3001): the user rejected the wallet connection
  • User error (3002): the user cancelled the request
  • Application error (2000): the public key is not allowed to be used
  • Application error (2000): the transaction will break the network's spam rules
  • Application error (2000): the block height is too historic
  • Application error (2000): the transaction per block limit has been reached

Examples​

Sending a transaction for "vega.xyz"​

The third-party application "vega.xyz" requests to send a transaction and the user accepts.

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.send_transaction",
"params": {
"publicKey": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80",
"sendingMode": "TYPE_SYNC",
"encodedTransaction": "ewogICAgInZvdGVTdWJtaXNzaW9uIjogewogICAgICAgICJwcm9wb3NhbElkIjogImViMmQzOTAyZmRkYTljM2ViNmUzNjlmMjIzNTY4OWI4NzFjNzMyMmNmM2FiMjg0ZGRlM2U5ZGZjMTM4NjNhMTciLAogICAgICAgICJ2YWx1ZSI6ICJWQUxVRV9ZRVMiCiAgICB9Cn0K"
}
}
Result​
{
"name": "Success",
"value": {
"receivedAt": "2021-02-18T21:54:42.123Z",
"sentAt": "2021-02-18T21:54:42.123Z",
"txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3"
}
}

client.check_transaction​

This method sends a transaction or a bundle of transactions to the network to verify their validity.

The network does not add them to a block. What happens with the transaction is up to the third-party application.

The user has to review the transaction after this step.

Parameters​

Parameter nameTypeDescription
publicKeystringThe Vega public key to use.
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
receivedAtstringThe date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
sentAtstringThe date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

Errors​

  • Network error (1000): no healthy node available
  • Network error (1000): could not get the chain ID from the node
  • Network error (1000): could not get information about the last block on the network
  • Network error (1001): the transaction failed
  • User error (3000): the user closed the connection
  • User error (3001): the user rejected the wallet connection
  • User error (3002): the user cancelled the request
  • Application error (2000): the public key is not allowed to be used
  • Application error (2000): the transaction will break the network's spam rules
  • Application error (2000): the block height is too historic
  • Application error (2000): the transaction per block limit has been reached

Examples​

Check a transaction for "vega.xyz"​

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.check_transaction",
"params": {
"publicKey": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80",
"transaction": {}
}
}
Result​
{
"name": "Success",
"value": {
"receivedAt": "2021-02-18T21:54:42.123Z",
"sentAt": "2021-02-18T21:54:42.123Z",
"txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3"
}
}

client.get_chain_id​

This method returns the chain ID of the network in use.

It should be called by every third-party application to know from which network it should fetch data.

Parameters​

None required

Result: Success​

Result keyTypeDescriptionExample
chainIDstringThe chain identifierThe chain identifier

Errors​

  • Network error (1000): no healthy node available
  • Network error (1000): could not get information about the last block on the network

Examples​

Fetching the chain ID​

An example of requesting the chain's ID

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "client.get_chain_id",
"params": []
}
Result​
{
"name": "Success",
"value": {
"chainID": "test-chain-Thz9c6"
}
}

admin.create_wallet​

This method creates a HD wallet (with version 2 of the key derivation) and generates its first key-pair the cryptographic algorithm ed25519.

The passphrase will be used to encrypt the wallet and its keys.

If successful, the wallet is ready to use for sending transaction.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-

Result: Success​

Result keyTypeDescriptionExample
walletobjectthe newly generated walletthe newly generated wallet
keyobjectthe first public key generatedthe first public key generated

Examples​

Creating a wallet​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.create_wallet",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase"
}
}
Result​
{
"name": "Success",
"value": {
"wallet": {
"name": "my-wallet",
"keyDerivationVersion": 2,
"recoveryPhrase": "swing ceiling chaos green put insane ripple desk match tip melt usual shrug turkey renew icon parade veteran lens govern path rough page render"
},
"key": {
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"algorithm": {
"name": "vega/ed25519",
"version": 1
},
"metadata": [
{
"key": "name",
"value": "my-wallet key 1"
}
]
}
}
}

admin.import_wallet​

This method imports a wallet using the specified recovery phrase and a key derivation version, and generates its first key-pair.

The passphrase will be used to encrypt the wallet and its keys.

If successful, the wallet is ready to use for sending transaction.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
recoveryPhrasestring-
keyDerivationVersionnumber-

Result: Success​

Result keyTypeDescriptionExample
walletobjectthe imported walletthe imported wallet
keyobjectthe first public key generatedthe first public key generated

Examples​

Importing a wallet​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.import_wallet",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"recoveryPhrase": "swing ceiling chaos green put insane ripple desk match tip melt usual shrug turkey renew icon parade veteran lens govern path rough page render",
"keyDerivationVersion": "2"
}
}
Result​
{
"name": "Success",
"value": {
"wallet": {
"name": "my-wallet",
"keyDerivationVersion": 2
},
"key": {
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"algorithm": {
"name": "vega/ed25519",
"version": 1
},
"metadata": [
{
"key": "name",
"value": "my-wallet key 1"
}
]
}
}
}

admin.update_passphrase​

This method changes the passphrase used to lock the wallet.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
newPassphrasestring-

Result: Success​

Examples​

Update the passphrase​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.update_passphrase",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-the-old-passphrase",
"newPassphrase": "this-is-the-new-passphrase"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.describe_wallet​

This method returns the wallet base information such as its name, ID, type and key derivation version. It doesn't return the keys nor the permissions.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-

Result: Success​

Result keyTypeDescriptionExample
namestring--
keyDerivationVersionnumber--
idstring--
typestring--

Examples​

Getting wallet base information​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.describe_wallet",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase"
}
}
Result​
{
"name": "Success",
"value": {
"name": "my-wallet",
"keyDerivationVersion": 2,
"type": "HD Wallet",
"id": "7ffa36b2fb99d8404e9448f0d2ce944055e64c36d895d1fde044c867bfdf779f"
}
}

admin.list_wallets​

This method returns the list of the wallets present on the computer. It is alphabetically sorted.

Parameters​

None required

Result: Success​

Result keyTypeDescriptionExample
walletsarray--

Examples​

Getting the list of wallets​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.list_wallets",
"params": []
}
Result​
{
"name": "Success",
"value": {
"wallets": [
"wallet-1",
"wallet-2"
]
}
}

admin.rename_wallet​

This method renames a wallet in-place.

If the new name matches an existing wallet, it fails.

Parameters​

Parameter nameTypeDescription
walletstring-
newNamestring-

Result: Success​

Examples​

Rename a wallet​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.rename_wallet",
"params": {
"wallet": "my-wallet",
"newWallet": "my-new-wallet-name"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.remove_wallet​

This method removes a wallet from the computer.

Parameters​

Parameter nameTypeDescription
walletstring-

Result: Success​

Examples​

Remove a wallet​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.remove_wallet",
"params": {
"wallet": "my-wallet"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.list_networks​

This method returns the list of the registered networks.

Parameters​

None required

Result: Success​

Result keyTypeDescriptionExample
networksarray--

Examples​

Getting the list of networks​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.list_networks",
"params": []
}
Result​
{
"name": "Success",
"value": {
"networks": [
{
"name": "fairground",
"metadata": [
{
"key": "network",
"value": "testnet"
}
]
},
{
"name": "local-network"
}
]
}
}

admin.describe_network​

This method returns the network information.

Parameters​

Parameter nameTypeDescription
namestring-

Result: Success​

Result keyTypeDescriptionExample
namestring--
metadataarray--
apiobjectThe API configuration for the network.The API configuration for the network.
appsobjectThe URLs to the network applications.The URLs to the network applications.

Examples​

Describing a network​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.describe_network",
"params": {
"name": "local-network"
}
}
Result​
{
"name": "Success",
"value": {
"name": "local-network",
"metadata": [
{
"key": "network",
"value": "local"
}
],
"api": {
"grpcConfig": {
"hosts": [
"localhost:3028"
],
"retries": 5
},
"graphQLConfig": {
"hosts": [
"localhost:3028"
]
},
"restConfig": {
"hosts": [
"localhost:3029"
]
}
}
}
}

admin.update_network​

This method updates the network configuration.

Parameters​

Parameter nameTypeDescription
namestring-
metadata (Optional)array-
apiobjectThe API configuration for the network.



appsobjectThe URLs to the network applications.



Result: Success​

Examples​

Update a network​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.update_network",
"params": {
"name": "local-network",
"api": {
"grpcConfig": {
"hosts": [
"localhost:3028"
],
"retries": 5
},
"graphQLConfig": {
"hosts": [
"localhost:3028"
]
},
"restConfig": {
"hosts": [
"localhost:3029"
]
}
}
}
}
Result​
{
"name": "Success",
"value": null
}

admin.rename_network​

This method renames a network in-place.

If the new name matches an existing network, it fails.

Parameters​

Parameter nameTypeDescription
networkstring-
newNamestring-

Result: Success​

Examples​

Rename a network​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.rename_network",
"params": {
"network": "my-network",
"newWallet": "my-new-network-name"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.remove_network​

This method removes a network from the computer.

Parameters​

Parameter nameTypeDescription
namestring-

Result: Success​

Examples​

Remove a network​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.remove_network",
"params": {
"network": "fairground"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.import_network​

Import a network configuration from a file or an URL.

Parameters​

Parameter nameTypeDescription
name (Optional)stringThe name to give to the imported network. If unset the network's name will be taken from the imported definition
urlstringThe URL of a network to import. The prefix file:// can be used to indicate a file-path.
overwriteboolean-

Result: Success​

Result keyTypeDescriptionExample
namestring--

Examples​

Importing a network​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.import_network",
"params": {
"name": "local-network",
"url": "file:///Users/username/local-network.toml"
}
}
Result​
{
"name": "Success",
"value": {
"name": "local-network"
}
}

admin.generate_key​

This method generates a key on the specified wallet.

Metadata can be attached to this key.

A special metadata name can be provided to name the key. If no name is provided, a default name is generated.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
metadataarray-

Result: Success​

Result keyTypeDescriptionExample
publicKeystringThe Vega public key to use.The Vega public key to use.
algorithmobjectThe algorithm used to generate the key.The algorithm used to generate the key.
metadataarray--

Examples​

Generating a key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.generate_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"metadata": [
{
"name": "portfolio",
"value": "btc"
}
]
}
}
Result​
{
"name": "Success",
"value": {
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"algorithm": {
"name": "vega/ed25519",
"version": 1
},
"metadata": [
{
"key": "portfolio",
"value": "btc"
},
{
"key": "name",
"value": "Key 1"
}
]
}
}

admin.describe_key​

This method returns the information of the specified key.

It doesn't return the private key for security reasons. If you need something that requires a private key, you should use the available endpoints and let them handle the private key for you.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
publicKeystringThe Vega public key to use.

Result: Success​

Result keyTypeDescriptionExample
publicKeystringThe Vega public key to use.The Vega public key to use.
algorithmobjectThe algorithm used to generate the key.The algorithm used to generate the key.
metadataarray--
isTaintedbooleanTells if the key is tainted or not. A tainted key cannot be used for signing and sending transaction, for example.Tells if the key is tainted or not. A tainted key cannot be used for signing and sending transaction, for example.

Examples​

Getting key base information​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.describe_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
}
}
Result​
{
"name": "Success",
"value": {
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"algorithm": {
"name": "vega/ed25519",
"version": 1
},
"metadata": [
{
"key": "portfolio",
"value": "btc"
},
{
"key": "name",
"value": "Key 1"
}
],
"isTainted": false
}
}

admin.list_keys​

This method returns all generated key of the specified wallet with their respective name.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-

Result: Success​

Result keyTypeDescriptionExample
keysarray--

Examples​

Listing the keys​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.list_keys",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase"
}
}
Result​
{
"name": "Success",
"value": {
"keys": [
{
"name": "Key 1",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
}
]
}
}

admin.annotate_key​

This method attaches metadata to the specified key.

A special metadata name can be provided to name the key. If no name is provided, a default name is generated.

This method replaces the existing metadata by the specified ones. It does not update in place.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
publicKeystringThe Vega public key to use.
metadataarray-

Result: Success​

Result keyTypeDescriptionExample
metadataarray--

Examples​

Annotating the key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.annotate_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"metadata": [
{
"name": "portfolio",
"value": "btc"
}
]
}
}
Result​
{
"name": "Success",
"value": {
"metadata": [
{
"key": "portfolio",
"value": "btc"
},
{
"key": "name",
"value": "Key 1"
}
]
}
}

admin.isolate_key​

This method isolates a key in a specific wallet called an "isolated wallet". This isolated wallet contains a single key. It can't generate keys, and is stripped of the master key. Generally, it can only sign transactions.

This is a security feature that lowers the impact of having a wallet stolen. If a wallet is stolen and the attacker breaks into it, he has access to all keys. On an isolated wallet, it can only retrieve the isolated key.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
isolatedWalletPassphrasestring-
publicKeystringThe Vega public key to use.

Result: Success​

Result keyTypeDescriptionExample
walletundefinedName of the generated isolated walletName of the generated isolated wallet

Examples​

Isolating a key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.isolate_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"isolatedWalletPassphrase": "this-is-also-not-a-good-passphrase",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
}
}
Result​
{
"name": "Success",
"value": {
"wallet": "my-wallet.b5fd9d3c.isolated"
}
}

admin.rotate_key​

This method builds a transaction to rotate key on the network.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
fromPublicKeystringThe current public key
toPublicKeystringThe next public key to rotate to
chainIDstringThe chain identifier
submissionBlockHeightstringThe block height (approximation) at which the transaction will be submitted
enactmentBlockHeightstringThe block height at which the rotation should happen

Result: Success​

Result keyTypeDescriptionExample
masterPublicKeyundefinedThe master public key of the wallet used to sign the transactionThe master public key of the wallet used to sign the transaction
encodedTransactionundefinedThe base64-encoded key rotation transactionThe base64-encoded key rotation transaction

Examples​

Rotating a key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.rotate_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"fromPublicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0",
"toPublicKey": "988eae323a07f12363c17025c23ee58ea32ac3912398e16bb0b56969f57adc52",
"chainID": "test-chain-Thz9c6",
"submissionBlockHeight": 10,
"enactmentBlockHeight": 15
}
}
Result​
{
"name": "Success",
"value": {
"masterPublicKey": "9df682a3c87d90567f260566a9c223ccbbb7529c38340cf163b8fe199dbf0f2e",
"encodedTransaction": "CqsBdGVzdC1jaGFpbi1UaHo5YzYACPfdurmpppHlogEQCqp9iAEIAhAPGkA5ODhlYWUzMjNhMDdmMTIzNjNjMTcwMjVjMjNlZTU4ZWEzMmFjMzkxMjM5OGUxNmJiMGI1Njk2OWY1N2FkYzUyIkA4MWFhZjk2NmU4ZjUxNDIzZjBiZDFkOTMzYWQ0NmY5NjJlMjNiY2Q3MTg4ZWQzZmUwZjUzZjRkYThhMzJhOWVlEpMBCoABYzg3NDVkODhlMWQ1YTBhOGE3NGI5YzRmN2QyMzQ3ZmQ5ZDY1NzIwYTQ3ZmYwNWU3YTZmZmYyOTA0NzhmOTU0M2NjM2E4MzJkNjBmYTJiNmY3ZTQ3YWJlMjE0MGIwOTEyNzBlNTAxZTA5MjVjNDg3NzEwMjViOTkyYTg1ZTAxMDQSDHZlZ2EvZWQyNTUxORgBgH0D0j5AOWRmNjgyYTNjODdkOTA1NjdmMjYwNTY2YTljMjIzY2NiYmI3NTI5YzM4MzQwY2YxNjNiOGZlMTk5ZGJmMGYyZQ=="
}
}

admin.taint_key​

This method marks the specified public key as tainted. It makes it unusable for transaction signing.

When a key is tainted, it is automatically removed from the allowed keys if specified. If the key is the only one to be set, the permission to access the public keys is revoked. If no allowed key is specified, but all keys in the wallet are tainted, the permission of the public keys is revoked as well.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
publicKeystringThe Vega public key to use.

Result: Success​

Examples​

Tainting a key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.taint_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.untaint_key​

This method removes the taint from the specified public key.

If you tainted a key for security reasons, you should not use it.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
publicKeystringThe Vega public key to use.

Result: Success​

Examples​

Remove the taint from a key​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.untaint_key",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.describe_permissions​

This method returns the permissions set for the specified wallet and hostname.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
hostnamestring-

Result: Success​

Result keyTypeDescriptionExample
permissionsobjectThe full description of the permissions a third-party application has.The full description of the permissions a third-party application has.

Examples​

Describe the permissions​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.describe_permissions",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"hostname": "vega.xyz"
}
}
Result​
{
"name": "Success",
"value": {
"permissions": {
"publicKeys": {
"access": "read",
"allowedKeys": [
"b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
]
}
}
}
}

admin.list_permissions​

This method returns the permissions summary for all set hostnames.

For a detailed description of the permissions on a given hostname, see admin.describe_permissions

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-

Result: Success​

Result keyTypeDescriptionExample
permissionsobject--

Examples​

List the permissions​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.list_permissions",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase"
}
}
Result​
{
"name": "Success",
"value": {
"permissions": {
"vega.xyz": {
"public_keys": "read"
},
"token.vega.xyz": {
"public_keys": "none"
}
}
}
}

admin.update_permissions​

This method updates the permissions for the specified wallet and hostname.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
hostnamestring-
permissionsobjectThe full description of the permissions a third-party application has.

Result: Success​

Result keyTypeDescriptionExample
permissionsobjectThe full description of the permissions a third-party application has.The full description of the permissions a third-party application has.

Examples​

Update the permissions​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.update_permissions",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"hostname": "vega.xyz",
"permissions": {
"publicKeys": {
"access": "read",
"allowedKeys": [
"b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
]
}
}
}
}
Result​
{
"name": "Success",
"value": {
"permissions": {
"publicKeys": {
"access": "read",
"allowedKeys": [
"b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0"
]
}
}
}
}

admin.revoke_permissions​

This method revokes the permissions set in the specified hostname.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
hostnamestring-

Result: Success​

Examples​

Revoke the permissions​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.revoke_permissions",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"hostname": "vega.xyz"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.purge_permissions​

This method purges all the permissions set for all hostname.

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-

Result: Success​

Examples​

Purge the permissions​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.purge_permissions",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.sign_transaction​

This method signs a transaction returning a base64-encoded transaction that can be sent using the method admin.send_transaction

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
pubKeystring-
chainIdstring-
blockHeightinteger-
network (Optional)integer-
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
encodedTransactionstring--

admin.sign_message​

This method signs any given message with a Vega public-key

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
pubKeystring-
encodedMessagestringThe message to sign encoded using base-64.

Result: Success​

Result keyTypeDescriptionExample
encodedSignaturestring--

Examples​

Sign a message​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.sign_message",
"params": {
"wallet": "my-wallet",
"passphrase": "this-is-not-a-good-passphrase",
"pubKey": "0101010101010101010101010101010101010101010101010101010101010101",
"encodedMessage": "U3VwZXIgc2VjcmV0IG1lc3NhZ2U="
}
}
Result​
{
"name": "Success",
"value": {
"encodedSignature": "6a2Ud6yuNcnOaO8jaiTJJi8dZBQzvNySV2Tt2hD+YhVnz1dNxHGUavU2a1W1z0/1uX0n91x2jWXONMRpiiNODg=="
}
}

admin.verify_message​

This method verifies any given signature with a Vega public-key

Parameters​

Parameter nameTypeDescription
pubKeystring-
encodedMessagestringThe message use to create the signature, encoded using base-64.
encodedSignaturestringThe signature to verify, encoded using base-64.

Result: Success​

Result keyTypeDescriptionExample
isValidstring--

admin.send_transaction​

This method signs a transaction returning a base64-encoded transaction that can be sent using the method admin.send_transaction

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
pubKeystring-
network (Optional)integer-
nodeAddress (Optional)string-
retries (Optional)integer-
sendingModestringThe chosen mode to send the transaction:
- TYPE_SYNC returns the result of running the transaction.
- TYPE_ASYNC returns right away without waiting to hear if the transaction is even valid.
- TYPE_COMMIT waits until the transaction is committed in a block, or until some timeout is reached, or returns return right away if the transaction is not valid.
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
receivedAtstringThe date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
sentAtstringThe date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
transactionHashstringThe hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

admin.check_transaction​

This method checks a transaction is valid, and returns a base64-encoded transaction that can be sent using the method admin.send_transaction

Parameters​

Parameter nameTypeDescription
walletstring-
passphrasestring-
pubKeystring-
network (Optional)integer-
nodeAddress (Optional)string-
retries (Optional)integer-
transactionobjectThe transaction as a JSON object

Result: Success​

Result keyTypeDescriptionExample
receivedAtstringThe date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
sentAtstringThe date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

admin.send_raw_transaction​

This method sends a transaction that was signed using admin.sign_transaction into a network

Parameters​

Parameter nameTypeDescription
encodedTransactionstringThe signed transaction to be sent, encoded using base-64.
networkstringThe network to send the transaction to.
nodeAddressstringThe node address to send the transaction to.
retriesintegerthe number of times sending the transaction should be attempted if it fails
sendingModestringThe chosen mode to send the transaction:
- TYPE_SYNC returns the result of running the transaction.
- TYPE_ASYNC returns right away without waiting to hear if the transaction is even valid.
- TYPE_COMMIT waits until the transaction is committed in a block, or until some timeout is reached, or returns return right away if the transaction is not valid.

Result: Success​

Result keyTypeDescriptionExample
receivedAtstringThe date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the API received the request to send the transaction.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
sentAtstringThe date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
The date when the transaction has been sent to the network.

The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
transactionHashstringThe hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it.
transactionobjectA transaction that has been signed by the wallet.A transaction that has been signed by the wallet.

admin.start_service​

This method starts a wallet service targeting the specified network.

Parameters​

Parameter nameTypeDescription
networkstring-
noVersionCheckboolean-

Result: Success​

Examples​

Start the service​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.start_service",
"params": {
"network": "fairground",
"noVersionCheck": false
}
}
Result​
{
"name": "Success",
"value": null
}

admin.stop_service​

This method stops the wallet service targeting the specified network. This automatically disconnects all the wallets used in the service.

It does not fail if there is no service running for this network.

Parameters​

Parameter nameTypeDescription
networkstring-

Result: Success​

Examples​

Stop a running service​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.stop_service",
"params": {
"network": "fairground"
}
}
Result​
{
"name": "Success",
"value": null
}

Stop a non-running service​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.stop_service",
"params": {
"network": "network-without-running-service"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.list_connections​

This method lists all the connections of a service.

Parameters​

None required

Result: Success​

Result keyTypeDescriptionExample
activeConnectionsarrayThe list is sorted by hostname, then by wallet name.The list is sorted by hostname, then by wallet name.

Examples​

List the connection of a service​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.list_connections",
"params": []
}
Result​
{
"name": "Success",
"value": {
"activeConnections": [
{
"hostname": "example.com",
"wallet": "my-btc-wallet"
},
{
"hostname": "vega.xyz",
"wallet": "my-btc-wallet"
},
{
"hostname": "vega.xyz",
"wallet": "my-eth-wallet"
}
]
}
}

admin.close_connection​

This method closes the connection between a third-party application and a wallet opened in the service that run against the specified network.

Parameters​

Parameter nameTypeDescription
hostnamestring-
walletstring-

Result: Success​

Examples​

Close a connection​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.close_connection",
"params": {
"hostname": "vega.xyz",
"wallet": "my-btc-wallet"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.close_connections_to_hostname​

This method closes all the connections from the specified hostname to any wallet opened in the service that run against the specified network.

Parameters​

Parameter nameTypeDescription
hostnamestring-

Result: Success​

Examples​

Close all connections to a given hostname​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.close_connections_to_hostname",
"params": {
"hostname": "vega.xyz"
}
}
Result​
{
"name": "Success",
"value": null
}

admin.close_connections_to_wallet​

This method closes all the connections from any hostname to the specified wallet opened in the service that run against the specified network.

Parameters​

Parameter nameTypeDescription
walletstring-

Result: Success​

Examples​

Close all connections to a given wallet​

undefined

Parameters​
{
"id": 1,
"jsonrpc": "2.0",
"method": "admin.close_connections_to_wallet",
"params": {
"wallet": "my-btc-wallet"
}
}
Result​
{
"name": "Success",
"value": null
}