{ "openrpc": "1.2.6", "info": { "version": "1.0.0", "title": "Wallet API" }, "methods": [ { "name": "client.connect_wallet", "summary": "Initiates a connection between a wallet and a third-party application.", "description": "This method initiates a connection between a wallet and a third-party application.\n\nThe user has to review the request, and, if they accept it, select the wallet they want to use for this connection.\n\n**Supported connections:**\n- Multiple wallets connected for the same hostname.\n- A single wallet connected to multiple hostnames.\n- Combination of the above setups.\n\nHowever, 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.\n\nThis method should be the entry point of every third-party application.", "tags": [ { "name": "client" }, { "name": "connection" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "errors": [ { "$ref": "#/components/errors/user_error_connection_closed" }, { "$ref": "#/components/errors/application_error_request_cancelled" }, { "$ref": "#/components/errors/user_error_wallet_connection_rejected" }, { "$ref": "#/components/errors/user_error_request_cancelled" }, { "$ref": "#/components/errors/user_error_request_cancelled" } ], "examples": [ { "name": "Accepting a connection from \"vega.xyz\"", "description": "The third-party application \"vega.xyz\" requests a connection to a wallet and the user accepts.", "params": [], "result": { "name": "Success", "value": "null" } } ] }, { "name": "client.disconnect_wallet", "summary": "Ends the connection between the third-party application and the wallet.", "description": "This method ends the connection between the third-party application and the wallet.", "tags": [ { "name": "client" }, { "name": "connection" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Disconnection from \"vega.xyz\"", "description": "The third-party application \"vega.xyz\" requests a disconnection to a wallet.", "params": [], "result": { "name": "Success", "value": null } } ] }, { "name": "client.list_keys", "summary": "Returns the keys the user has allowed the third-party application to have access to.", "description": "This method returns the keys the user has allowed the third-party application to have access to.\n\nIt requires a `read` access on `public_keys`.", "tags": [ { "name": "client" }, { "name": "key" } ], "paramStructure": "by-name", "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/named_public_key" } } } } }, "examples": [ { "name": "List keys allowed on \"vega.xyz\"", "description": "The third-party application \"vega.xyz\" wants to list the public keys it has access to.", "params": [], "result": { "name": "Success", "value": { "keys": [ { "name": "Key 1", "publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" }, { "name": "Key 2", "publicKey": "988eae323a07f12363c17025c23ee58ea32ac3912398e16bb0b56969f57adc52" } ] } } } ] }, { "name": "client.sign_transaction", "summary": "Sign a transaction without sending it.", "description": "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.\n\nThe user has to review the transaction.", "tags": [ { "name": "client" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } }, { "name": "transaction", "required": true, "schema": { "$ref": "#/components/schemas/transaction" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "transaction" ], "properties": { "transaction": { "$ref": "#/components/schemas/signed_transaction" } } } }, "errors": [ { "$ref": "#/components/errors/network_error_no_healthy_node" }, { "$ref": "#/components/errors/network_error_could_not_get_chain_id" }, { "$ref": "#/components/errors/network_error_could_not_get_last_block" }, { "$ref": "#/components/errors/application_error_public_key_not_allowed" }, { "$ref": "#/components/errors/user_error_connection_closed" }, { "$ref": "#/components/errors/user_error_wallet_connection_rejected" }, { "$ref": "#/components/errors/user_error_request_cancelled" }, { "$ref": "#/components/errors/application_error_transaction_would_break_spam_rules" }, { "$ref": "#/components/errors/application_error_block_height_is_too_historic" }, { "$ref": "#/components/errors/application_error_transaction_per_block_limit_reached" } ], "examples": [ { "name": "Signing a transaction for \"vega.xyz\"", "description": "The third-party application \"vega.xyz\" requests to sign a transaction and the user accepts.", "params": [ { "name": "publicKey", "value": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80" }, { "name": "sendingMode", "value": "TYPE_SYNC" }, { "name": "transaction", "value": {} } ], "result": { "name": "Success", "value": { "receivedAt": "2021-02-18T21:54:42.123Z", "sentAt": "2021-02-18T21:54:42.123Z", "txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3" } } } ] }, { "name": "client.send_transaction", "summary": "Send a transaction to the network.", "description": "This method sends a transaction to the network.\n\nThe user has to review the transaction.", "tags": [ { "name": "client" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } }, { "name": "sendingMode", "required": true, "schema": { "$ref": "#/components/schemas/sending_mode" } }, { "name": "transaction", "required": true, "schema": { "$ref": "#/components/schemas/transaction" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "receivedAt", "sentAt", "transactionHash", "transaction" ], "properties": { "receivedAt": { "type": "string", "description": "The date when the API received the request to send the transaction.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "sentAt": { "type": "string", "description": "The date when the transaction has been sent to the network.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "transactionHash": { "type": "string", "description": "The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it." }, "transaction": { "$ref": "#/components/schemas/signed_transaction" } } } }, "errors": [ { "$ref": "#/components/errors/network_error_no_healthy_node" }, { "$ref": "#/components/errors/network_error_could_not_get_chain_id" }, { "$ref": "#/components/errors/network_error_could_not_get_last_block" }, { "$ref": "#/components/errors/network_error_failed_transaction" }, { "$ref": "#/components/errors/user_error_connection_closed" }, { "$ref": "#/components/errors/user_error_wallet_connection_rejected" }, { "$ref": "#/components/errors/user_error_request_cancelled" }, { "$ref": "#/components/errors/application_error_public_key_not_allowed" }, { "$ref": "#/components/errors/application_error_transaction_would_break_spam_rules" }, { "$ref": "#/components/errors/application_error_block_height_is_too_historic" }, { "$ref": "#/components/errors/application_error_transaction_per_block_limit_reached" } ], "examples": [ { "name": "Sending a transaction for \"vega.xyz\"", "description": "The third-party application \"vega.xyz\" requests to send a transaction and the user accepts.", "params": [ { "name": "publicKey", "value": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80" }, { "name": "sendingMode", "value": "TYPE_SYNC" }, { "name": "encodedTransaction", "value": "ewogICAgInZvdGVTdWJtaXNzaW9uIjogewogICAgICAgICJwcm9wb3NhbElkIjogImViMmQzOTAyZmRkYTljM2ViNmUzNjlmMjIzNTY4OWI4NzFjNzMyMmNmM2FiMjg0ZGRlM2U5ZGZjMTM4NjNhMTciLAogICAgICAgICJ2YWx1ZSI6ICJWQUxVRV9ZRVMiCiAgICB9Cn0K" } ], "result": { "name": "Success", "value": { "receivedAt": "2021-02-18T21:54:42.123Z", "sentAt": "2021-02-18T21:54:42.123Z", "txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3" } } } ] }, { "name": "client.check_transaction", "summary": "Check a transaction or a bundle of transactions and send them to the network.", "description": "This method sends a transaction or a bundle of transactions to the network to verify their validity.\n\nThe network does not add them to a block. What happens with the transaction is up to the third-party application.\n\nThe user has to review the transaction after this step.", "tags": [ { "name": "client" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } }, { "name": "transaction", "required": true, "schema": { "$ref": "#/components/schemas/transaction" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "receivedAt", "sentAt", "transaction" ], "properties": { "receivedAt": { "type": "string", "description": "The date when the API received the request to send the transaction.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "sentAt": { "type": "string", "description": "The date when the transaction has been sent to the network.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "transaction": { "$ref": "#/components/schemas/signed_transaction" } } } }, "errors": [ { "$ref": "#/components/errors/network_error_no_healthy_node" }, { "$ref": "#/components/errors/network_error_could_not_get_chain_id" }, { "$ref": "#/components/errors/network_error_could_not_get_last_block" }, { "$ref": "#/components/errors/network_error_failed_transaction" }, { "$ref": "#/components/errors/user_error_connection_closed" }, { "$ref": "#/components/errors/user_error_wallet_connection_rejected" }, { "$ref": "#/components/errors/user_error_request_cancelled" }, { "$ref": "#/components/errors/application_error_public_key_not_allowed" }, { "$ref": "#/components/errors/application_error_transaction_would_break_spam_rules" }, { "$ref": "#/components/errors/application_error_block_height_is_too_historic" }, { "$ref": "#/components/errors/application_error_transaction_per_block_limit_reached" } ], "examples": [ { "name": "Check a transaction for \"vega.xyz\"", "description": "", "params": [ { "name": "publicKey", "value": "3fd42fd5ceb22d99ac45086f1d82d516118a5cb7ad9a2e096cd78ca2c8960c80" }, { "name": "transaction", "value": {} } ], "result": { "name": "Success", "value": { "receivedAt": "2021-02-18T21:54:42.123Z", "sentAt": "2021-02-18T21:54:42.123Z", "txHash": "E8C167126D1FC8D92898AB9C07C318161DF68753A1316A69ABDC9ADC557723B3" } } } ] }, { "name": "client.get_chain_id", "summary": "Returns the chain ID of the network in use.", "description": "This method returns the chain ID of the network in use.\n\nIt should be called by every third-party application to know from which network it should fetch data.", "tags": [ { "name": "client" } ], "paramStructure": "by-name", "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "chainID" ], "properties": { "chainID": { "type": "string", "description": "The chain identifier", "examples": [ "test-chain-Thz9c6" ] } } } }, "errors": [ { "$ref": "#/components/errors/network_error_no_healthy_node" }, { "$ref": "#/components/errors/network_error_could_not_get_last_block" } ], "examples": [ { "name": "Fetching the chain ID", "description": "An example of requesting the chain's ID", "params": [], "result": { "name": "Success", "value": { "chainID": "test-chain-Thz9c6" } } } ] }, { "name": "admin.unlock_wallet", "summary": "Unlock the wallet to allow other methods to access it.", "description": "This method unlocks the specified wallet. This is a mandatory step to access and modify the wallet and its associated keys, permissions, etc.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "passphrase", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Unlocking a wallet", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "passphrase", "value": "this-is-not-a-good-passphrase" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.create_wallet", "summary": "Creates a wallet with its first key-pair.", "description": "This method creates a HD wallet (with version 2 of the key derivation) and generates its first key-pair the cryptographic algorithm ed25519.\n\nThe passphrase will be used to encrypt the wallet and its keys.\n\nIf successful, the wallet is ready to use for sending transaction.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "passphrase", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "wallet", "key" ], "properties": { "wallet": { "type": "object", "description": "the newly generated wallet", "required": [ "name", "keyDerivationVersion", "recoveryPhrase" ], "properties": { "name": { "type": "string" }, "keyDerivationVersion": { "type": "number" }, "recoveryPhrase": { "type": "string" } } }, "key": { "type": "object", "description": "the first public key generated", "required": [ "publicKey", "algorithm", "metadata" ], "properties": { "publicKey": { "$ref": "#/components/schemas/public_key" }, "algorithm": { "$ref": "#/components/schemas/algorithm" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } } } } }, "examples": [ { "name": "Creating a wallet", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "passphrase", "value": "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" } ] } } } } ] }, { "name": "admin.import_wallet", "summary": "Import a wallet with its first key-pair with a recovery phrase and a key derivation version.", "description": "This method imports a wallet using the specified recovery phrase and a key derivation version, and generates its first key-pair.\n\nThe passphrase will be used to encrypt the wallet and its keys.\n\nIf successful, the wallet is ready to use for sending transaction.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "passphrase", "required": true, "schema": { "type": "string" } }, { "name": "recoveryPhrase", "required": true, "schema": { "type": "string" } }, { "name": "keyDerivationVersion", "required": true, "schema": { "type": "number" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "wallet", "key" ], "properties": { "wallet": { "type": "object", "description": "the imported wallet", "required": [ "name", "keyDerivationVersion" ], "properties": { "name": { "type": "string" }, "keyDerivationVersion": { "type": "number" } } }, "key": { "type": "object", "description": "the first public key generated", "required": [ "publicKey", "algorithm", "metadata" ], "properties": { "publicKey": { "$ref": "#/components/schemas/public_key" }, "algorithm": { "$ref": "#/components/schemas/algorithm" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } } } } }, "examples": [ { "name": "Importing a wallet", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "passphrase", "value": "this-is-not-a-good-passphrase" }, { "name": "recoveryPhrase", "value": "swing ceiling chaos green put insane ripple desk match tip melt usual shrug turkey renew icon parade veteran lens govern path rough page render" }, { "name": "keyDerivationVersion", "value": "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" } ] } } } } ] }, { "name": "admin.update_passphrase", "summary": "Change the passphrase of the specified wallet.", "description": "This method changes the passphrase used to lock the wallet.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "newPassphrase", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Update the passphrase", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "newPassphrase", "value": "this-is-the-new-passphrase" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.describe_wallet", "summary": "Returns the wallet base information.", "description": "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.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "name", "keyDerivationVersion", "id", "type" ], "properties": { "name": { "type": "string" }, "keyDerivationVersion": { "type": "number" }, "id": { "type": "string" }, "type": { "type": "string" } } } }, "examples": [ { "name": "Getting wallet base information", "params": [ { "name": "wallet", "value": "my-wallet" } ], "result": { "name": "Success", "value": { "name": "my-wallet", "keyDerivationVersion": 2, "type": "HD Wallet", "id": "7ffa36b2fb99d8404e9448f0d2ce944055e64c36d895d1fde044c867bfdf779f" } } } ] }, { "name": "admin.list_wallets", "summary": "Returns the list of the wallets present on the computer.", "description": "This method returns the list of the wallets present on the computer. It is alphabetically sorted.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "wallets" ], "properties": { "wallets": { "type": "array", "items": { "type": "string" } } } } }, "examples": [ { "name": "Getting the list of wallets", "params": [], "result": { "name": "Success", "value": { "wallets": [ "wallet-1", "wallet-2" ] } } } ] }, { "name": "admin.rename_wallet", "summary": "Renames a wallet", "description": "This method renames a wallet in-place.\n\nIf the new name matches an existing wallet, it fails.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "newName", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Rename a wallet", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "newWallet", "value": "my-new-wallet-name" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.remove_wallet", "summary": "Removes a wallet from the computer.", "description": "This method removes a wallet from the computer.", "tags": [ { "name": "admin" }, { "name": "wallet" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Remove a wallet", "params": [ { "name": "wallet", "value": "my-wallet" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.list_networks", "summary": "Returns the list of all registered networks.", "description": "This method returns the list of the registered networks.", "tags": [ { "name": "admin" }, { "name": "network" } ], "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "networks" ], "properties": { "networks": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } } } } } }, "examples": [ { "name": "Getting the list of networks", "params": [], "result": { "name": "Success", "value": { "networks": [ { "name": "mainnet1", "metadata": [ { "key": "network", "value": "mainnet" } ] }, { "name": "fairground", "metadata": [ { "key": "network", "value": "testnet" } ] }, { "name": "local-network" } ] } } } ] }, { "name": "admin.describe_network", "summary": "Returns the network information.", "description": "This method returns the network information.", "tags": [ { "name": "admin" }, { "name": "network" } ], "paramStructure": "by-name", "params": [ { "name": "name", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "name", "api", "apps" ], "properties": { "name": { "type": "string" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } }, "api": { "$ref": "#/components/schemas/network_api_config" }, "apps": { "$ref": "#/components/schemas/network_apps_config" } } } }, "examples": [ { "name": "Describing a network", "params": [ { "name": "name", "value": "local-network" } ], "result": { "name": "Success", "value": { "name": "local-network", "metadata": [ { "key": "network", "value": "local" } ], "api": { "grpc": { "hosts": [ "localhost:3028" ] }, "graphQL": { "hosts": [ "localhost:3028" ] }, "rest": { "hosts": [ "localhost:3029" ] } }, "apps": { "console": "console.vega.xyz", "governance": "governance.vega.xyz", "explorer": "explorer.vega.xyz" } } } } ] }, { "name": "admin.update_network", "summary": "Update an existing network.", "description": "This method updates the network configuration.", "tags": [ { "name": "admin" }, { "name": "network" } ], "paramStructure": "by-name", "params": [ { "name": "name", "required": true, "schema": { "type": "string" } }, { "name": "metadata", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } }, { "name": "api", "required": true, "schema": { "$ref": "#/components/schemas/network_api_config" } }, { "name": "apps", "required": true, "schema": { "$ref": "#/components/schemas/network_apps_config" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Update a network", "params": [ { "name": "name", "value": "local-network" }, { "name": "api", "value": { "grpc": { "hosts": [ "localhost:3028" ] }, "graphQL": { "hosts": [ "localhost:3028" ] }, "rest": { "hosts": [ "localhost:3029" ] } } } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.rename_network", "summary": "Renames a network", "description": "This method renames a network in-place.\n\nIf the new name matches an existing network, it fails.", "tags": [ { "name": "admin" }, { "name": "network" } ], "paramStructure": "by-name", "params": [ { "name": "network", "required": true, "schema": { "type": "string" } }, { "name": "newName", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Rename a network", "params": [ { "name": "network", "value": "my-network" }, { "name": "newWallet", "value": "my-new-network-name" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.remove_network", "summary": "Removes a network from the computer.", "description": "This method removes a network from the computer.", "tags": [ { "name": "admin" }, { "name": "network" } ], "paramStructure": "by-name", "params": [ { "name": "name", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Remove a network", "params": [ { "name": "network", "value": "fairground" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.import_network", "summary": "Import a network configuration from a file or an URL.", "description": "Import a network configuration from a file or an URL.", "tags": [ { "name": "admin" }, { "name": "network" } ], "paramStructure": "by-name", "params": [ { "name": "name", "description": "The name to give to the imported network. If unset the network's name will be taken from the imported definition", "schema": { "type": "string" } }, { "name": "url", "description": "The URL of a network to import. The prefix `file://` can be used to indicate a file-path.", "required": true, "schema": { "type": "string" } }, { "name": "overwrite", "required": true, "schema": { "type": "boolean" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } }, "examples": [ { "name": "Importing a network", "params": [ { "name": "name", "value": "local-network" }, { "name": "url", "value": "file:///Users/username/local-network.toml" } ], "result": { "name": "Success", "value": { "name": "local-network" } } } ] }, { "name": "admin.generate_key", "summary": "Generates a key on the specified wallet.", "description": "This method generates a key on the specified wallet.\n\nMetadata can be attached to this key.\n\nA special metadata `name` can be provided to name the key. If no `name` is provided, a default name is generated.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "metadata", "required": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "publicKey", "algorithm", "metadata" ], "properties": { "publicKey": { "$ref": "#/components/schemas/public_key" }, "algorithm": { "$ref": "#/components/schemas/algorithm" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } } }, "examples": [ { "name": "Generating a key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "metadata", "value": [ { "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" } ] } } } ] }, { "name": "admin.describe_key", "summary": "Returns key's information.", "description": "This method returns the information of the specified key.\n\nIt 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.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "name", "publicKey", "algorithm", "metadata", "isTainted" ], "properties": { "name": { "type": "string" }, "publicKey": { "$ref": "#/components/schemas/public_key" }, "algorithm": { "$ref": "#/components/schemas/algorithm" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } }, "isTainted": { "type": "boolean", "description": "Tells if the key is tainted or not. A tainted key cannot be used for signing and sending transaction, for example." } } } }, "examples": [ { "name": "Getting key base information", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "publicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" } ], "result": { "name": "Success", "value": { "name": "Key 1", "publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0", "algorithm": { "name": "vega/ed25519", "version": 1 }, "metadata": [ { "key": "portfolio", "value": "btc" } ], "isTainted": false } } } ] }, { "name": "admin.list_keys", "summary": "Returns all generated key of the specified wallet.", "description": "This method returns all generated key of the specified wallet with their respective name.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/named_public_key" } } } } }, "examples": [ { "name": "Listing the keys", "params": [ { "name": "wallet", "value": "my-wallet" } ], "result": { "name": "Success", "value": { "keys": [ { "name": "Key 1", "publicKey": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" } ] } } } ] }, { "name": "admin.annotate_key", "summary": "Attaches metadata to a key.", "description": "This method attaches metadata to the specified key.\n\nA special metadata `name` can be provided to name the key. If no `name` is provided, a default name is generated.\n\nThis method **replaces** the existing metadata by the specified ones. It does **not** update in place.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } }, { "name": "metadata", "required": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "metadata" ], "properties": { "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } } } } }, "examples": [ { "name": "Annotating the key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "publicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" }, { "name": "metadata", "value": [ { "name": "portfolio", "value": "btc" } ] } ], "result": { "name": "Success", "value": { "metadata": [ { "key": "portfolio", "value": "btc" }, { "key": "name", "value": "Key 1" } ] } } } ] }, { "name": "admin.isolate_key", "summary": "Isolate a key to a specific wallet.", "description": "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.\n\nThis 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.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "isolatedWalletPassphrase", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "description": "Name of the generated isolated wallet", "type": "string" } } } }, "examples": [ { "name": "Isolating a key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "isolatedWalletPassphrase", "value": "this-is-also-not-a-good-passphrase" }, { "name": "publicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" } ], "result": { "name": "Success", "value": { "wallet": "my-wallet.b5fd9d3c.isolated" } } } ] }, { "name": "admin.rotate_key", "summary": "Builds a transaction to rotate key on the network.", "description": "This method builds a transaction to rotate key on the network.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "fromPublicKey", "required": true, "description": "The current public key", "schema": { "type": "string" } }, { "name": "toPublicKey", "required": true, "description": "The next public key to rotate to", "schema": { "type": "string" } }, { "name": "chainID", "required": true, "description": "The chain identifier", "schema": { "type": "string" } }, { "name": "submissionBlockHeight", "required": true, "description": "The block height (approximation) at which the transaction will be submitted", "schema": { "type": "number" } }, { "name": "enactmentBlockHeight", "required": true, "description": "The block height at which the rotation should happen", "schema": { "type": "number" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "masterPublicKey", "encodedTransaction" ], "properties": { "masterPublicKey": { "description": "The master public key of the wallet used to sign the transaction", "type": "string" }, "encodedTransaction": { "description": "The base64-encoded key rotation transaction", "type": "string" } } } }, "examples": [ { "name": "Rotating a key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "fromPublicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" }, { "name": "toPublicKey", "value": "988eae323a07f12363c17025c23ee58ea32ac3912398e16bb0b56969f57adc52" }, { "name": "chainID", "value": "test-chain-Thz9c6" }, { "name": "submissionBlockHeight", "value": 10 }, { "name": "enactmentBlockHeight", "value": 15 } ], "result": { "name": "Success", "value": { "masterPublicKey": "9df682a3c87d90567f260566a9c223ccbbb7529c38340cf163b8fe199dbf0f2e", "encodedTransaction": "CqsBdGVzdC1jaGFpbi1UaHo5YzYACPfdurmpppHlogEQCqp9iAEIAhAPGkA5ODhlYWUzMjNhMDdmMTIzNjNjMTcwMjVjMjNlZTU4ZWEzMmFjMzkxMjM5OGUxNmJiMGI1Njk2OWY1N2FkYzUyIkA4MWFhZjk2NmU4ZjUxNDIzZjBiZDFkOTMzYWQ0NmY5NjJlMjNiY2Q3MTg4ZWQzZmUwZjUzZjRkYThhMzJhOWVlEpMBCoABYzg3NDVkODhlMWQ1YTBhOGE3NGI5YzRmN2QyMzQ3ZmQ5ZDY1NzIwYTQ3ZmYwNWU3YTZmZmYyOTA0NzhmOTU0M2NjM2E4MzJkNjBmYTJiNmY3ZTQ3YWJlMjE0MGIwOTEyNzBlNTAxZTA5MjVjNDg3NzEwMjViOTkyYTg1ZTAxMDQSDHZlZ2EvZWQyNTUxORgBgH0D0j5AOWRmNjgyYTNjODdkOTA1NjdmMjYwNTY2YTljMjIzY2NiYmI3NTI5YzM4MzQwY2YxNjNiOGZlMTk5ZGJmMGYyZQ==" } } } ] }, { "name": "admin.taint_key", "summary": "Marks the specified public key as tainted.", "description": "This method marks the specified public key as tainted. It makes it unusable for transaction signing.\n\nWhen 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.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Tainting a key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "publicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.untaint_key", "summary": "Remove the taint from the specified public key.", "description": "This method removes the taint from the specified public key.\n\nIf you tainted a key for security reasons, you should not use it.", "tags": [ { "name": "admin" }, { "name": "key" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "$ref": "#/components/schemas/public_key" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Remove the taint from a key", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "publicKey", "value": "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.describe_permissions", "summary": "Returns the permissions set for the specified wallet and hostname.", "description": "This method returns the permissions set for the specified wallet and hostname.", "tags": [ { "name": "admin" }, { "name": "permissions" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "hostname", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "$ref": "#/components/schemas/permissions" } } } }, "examples": [ { "name": "Describe the permissions", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "hostname", "value": "vega.xyz" } ], "result": { "name": "Success", "value": { "permissions": { "publicKeys": { "access": "read", "allowedKeys": [ "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" ] } } } } } ] }, { "name": "admin.list_permissions", "summary": "Returns the permissions summary for all set hostnames.", "description": "This method returns the permissions summary for all set hostnames.\n\nFor a detailed description of the permissions on a given hostname, see `admin.describe_permissions`", "tags": [ { "name": "admin" }, { "name": "permissions" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "type": "object", "patternProperties": { ".": { "schema": { "$ref": "#/components/schemas/permissions_summary" } } } } } } }, "examples": [ { "name": "List the permissions", "params": [ { "name": "wallet", "value": "my-wallet" } ], "result": { "name": "Success", "value": { "permissions": { "vega.xyz": { "public_keys": "read" }, "token.vega.xyz": { "public_keys": "none" } } } } } ] }, { "name": "admin.update_permissions", "summary": "Updates the permissions for the specified wallet and hostname.", "description": "This method updates the permissions for the specified wallet and hostname.", "tags": [ { "name": "admin" }, { "name": "permissions" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "hostname", "required": true, "schema": { "type": "string" } }, { "name": "permissions", "required": true, "schema": { "$ref": "#/components/schemas/permissions" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "$ref": "#/components/schemas/permissions" } } } }, "examples": [ { "name": "Update the permissions", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "hostname", "value": "vega.xyz" }, { "name": "permissions", "value": { "publicKeys": { "access": "read", "allowedKeys": [ "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" ] } } } ], "result": { "name": "Success", "value": { "permissions": { "publicKeys": { "access": "read", "allowedKeys": [ "b5fd9d3c4ad553cb3196303b6e6df7f484cf7f5331a572a45031239fd71ad8a0" ] } } } } } ] }, { "name": "admin.revoke_permissions", "summary": "Revokes the permissions set in the specified hostname.", "description": "This method revokes the permissions set in the specified hostname.", "tags": [ { "name": "admin" }, { "name": "permissions" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "hostname", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Revoke the permissions", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "hostname", "value": "vega.xyz" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.purge_permissions", "summary": "Purges all the permissions set for all hostname.", "description": "This method purges all the permissions set for all hostname.", "tags": [ { "name": "admin" }, { "name": "permissions" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Purge the permissions", "params": [ { "name": "wallet", "value": "my-wallet" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.sign_transaction", "summary": "Sign a command using the specified wallet and public key.", "description": "This method signs a transaction returning a base64-encoded transaction that can be sent using the method `admin.send_transaction`", "tags": [ { "name": "admin" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "description": "The wallet from which the signing key comes from.", "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "description": "The public key associated to the private key that is used to sign the transaction.", "schema": { "type": "string" } }, { "name": "network", "description": "The network configuration to use to retrieve the last block data. If specified, the last block data will be fetched by one of the nodes specified in this network configuration. Not required if the last block data is specified, as no network query will be issued.", "schema": { "type": "string" } }, { "name": "transaction", "description": "The transaction to sign.", "required": true, "schema": { "$ref": "#/components/schemas/transaction" } }, { "name": "lastBlockData", "description": "Instead of fetching the last block data from a network, it possible to manually specify it. If specified, then the parameters `network`, `retries` and `maximumRequestDuration` do not have to be specified.", "schema": { "$ref": "#/components/schemas/last_block_data" } }, { "name": "retries", "description": "The number of times the software should retry sending the requests to the node if there is a communication failure. Not required if the last block data is specified, as no network query will be issued.", "schema": { "type": "number" } }, { "name": "maximumRequestDuration", "description": "The maximum duration the software waits for the node to respond. If the node does not respond in time, the software cancels the request. Not required if the last block data is specified, as no network query will be issued.", "schema": { "$ref": "#/components/schemas/duration" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "transaction", "encodedTransaction" ], "properties": { "transaction": { "$ref": "#/components/schemas/signed_transaction" }, "encodedTransaction": { "type": "string" } } } } }, { "name": "admin.sign_message", "summary": "Sign any arbitrary message", "description": "This method signs any given message with a Vega public-key", "tags": [ { "name": "admin" }, { "name": "message" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "required": true, "schema": { "type": "string" } }, { "name": "encodedMessage", "description": "The message to sign encoded using base-64.", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "encodedSignature" ], "properties": { "encodedSignature": { "type": "string" } } } }, "examples": [ { "name": "Sign a message", "params": [ { "name": "wallet", "value": "my-wallet" }, { "name": "publicKey", "value": "0101010101010101010101010101010101010101010101010101010101010101" }, { "name": "encodedMessage", "value": "U3VwZXIgc2VjcmV0IG1lc3NhZ2U=" } ], "result": { "name": "Success", "value": { "encodedSignature": "6a2Ud6yuNcnOaO8jaiTJJi8dZBQzvNySV2Tt2hD+YhVnz1dNxHGUavU2a1W1z0/1uX0n91x2jWXONMRpiiNODg==" } } } ] }, { "name": "admin.verify_message", "summary": "Verify any arbitrary signature", "description": "This method verifies any given signature with a Vega public-key", "tags": [ { "name": "admin" }, { "name": "message" } ], "paramStructure": "by-name", "params": [ { "name": "publicKey", "required": true, "schema": { "type": "string" } }, { "name": "encodedMessage", "description": "The message use to create the signature, encoded using base-64.", "required": true, "schema": { "type": "string" } }, { "name": "encodedSignature", "description": "The signature to verify, encoded using base-64.", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "isValid" ], "properties": { "isValid": { "type": "boolean" } } } } }, { "name": "admin.send_transaction", "summary": "Sign & send a transaction to a network", "description": "This method signs a transaction returning a base64-encoded transaction that can be sent using the method `admin.send_transaction`", "tags": [ { "name": "admin" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "description": "The wallet from which the signing key comes from.", "schema": { "type": "string" } }, { "name": "publicKey", "description": "The public key associated to the private key that is used to sign the transaction.", "required": true, "schema": { "type": "string" } }, { "name": "network", "description": "The network configuration used to connect the network and send the transaction to. It should not be specified if the parameter `nodeAddress` is specified.", "schema": { "type": "string" } }, { "name": "nodeAddress", "description": "he specific node address used to connect to the network and send the transaction. It should not be specified if the parameter `network` is specified.", "schema": { "type": "string" } }, { "name": "retries", "description": "The number of times the software should retry sending the requests to the node if there is a communication failure.", "schema": { "type": "number" } }, { "name": "maximumRequestDuration", "description": "The maximum duration the software waits for the node to respond. If the node does not respond in time, the software cancels the request.", "schema": { "$ref": "#/components/schemas/duration" } }, { "name": "sendingMode", "required": true, "description": "The mode used to send the transaction to the network.", "schema": { "$ref": "#/components/schemas/sending_mode" } }, { "name": "transaction", "required": true, "description": "The transaction to send.", "schema": { "$ref": "#/components/schemas/transaction" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "receivedAt", "sentAt", "transactionHash", "transaction", "node" ], "properties": { "receivedAt": { "type": "string", "description": "The date when the API received the request to send the transaction.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "sentAt": { "type": "string", "description": "The date when the transaction has been sent to the network.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "transactionHash": { "type": "string", "description": "The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it." }, "transaction": { "$ref": "#/components/schemas/signed_transaction" }, "node": { "$ref": "#/components/schemas/node_info" } } } } }, { "name": "admin.check_transaction", "summary": "Check transaction command using the specified wallet and public key.", "description": "This method checks a transaction is valid, and returns a base64-encoded transaction that can be sent using the method `admin.send_transaction`", "tags": [ { "name": "admin" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "description": "The wallet from which the signing key comes from.", "required": true, "schema": { "type": "string" } }, { "name": "publicKey", "description": "The public key associated to the private key that is used to sign the transaction.", "required": true, "schema": { "type": "string" } }, { "name": "network", "description": "The network configuration used to connect the network and check the transaction against. It should not be specified if the parameter `nodeAddress` is specified.", "schema": { "type": "string" } }, { "name": "nodeAddress", "description": "The specific node address used to connect the network and check the transaction against. It should not be specified if the parameter `network` is specified.", "schema": { "type": "string" } }, { "name": "retries", "description": "The number of times the software should retry sending the requests to the node if there is a communication failure.", "required": true, "schema": { "type": "number" } }, { "name": "maximumRequestDuration", "description": "The maximum duration the software waits for the node to respond. If the node does not respond in time, the software cancels the request.", "required": true, "schema": { "$ref": "#/components/schemas/duration" } }, { "name": "transaction", "description": "The transaction to check.", "required": true, "schema": { "$ref": "#/components/schemas/transaction" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "receivedAt", "sentAt", "encodedTransaction", "transaction", "node" ], "properties": { "receivedAt": { "type": "string", "description": "The date when the API received the request to send the transaction.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "sentAt": { "type": "string", "description": "The date when the transaction has been sent to the network.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "encodedTransaction": { "type": "string" }, "transaction": { "$ref": "#/components/schemas/signed_transaction" }, "node": { "$ref": "#/components/schemas/node_info" } } } } }, { "name": "admin.send_raw_transaction", "summary": "Send a signed transaction to a network", "description": "This method sends a transaction that was signed using admin.sign_transaction into a network", "tags": [ { "name": "admin" }, { "name": "transaction" } ], "paramStructure": "by-name", "params": [ { "name": "encodedTransaction", "description": "The signed transaction to be sent, encoded using base-64.", "required": true, "schema": { "type": "string" } }, { "name": "network", "description": "The network configuration used to connect the network and send the transaction to. It should not be specified if the parameter `nodeAddress` is specified.", "required": true, "schema": { "type": "string" } }, { "name": "nodeAddress", "description": "he specific node address used to connect to the network and send the transaction. It should not be specified if the parameter `network` is specified.", "required": true, "schema": { "type": "string" } }, { "name": "retries", "description": "The number of times the software should retry sending the requests to the node if there is a communication failure.", "required": true, "schema": { "type": "number" } }, { "name": "maximumRequestDuration", "description": "The maximum duration the software waits for the node to respond. If the node does not respond in time, the software cancels the request.", "required": true, "schema": { "$ref": "#/components/schemas/duration" } }, { "name": "sendingMode", "description": "The mode used to send the transaction to the network.", "required": true, "schema": { "$ref": "#/components/schemas/sending_mode" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "receivedAt", "sentAt", "transactionHash", "transaction", "node" ], "properties": { "receivedAt": { "type": "string", "description": "The date when the API received the request to send the transaction.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "sentAt": { "type": "string", "description": "The date when the transaction has been sent to the network.\n\nThe time is a quoted string in RFC 3339 format, with sub-second precision added if present.", "examples": [ "2021-02-18T21:54:42.123Z" ] }, "transactionHash": { "type": "string", "description": "The hash of the transaction. It's used to uniquely identify the transaction and can be used in the block explorer to retrieve it." }, "transaction": { "$ref": "#/components/schemas/signed_transaction" }, "node": { "$ref": "#/components/schemas/node_info" } } } } }, { "name": "admin.list_connections", "summary": "List all the connections of a service.", "description": "This method lists all the connections of a service.", "tags": [ { "name": "admin" }, { "name": "service" } ], "paramStructure": "by-name", "params": [], "result": { "name": "Success", "required": true, "schema": { "type": "object", "required": [ "activeConnections" ], "properties": { "activeConnections": { "type": "array", "description": "The list is sorted by hostname, then by wallet name.", "items": { "type": "object", "required": [ "hostname", "wallet" ], "properties": { "hostname": { "type": "string" }, "wallet": { "type": "string" } } } } } } }, "examples": [ { "name": "List the connection of a service", "params": [], "result": { "name": "Success", "value": { "activeConnections": [ { "hostname": "console.vega.xyz", "wallet": "my-btc-wallet" }, { "hostname": "vega.xyz", "wallet": "my-btc-wallet" }, { "hostname": "vega.xyz", "wallet": "my-eth-wallet" } ] } } } ] }, { "name": "admin.close_connection", "summary": "Close the connection between a third-party application and a wallet.", "description": "This method closes the connection between a third-party application and a wallet opened in the service that run against the specified network.", "tags": [ { "name": "admin" }, { "name": "service" } ], "paramStructure": "by-name", "params": [ { "name": "hostname", "required": true, "schema": { "type": "string" } }, { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Close a connection", "params": [ { "name": "hostname", "value": "vega.xyz" }, { "name": "wallet", "value": "my-btc-wallet" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.close_connections_to_hostname", "summary": "Close the connection from the specified third-party application to any wallet.", "description": "This method closes all the connections from the specified hostname to any wallet opened in the service that run against the specified network.", "tags": [ { "name": "admin" }, { "name": "service" } ], "paramStructure": "by-name", "params": [ { "name": "hostname", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Close all connections to a given hostname", "params": [ { "name": "hostname", "value": "vega.xyz" } ], "result": { "name": "Success", "value": null } } ] }, { "name": "admin.close_connections_to_wallet", "summary": "Close the connection from any third-party application to the specified wallet.", "description": "This method closes all the connections from any hostname to the specified wallet opened in the service that run against the specified network.", "tags": [ { "name": "admin" }, { "name": "service" } ], "paramStructure": "by-name", "params": [ { "name": "wallet", "required": true, "schema": { "type": "string" } } ], "result": { "name": "Success", "required": true, "schema": { "type": "null" } }, "examples": [ { "name": "Close all connections to a given wallet", "params": [ { "name": "wallet", "value": "my-btc-wallet" } ], "result": { "name": "Success", "value": null } } ] } ], "components": { "schemas": { "node_info": { "type": "object", "description": "The node that handled the transaction.", "required": [ "host" ], "properties": { "host": { "type": "string" } } }, "signed_transaction": { "type": "object", "description": "A transaction that has been signed by the wallet.", "required": [ "inputData", "signature", "from", "version", "pow" ], "properties": { "inputData": { "type": "string" }, "signature": { "type": "object", "required": [ "value", "algo", "version" ], "properties": { "value": { "type": "string" }, "algo": { "type": "string" }, "version": { "type": "number" } } }, "from": { "type": "object" }, "version": { "type": "number" }, "pow": { "type": "object", "required": [ "tid", "nonce" ], "properties": { "tid": { "type": "string" }, "nonce": { "type": "number" } } } } }, "public_key": { "type": "string", "description": "The Vega public key to use." }, "algorithm": { "type": "object", "description": "The algorithm used to generate the key.", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "number" } } }, "metadata": { "type": "object", "description": "The object metadata.", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "named_public_key": { "type": "object", "description": "The public key with its name.", "required": [ "name", "publicKey" ], "properties": { "name": { "type": "string" }, "publicKey": { "type": "string" } } }, "encoded_transaction": { "type": "string", "description": "The transaction encoded using base-64." }, "transaction": { "type": "object", "description": "The transaction as a JSON object" }, "access_mode": { "type": "string", "description": "The different access modes a permission can have.", "enum": [ "read", "none" ] }, "permissions_summary": { "type": "object", "description": "The description of the permissions a third-party application has.", "patternProperties": { ".": { "schema": { "type": "string" } } } }, "permissions": { "type": "object", "description": "The full description of the permissions a third-party application has.", "required": [ "publicKeys" ], "properties": { "publicKeys": { "type": "object", "description": "The permissions related to public keys.", "required": [ "access", "allowedKeys" ], "properties": { "access": { "$ref": "#/components/schemas/access_mode" }, "allowedKeys": { "type": "array", "description": "The subset of public keys the user selected for this hostname. If empty, the wallet assumes all keys are accessible.", "items": { "type": "string" } } } } } }, "network_api_config": { "type": "object", "description": "The API configuration for the network.", "required": [ "grpc" ], "properties": { "grpc": { "type": "object", "required": [ "hosts" ], "properties": { "hosts": { "type": "array", "items": { "type": "string" } } } }, "graphQL": { "type": "object", "required": [ "hosts" ], "properties": { "hosts": { "type": "array", "items": { "type": "string" } } } }, "rest": { "type": "object", "required": [ "hosts" ], "properties": { "hosts": { "type": "array", "items": { "type": "string" } } } } } }, "network_apps_config": { "type": "object", "description": "The URLs to the network applications.", "properties": { "console": { "type": "string" }, "governance": { "type": "string" }, "explorer": { "type": "string" } } }, "last_block_data": { "type": "object", "description": "The data related to the last block forged on the network.", "required": [ "blockHeight", "blockHash", "chainID", "proofOfWorkDifficulty", "proofOfWorkHashFunction" ], "properties": { "blockHeight": { "type": "number" }, "blockHash": { "type": "string" }, "chainID": { "type": "string" }, "proofOfWorkHashFunction": { "type": "string" }, "proofOfWorkDifficulty": { "type": "number" } } }, "sending_mode": { "type": "string", "description": "The chosen mode to send the transaction:\n- `TYPE_SYNC` returns the result of running the transaction.\n- `TYPE_ASYNC` returns right away without waiting to hear if the transaction is even valid.\n- `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.", "enum": [ "TYPE_SYNC", "TYPE_ASYNC", "TYPE_COMMIT" ] }, "duration": { "type": "number", "description": "As nanoseconds" } }, "errors": { "network_error_no_healthy_node": { "code": 1000, "message": "Network error", "data": "no healthy node available" }, "network_error_could_not_get_last_block": { "code": 1000, "message": "Network error", "data": "could not get information about the last block on the network" }, "network_error_could_not_get_chain_id": { "code": 1000, "message": "Network error", "data": "could not get the chain ID from the node" }, "network_error_transaction_failed": { "code": 1000, "message": "Network error", "data": "the transaction could not be sent through the selected node" }, "network_error_failed_transaction": { "code": 1001, "message": "Network error", "data": "the transaction failed" }, "network_error_invalid_transaction": { "code": 1051, "message": "Network error", "data": "the network rejected the transaction because it's invalid" }, "network_error_malformed_transaction": { "code": 1060, "message": "Network error", "data": "the network rejected the transaction because it's malformed" }, "network_error_unprocessable_transaction": { "code": 1070, "message": "Network error", "data": "the network could not process the transaction" }, "network_error_unsupported_transaction": { "code": 1080, "message": "Network error", "data": "the network does not support this transaction" }, "network_error_spam_protection_activated": { "code": 1089, "message": "Network error", "data": "the network blocked the transaction through the spam protection" }, "application_error_public_key_not_allowed": { "code": 2000, "message": "Application error", "data": "the public key is not allowed to be used" }, "application_error_transaction_would_break_spam_rules": { "code": 2000, "message": "Application error", "data": "the transaction will break the network's spam rules" }, "application_error_block_height_is_too_historic": { "code": 2000, "message": "Application error", "data": "the block height is too historic" }, "application_error_transaction_per_block_limit_reached": { "code": 2000, "message": "Application error", "data": "the transaction per block limit has been reached" }, "application_error_request_cancelled": { "code": 2001, "message": "Application error", "data": "the application cancelled the request" }, "user_error_connection_closed": { "code": 3000, "message": "User error", "data": "the user closed the connection" }, "user_error_wallet_connection_rejected": { "code": 3001, "message": "User error", "data": "the user rejected the wallet connection" }, "user_error_keys_access_rejected": { "code": 3001, "message": "User error", "data": "the user rejected the access to the keys" }, "user_error_sending_transaction_rejected": { "code": 3001, "message": "User error", "data": "the user rejected the sending of the transaction" }, "user_error_signing_transaction_rejected": { "code": 3001, "message": "User error", "data": "the user rejected the signing of the transaction" }, "user_error_request_cancelled": { "code": 3002, "message": "User error", "data": "the user cancelled the request" } } } }