The REST API
Technically, the restapi is an example ‘dapp’ (daemon application). But is nevertheless provided in a format that aims to eventually cover the majority of basic use cases.
This RESTAPI may be subject to slight changes but the example dapp source code is there for users to modify
to suit your own specific needs. See examples/applications/README.rst
for instructions.
Wallet Creation (without using the GUI)
At this time, wallet creation via the REST API is only supported on the RegTest network. To create a wallet and account programmatically, shutdown the ElectrumSV daemon and run these commands on the command-line:
python3 electrum-sv create_wallet -w ~/.electrum-sv/wallets/mywallet.sqlite -wp test --no-password-check
python3 electrum-sv create_account -w ~/.electrum-sv/wallets/mywallet.sqlite -wp test --no-password-check
This will create a wallet called mywallet.sqlite
with a wallet password of test
and will add a standard BIP32
account which uses P2PKH output scripts for receiving payments.
Endpoints
get_all_wallets
Get a list of all available wallets
- Method
GET
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets
Sample Response
{
"wallets": [
"worker1.sqlite"
]
}
get_parent_wallet
Get a high-level information about the parent wallet and accounts (within the parent wallet).
- Method
GET
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite
Sample Response
{
"parent_wallet": "worker1.sqlite",
"accounts": {
"1": {
"wallet_type": "Standard account",
"default_script_type": "P2PKH",
"is_wallet_ready": true
}
}
}
load_wallet
Load the wallet on the daemon (i.e. subscribe to ElectrumX for active keys) and initiate synchronization. Returns a high-level information about the parent wallet and accounts.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/load_wallet
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/load_wallet
Sample Response
{
"parent_wallet": "worker1.sqlite",
"accounts": {
"1": {
"wallet_type": "Standard account",
"default_script_type": "P2PKH",
"is_wallet_ready": true
}
}
}
get_account
Get high-level information about a given account
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1
Sample Response
{
"1": {
"wallet_type": "Standard account",
"default_script_type": "P2PKH",
"is_wallet_ready": true
}
}
get_coin_state
Get the count of cleared, settled and matured coins.
- Method
GET
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/utxos/coin_state
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/utxos/coin_state
Sample Response
{
"cleared_coins": 11,
"settled_coins": 700,
"unmatured_coins": 0
}
get_utxos
Get a list of all utxos.
- Method
GET
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/utxos
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/utxos
Sample Response
{
"utxos": [
{
"value": 20000,
"script_pubkey": "76a91485324d225c81d414fe8a92bf101dba1a59211e8488ac",
"script_type": 2,
"tx_hash": "ce7c2fbc25d25d945b4ad539d2b41ead29e1b786a8aa42b2677af28da3f231a0",
"out_index": 49,
"keyinstance_id": 13,
"address": "msfERZdhGaabQmeQ1ks8sHYdCDtxnTfL2z",
"is_coinbase": false,
"flags": 0
},
{
"value": 20000,
"script_pubkey": "76a91488471d45666dadece7f06aca22f1a1cf9a3a534988ac",
"script_type": 2,
"tx_hash": "ce7c2fbc25d25d945b4ad539d2b41ead29e1b786a8aa42b2677af28da3f231a0",
"out_index": 50,
"keyinstance_id": 12,
"address": "mswXPFgWJbgvyxkWBFfYjbbaD1DZmFS3ig",
"is_coinbase": false,
"flags": 0
},
]
}
get_balance
Get account balance (confirmed, unconfirmed, unmatured) in satoshis.
- Method
GET
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/balance
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/utxos/balance
Sample Response
{
"confirmed_balance": 14999694400,
"unconfirmed_balance": 98000,
"unmatured_balance": 0
}
remove
Removes transactions (currently restricted to ‘StateSigned’ transactions.)
Deleting transactions in the ‘Dispatched’, ‘Cleared’, ‘Settled’ states could cause issues with the utxo set and so is not supported at this time (a DisabledFeatureError will be returned). If you require this feature, please make contact via the Atlantis Slack or the MetanetICU slack.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs
Sample Body Payload
{
"txids": [
"96eee07f8e2c96e33d457138496958d912042ff4ed7b3b9c74a2b810fa5c3750",
"469ddc27b8ef3b386bf7451aebce64edfe22d836ad51076c7a82d78f8b4f4cf9",
"e81472f9bbf2dc2c7dcc64c1f84b91b6214599d9c79e63be96dcda74dcb8103d"
]
}
Sample Response
{
"items": [
{
"id": "96eee07f8e2c96e33d457138496958d912042ff4ed7b3b9c74a2b810fa5c3750",
"result": 200
},
{
"id": "469ddc27b8ef3b386bf7451aebce64edfe22d836ad51076c7a82d78f8b4f4cf9",
"result": 400,
"description": "DisabledFeatureError: You used this endpoint in a way that is not supported for safety reasons. See documentation for details (https://electrumsv.readthedocs.io/ )"
},
{
"id": "e81472f9bbf2dc2c7dcc64c1f84b91b6214599d9c79e63be96dcda74dcb8103d",
"result": 400,
"description": "Transaction not found"
}
]
}
get_transaction_history
Get transaction history. tx_flags
can be specified in the request body. This is an enum representing
a bitmask for filtering transactions.
The main `TxFlags` are:
- StateCleared
1 << 20 (received over p2p network and is unconfirmed and in the mempool)
- StateSettled
1 << 21 (received over the p2p network and is confirmed in a block)
- StateReceived
1 << 22 (received from another party and is unknown to the p2p network)
- StateSigned
1 << 23 (not sent or given to anyone else, but are with-holding and consider the inputs it uses allocated)
- StateDispatched
1 << 24 (a transaction you have given to someone else, and are considering the inputs it uses allocated)
However, there are other flags that can be set. See electrumsv/constants.py:TxFlags
for details.
In the example below, (1 << 23 | 1 << 21) yields 9437184 (to filter for only StateSigned and StateCleared transactions)
An empty request body will return all transaction history for this account. Pagination is not yet implemented.
Request
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/history
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/history
Sample Body Payload
{
"tx_flags": 9437184
}
Sample Response
{
"history": [
{
"txid": "64a9564588f9ebcce4ac52f4e0c8fe758b16dfd6fdb5bd8db5920da317aa15c8",
"height": 0,
"tx_flags": 1052720,
"value": -10200
},
{
"txid": "a6ec24243a79de1b51646d1a46ece854a8f682ff23b4d4afabaebc2bc10ef110",
"height": 0,
"tx_flags": 1052720,
"value": -10200
}
]
}
fetch_transaction
Get the raw transaction for a given hex txid (as a hex string) - must be a transaction in the wallet’s history.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/fetch
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/fetch
Sample Request Payload
{
"txid": "d45145f0c2ff87f6cfe5524d46d5ba14932363e927bd5a4af899a9b8fc0ab76f"
}
Sample Response
{
"tx_hex": "0100000001e59dd2992ed46911bea87af1b4f7ab1edce8e038520f142d2aa219492664d993160000006b483045022100ec97e4887b5dd9bb3c1e0ebd0d5b2b3520aeda4d957de4bf0e06a920c7dd3fe802200be4c58192a7c67930518bf29b30ab49883fcc342ca4ee5815288c6f17d7b486412103ab06ed1f70de1524e34a4e36575993a70ff2c8800958045137d0cc2caf67ec91ffffffff0248260000000000001976a9143ef1b7677ea1ed53400da9719380b4d0373a1b5f88ac10270000000000001976a91403d0de941da4f897a7cd3828b4905fa64190a72f88acce000000"
}
create_tx
Create a locally signed transaction ready for broadcast. A side effect of this is that the utxos associated with the transaction are allocated for use and so cannot be used in any other transaction.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/create
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/create
Sample Request Payload This example is of a single “OP_FALSE OP_RETURN” output with “Hello World” encoded in Hex. The preceeding 0x0b byte represents a pushdata op code to push the next 11 bytes onto the stack (“68656c6c6f20776f726c64”).
Additional outputs for leftover change will be created automatically.
{
"utxos": [
{
"value": 100,
"script_pubkey": "76a914884f1ca934bc8cca71aff46d04755422198376da88ac",
"script_type": 2,
"tx_hash": "098fab209ec4a31aa69a4e486fb9660d2aeba708bef0385c24ff9e4c8b19bd82",
"out_index": 0,
"keyinstance_id": 5,
"address": "1DRjftGzwgNQpujPAjX3LUcqDbgGbmDSw2",
"is_coinbase": false,
"flags": 0
}
],
"outputs": [
{"script_pubkey":"006a0b68656c6c6f20776f726c64", "value": 0}
],
"password": "test"
}
Sample Response
{
"txid": "96eee07f8e2c96e33d457138496958d912042ff4ed7b3b9c74a2b810fa5c3750",
"rawtx": "0100000001cfdec4ce0f10c4148b44163bf6205f53e5ab31f04a57fcaaeb33ef6487e08511000000006b483045022100873bb0dabc0b053be5602ebd1bb1ce143999221317eda8835fdf96a3197b168e022037ac7ad4c5f27beee3805e581b483b418a5298a3c467872d548accdc056321cb412103bf03fd106e69b55fc2041cc862a2c1932367899de4a734ef37b8a8f056792869ffffffff0200000000000000000e006a0b68656c6c6f20776f726c64dd250000000000001976a914c6d2e09ff211db5671ea1a9a08df13703b5a06f988acd5000000"
}
broadcast
Broadcast a rawtx (created with the previous endpoint).
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/broadcast
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/broadcast
Sample Request Payload This example is of a single “OP_FALSE OP_RETURN” output with “Hello World” encoded in Hex. The preceeding 0x0b byte represents a pushdata op code to push the next 11 bytes onto the stack (“68656c6c6f20776f726c64”).
Additional outputs for leftover change will be created automatically.
{
"rawtx": "0100000001ab9aff89a92c011b5436a0c02eb53cf6328286e5cf5767f309cde5414f657661000000006a473044022050750ec47afa183d3c99e22bc4324c3af83115fb409f966e345f72e0bcfa780302201e5d5920e0164c26f2fee2a71b079a4c4918ec9b269df624f3fb2fd483d6dedc4121038cac099086f38c1298d745f3b67e14bc4ab29a21fab5514111c65e196d430b29ffffffff0200000000000000000e006a0b68656c6c6f20776f726c64dd250000000000001976a914ee8f1e9312200924a406e4c39a2d0685df60924988acce000000"
}
Sample Response
{
"txid": "7ff0fcf6de91ffa71ef145e31d0bffe31467ecaa125a8db307cf9066fea55db5"
}
create_and_broadcast
Atomically creates and broadcasts a transaction. If any errors occur, the intermediate step of creating a signed transaction will be reversed (i.e. the transaction will be deleted and the utxos freed for use).
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/create_and_broadcast
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/create_and_broadcast
Sample Request Payload This example is of a single “OP_FALSE OP_RETURN” output with “Hello World” encoded in Hex. The preceeding 0x0b byte represents a pushdata op code to push the next 11 bytes onto the stack (“68656c6c6f20776f726c64”).
Additional outputs for leftover change will be created automatically.
{
"outputs": [
{"script_pubkey":"006a0b68656c6c6f20776f726c64", "value": 0}
],
"password": "test"
}
Sample Response
{
"txid": "469ddc27b8ef3b386bf7451aebce64edfe22d836ad51076c7a82d78f8b4f4cf9"
}
split_utxos
Creates and broadcasts a coin-splitting transaction i.e. it breaks up existing utxos into a specified number of new utxos with the desired “split_value” (satoshis). “split_count” represents the maximum number of splitting outputs for the transaction. “desired_utxo_count” determines when the desired utxo count has been reached (i.e. if you have 200 utxos but “desired_utxo_count” is 220 then the next coin splitting transaction will create 20 more utxos.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/split_utxos
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/split_utxos
Sample Request Payload
{
"split_value": 10000,
"split_count": 100,
"password": "test",
"desired_utxo_count": 1000
}
Sample Response
{
"txid": "42329848db94cb16379b0c8898eb2b98542fb25d9257a47663c3fac7b0f49938"
}
Regtest only endpoints
If you try to access these endpoints when not in RegTest mode you will get back a 404 error because the endpoint will not be available.
topup_account
Tops up the RegTest wallet from the RegTest node wallet (new blocks may be generated to facilitate this process).
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/topup_account
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/topup_account
Sample Request Payload
{
"amount": 10
}
Sample Response
{
"txid": "8f3dfe9b9e84c1d0b6d6ead8700be4114bb2d3ca1f97e1e84c64ea944415c723"
}
generate_blocks
Tops up the RegTest wallet from the RegTest node wallet (new blocks may be generated to facilitate this process).
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/generate_blocks
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/generate_blocks
Sample Request Payload
{
"nblocks": 3
}
Sample Response
{
"txid": [
"72d1270d0b3ad4c71d8257db8d6f880186108152534658ae6a127b616795530d"
]
}
create_new_wallet
This will create a new wallet - in this example “worker1.sqlite”. This example was produced via the electrumsv-sdk which allows a convienient method for running a RegTest node, electrumX instance (pre-configured to connect) and an ElectrumSV instance with data-dir=G:\electrumsv_official\electrumsv1.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/create_new_wallet
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/create_new_wallet
Sample Request Payload
{
"password": "test"
}
Sample Response
{
"new_wallet": "G:\\electrumsv_official\\electrumsv1\\regtest\\wallets\\worker1.sqlite"
}