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.
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
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
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}
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite
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
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
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
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
remove_txs¶
Removes transactions in the ‘Signed’ state.
Deleting transactions in the ‘Dispatched’, ‘Cleared’, ‘Settled’ states could cause issues 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/remove
Request Body Payload
{
"txids": [<txid1>, <txid2>, ...] (optional field)
}
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/remove
Sample Body Payload
{
"txids": ["d45145f0c2ff87f6cfe5524d46d5ba14932363e927bd5a4af899a9b8fc0ab76f"]
}
Sample Response
{
"value": {
"message": "All StateSigned transactions in set: ['299405452db66866b9fed2ebe83bee5d41c4a29a0d88e2f8590f1ced7f5531b1'] deleted fromTxCache, TxInputs and TxOutputs cache and SqliteDatabase."
}
}
get_transaction_history¶
Get transaction history.
- 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 Response
{
"value": [
{
"txid": "d45145f0c2ff87f6cfe5524d46d5ba14932363e927bd5a4af899a9b8fc0ab76f",
"height": 201,
"timestamp": "2020-09-30T21:02:32",
"value": "+25.",
"balance": "25.",
"label": "",
"fiat_value": "No data",
"fiat_balance": "No data"
}
]
}
get_transactions_metadata¶
Get transaction metadata.
- Method
POST
- Content-Type
application/json
- Endpoint
http://127.0.0.1:9999/v1/{network}/dapp/wallets/{wallet_name}/{account_id}/txs/metadata
- Regtest example
http://127.0.0.1:9999/v1/regtest/dapp/wallets/worker1.sqlite/1/txs/metadata
Sample Request Payload
{
"txids": ["d45145f0c2ff87f6cfe5524d46d5ba14932363e927bd5a4af899a9b8fc0ab76f"]
}
Sample Response
{
"value": {
"d45145f0c2ff87f6cfe5524d46d5ba14932363e927bd5a4af899a9b8fc0ab76f": {
"block_id": "7a24a95c4bfec88785203dc2e36dcf4493469d4d8cadfd4e89b37f7eae9e77bd",
"height": 201,
"conf": 1,
"timestamp": 1601452952
}
}
}
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
{
"value": {
"tx_hex": "0200000001adc7943687d0f89c1e20bb1c196e16cd5f08449e5aa7e744c83cc5f67ffe1e6d000000006a47304402204a23d0a3b4f3806c741966748ab0433409e9a75eeb8203d9ddb5a4209b224a0c022034b4e134aabf77f54a37175f4e391f9ab2c08540d7dfef2cb7189e0526fb6235412102f1120ab677437a561b9c2c05584d974aedf01d6038c3edfe3a3af9742113a91cfeffffff0200f90295000000001976a914b3de43912c075239c5bba3e1061baa021d238e4d88ac1ef80295000000001976a91444afd14a53a354048320c19ccfb1833263b3bd0188acc8000000"
}
}
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” encoded in Hex (“48656c6c6f”) the preceeding 0x05 byte represents a pushdata op code to push the next 5 bytes onto the stack (in this case “48656c6c6f”).
Additional outputs for leftover change will be created automatically.
{
"outputs": [
{"script_pubkey":"006a0548656c6c6f", "value": 0}
],
"password": "test"
}
Sample Response
{
"value": {
"tx_hex": "0200000001adc7943687d0f89c1e20bb1c196e16cd5f08449e5aa7e744c83cc5f67ffe1e6d000000006a47304402204a23d0a3b4f3806c741966748ab0433409e9a75eeb8203d9ddb5a4209b224a0c022034b4e134aabf77f54a37175f4e391f9ab2c08540d7dfef2cb7189e0526fb6235412102f1120ab677437a561b9c2c05584d974aedf01d6038c3edfe3a3af9742113a91cfeffffff0200f90295000000001976a914b3de43912c075239c5bba3e1061baa021d238e4d88ac1ef80295000000001976a91444afd14a53a354048320c19ccfb1833263b3bd0188acc8000000"
}
}
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” encoded in Hex (“48656c6c6f”) the preceeding 0x05 byte represents a pushdata op code to push the next 5 bytes onto the stack (in this case “48656c6c6f”).
Additional outputs for leftover change will be created automatically.
{
"rawtx": "0100000001b131557fed1c0f59f8e2880d9aa2c4415dee3be8ebd2feb96668b62d45059429010000006b48304502210087d8ef3f390e563499598501759695a519a5b405f36704f8c9506089b1d5de32022072477b3f96d1df1e4b32519f5606415928d67786b0193a87d372fb9bcf5ddc04412103e9ca43c3b2e885c8a420d5784bc3bbf26c0c3def9751a8fe7b4a4a9918c22d10ffffffff02000000000000000008006a0548656c6c6f60f70295000000001976a914b3de43912c075239c5bba3e1061baa021d238e4d88acc9000000"
}
Sample Response
{
"value": {
"txid": "53b1b2886f038183199f3dc6979c9c54934ebe74166e20addb0f318165d1b7ce"
}
}
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” encoded in Hex (“48656c6c6f”) the preceeding 0x05 byte represents a pushdata op code to push the next 5 bytes onto the stack (in this case “48656c6c6f”).
Additional outputs for leftover change will be created automatically.
{
"outputs": [
{"script_pubkey":"006a0548656c6c6f", "value": 0}
],
"password": "test"
}
Sample Response
{
"value": {
"txid": "7a77e888bb9a60f277cf3ae570c1fb61f99c13c9335170895efa07c6a923c91c"
}
}
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
{
"value": {
"txid": "7a77e888bb9a60f277cf3ae570c1fb61f99c13c9335170895efa07c6a923c91c"
}
}
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
{
"value": {
"txid": "cea035abf5b8c6814db2b3ab4240a7c8f65ea08d8b3a32a0bdb1d6c0605bb7e0"
}
}
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
{
"value": {
"txid": [
"410a6fd9024613d8e98953706b31f13ed875a7dfd9f2cee39b33ed2de0a15c92",
"262b113c711eb11e8a44b58aea8be36ba788b599a2089b425d0eb7f94d7d3913",
"12a972760942e24b53d74c18608a16aeef6df3d193a80e5f503d1457b1fb815a"
]
}
}
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
{
"value": {
"new_wallet": "G:\\electrumsv_official\\electrumsv1\\regtest\\wallets\\worker1.sqlite"
}
}