From abd8de276a0b988117ea84b8712d3d67e32c8039 Mon Sep 17 00:00:00 2001 From: Bucko Date: Thu, 31 Aug 2017 11:29:17 -0700 Subject: [PATCH] update to api docs --- api-docs/index.html | 229 ++++++++++++++++++++++++++++---------------- 1 file changed, 146 insertions(+), 83 deletions(-) diff --git a/api-docs/index.html b/api-docs/index.html index fe1402e..7ad627e 100644 --- a/api-docs/index.html +++ b/api-docs/index.html @@ -564,7 +564,7 @@ Get Master HD Key
  • - Create New Wallet + Create A Wallet
  • Change Passphrase @@ -697,7 +697,7 @@

    Introduction

    Welcome to the Bcoin API!

    -

    The default bcoin HTTP server listens on the standard RPC port (8332 for main, 18333 for testnet, and 18555 default for simnet). It exposes a REST json api, as well as a JSON-RPC api.

    +

    The default bcoin HTTP server listens on the standard RPC port (8332 for main, 18332 for testnet, 48332 for regtest, and 18556 default for simnet). It exposes a REST json api, as well as a JSON-RPC api.

    Authentication

    Auth

    curl http://x:[api-key]@127.0.0.1:8332/
 
    export BCOIN_API_KEY=[api-key]
 bcoin cli info
@@ -5315,7 +5315,7 @@ to lookup transactions by transaction hashes and addresses, respectively.
 
 
 
    Wallet Admin
    
-
    The _admin namespace exists to differentiate administrative level tasks on the wallet API that you probably don't want to expose to individual wallets. 
    
+
    The _admin namespace exists to differentiate administrative level tasks on the wallet API that you probably don't want to expose to individual wallets.
    
 
 
    /wallet/_admin/[TARGET_ACTION]
    
 
@@ -5347,8 +5347,7 @@ Replace `[TARGET_ACTION]` with one of the available actions listed below
 
    Example HTTP Request
    
 
    POST /wallet/_admin/rescan?height=50000
    
 
    Wallet Resend
    curl $url/wallet/_admin/resend \
--X POST 
---data "{}"
+-X POST
 
    bcoin cli resend
 
    const client = new bcoin.http.Client({
   network: 'testnet',
@@ -5366,15 +5365,12 @@ Replace `[TARGET_ACTION]` with one of the available actions listed below
 
    
 
    Rebroadcast all pending transactions in all wallets.
    
 
    HTTP Request
    
-
    POST /wallet/_admin/resend 
    
+
    POST /wallet/_admin/resend
    
 
    Wallet Backup
    let path;
 
    path='/path/to/new/backup'
-
    curl $url/wallet/_admin/backup?path=/home/user/walletdb-backup.ldb \ 
+
    curl $url/wallet/_admin/backup?path=/home/user/walletdb-backup.ldb \
   -X POST \
-``
-
-```shell--cli
-bcoin cli backup $path
+
    bcoin cli backup $path
 
    const client = new bcoin.http.Client({
     network: 'testnet',
 });
@@ -5391,7 +5387,7 @@ bcoin cli backup $path
 
    
 
    Safely backup the wallet database to specified path (creates a clone of the database).
    
 
    HTTP Request
    
-
    POST /wallet/_admin/backup?path=/home/user/walletdb-backup.ldb 
    
+
    POST /wallet/_admin/backup?path=/home/user/walletdb-backup.ldb
    
 
    List all Wallets
    curl $url/wallet/_admin/wallets
 
    bcoin cli wallets
 
    const client = new bcoin.http.Client({
@@ -5414,15 +5410,26 @@ bcoin cli backup $path
 
    
 
    List all wallet IDs. Returns an array of strings.
    
 
    HTTP Request
    
-
    GET /wallet/_admin/wallets  
    
-
    Wallet
    The WalletDB and Object
    
+
    GET /wallet/_admin/wallets
    
+
    Wallet
    The WalletDB and Object
    let id, url;
+
    id="primary"
+url="http://localhost:18332"
+
    curl $url/wallet/$id/
+
    bcoin cli wallet get --id=$id
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
+
+(async () => {
+  const wallet = await httpWallet.getInfo();
+  console.log(wallet);
+})();
+
    
 
    
 
    The wallet object will look something like this:
    
 
    
 
    {
   "network": "testnet",
   "wid": 1,
-  "id": "foo",
+  "id": "primary",
   "initialized": true,
   "watchOnly": false,
   "accountDepth": 1,
@@ -5458,7 +5465,7 @@ bcoin cli backup $path
   }
 }
 
    
-
    Bcoin maintains a wallet database which contains every wallet. Wallets are not usable without also using a wallet database. For testing, the wallet database can be in-memory, but it must be there.
    
+
    Bcoin maintains a wallet database which contains every wallet. Wallets are not usable without also using a wallet database. For testing, the wallet database can be in-memory, but it must be there. Wallets are uniquely identified by an id and the walletdb is created with a default id of primary. (See Create a Wallet below for more details.)
    
 
 
    Wallets in bcoin use bip44. They also originally supported bip45 for multisig, but support was removed to reduce code complexity, and also because bip45 doesn't seem to add any benefit in practice.
    
 
@@ -5567,8 +5574,8 @@ bcoin cli backup $path
 
 
    let token, id;
 
    token='977fbb8d212a1e78c7ce9dfda4ff3d7cc8bcd20c4ccf85d2c9c84bbef6c88b3c'
-id='primary'
-
    curl $url/wallet/$id/send \
+id='foo'
+
    curl $url/wallet/$id \
     -H 'Content-Type: application/json' \
     -d '{ "token": "$token" ... }'
 
    bcoin cli wallet get --network=testnet --token=$token
@@ -5622,21 +5629,24 @@ Note: if you happen to lose the returned token, you will not be able to access t
 
 
    HTTP Request
    
 
    POST /wallet/:id/retoken
    
-
    Get Wallet Info
    curl http://localhost:18332/wallet/test/
+
    Get Wallet Info
    let id;
+
    id='foo'
+
    curl $url/wallet/$id/
 
-
    bcoin cli wallet get --id=test --network=testnet
+
    # ID defaults to `primary` if none is passed
+bcoin cli wallet get --id=$id
 
    `use strict`
 
-const client = new bcoin.http.Client({  network: 'testnet' });
+const httpWallet = new bcoin.http.Wallet({ id: id });
 const id = 'foo';
 
 (async () => {
-  const wallet = await client.getWallet(id);
+  const wallet = await httpWallet.getWalletInfo();
   console.log(wallet);
 })();
 
    
 
    
-
    Output is same as wallet object above
    
+
    Sample output
    
 
    
 
    {
   "network": "testnet",
@@ -5677,7 +5687,7 @@ Note: if you happen to lose the returned token, you will not be able to access t
   }
 }
 
    
-
    Get wallet info by ID.
    
+
    Get wallet info by ID. If no id is passed in the CLI it assumes an id of primary.
    
 
    HTTP Request
    
 
    GET /wallet/:id
    
 
@@ -5736,7 +5746,7 @@ Note: if you happen to lose the returned token, you will not be able to access t
 named id of the wallet whose info you would like to retrieve
 
 
-
    Create New Wallet
    let id, witness;
+
    Create A Wallet
    let id, witness;
 
    id = 'foo'
 witness = false
 
    curl $url/wallet/$id \
@@ -5818,14 +5828,14 @@ See Wallet Options for full list and description o
 
    id='foo'
 oldPass = 'oldpass123'
 newPass='newpass123'
-
    > No command available
+
    > No cli command available
 
    curl $url/wallet/$id/passphrase \
   -X POST
   --data '{"old":'$oldPass', "new":'$newPass'}'
-
    const client = new bcoin.http.CLient();
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
 
 (async () => {
-  const response = await client.setPassphrase(id, oldPass, newPass);
+  const response = await httpWallet.setPassphrase(oldPass, newPass);
   console.log(response);
 });
 
    
@@ -5849,7 +5859,7 @@ oldPass = 'oldpass123'
 Old passphrase. Pass in empty string if none
 
 
-passphrase 
     _string
+new 
     _string
 New passphrase
 
 
@@ -5981,10 +5991,10 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 
    curl $url/wallet/$id/import \
   -X POST \
   --data '{"account":"'$account'", "address":"'$address'"}'
-
    const wallet = new bcoin.http.Wallet({ id: id });
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
 
 (async () => {
-  const response = await wallet.importAddress(id, account, address)
+  const response = await httpWallet.importAddress(account, address)
 })();
 
    
 
    
@@ -6054,7 +6064,7 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 
    const httpWallet = new bcoin.http.Wallet({ id: id });
 
 (async () => {
-  const blockInfo = await httpWallet.getWalletBlock(height);
+  const blockInfo = await httpWallet.getBlock(height);
   console.log(blockInfo);
 })
 
    
@@ -6089,15 +6099,15 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 height of block being queried
 
 
-
    Add xpubkey (Multisig)
    let id, key;
+
    Add xpubkey (Multisig)
    let id, key, account;
 
    id="multi-foo"
-key=""
+key="tpubDCUQshhR98hjDDPtefuQdg4Dmpk5mes3TRyUp1Qa4BjxCVytfqmqNWmJ3tUZfqu4qLfEypQhNcpMF3yhZJ8h8hcahnxCzrqWmV5qVHHTqGM"
 
    bcoin cli wallet --id=$id shared add $key
 
    curl $url/wallet/$id/shared-key \
   -X PUT
   --data '{"accountKey": $key}'
 
    const httpWallet = new bcoin.http.wallet({ id: id });
-const account = 'default';
+account = 'default';
 
 (async () => {
   const response = await httpWallet.addSharedKey(account, key);
@@ -6112,6 +6122,10 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 }
 
    
 
    Add a shared xpubkey to wallet. Must be a multisig wallet.
    
+
+
 
    HTTP Request
    
 
    PUT /wallet/:id/shared-key
    
 
    Body Parameters
    
@@ -6125,10 +6139,14 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 accountKey 
     string
 xpubkey to add to the multisig wallet
 
+
+account 
     string
+multisig account to add the xpubkey to (default='default')
+
 
 
    Remove xpubkey (Multisig)
    let id, key;
 
    id="multi-foo"
-key=""
+key="tpubDCUQshhR98hjDDPtefuQdg4Dmpk5mes3TRyUp1Qa4BjxCVytfqmqNWmJ3tUZfqu4qLfEypQhNcpMF3yhZJ8h8hcahnxCzrqWmV5qVHHTqGM"
 
    bcoin cli wallet --id=$id shared remove $key
 
    curl $url/wallet/$id/shared-key \
   -X DELETE
@@ -6162,6 +6180,10 @@ Note that imported keys do not exist anywhere in the wallet's HD tree. They can
 accountKey 
     string
 xpubkey to add to the multisig wallet
 
+
+account 
     string
+multisig account to remove the key from (default='default')
+
 
 
    Get Public Key By Address
    let id, address;
 
    id="foo"
@@ -6354,7 +6376,9 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 
 
 
    POST /wallet/:id/nested
    
-
    Derive new nested p2sh receiving address for account.
    
+
    Derive new nested p2sh receiving address for account. Note that this can't be done on a non-witness account otherwise you will receive the following error:
    
+
+
    [error] (node) Cannot derive nested on non-witness account.
    
 
    HTTP Request
    
 
    POST /wallet/:id/nested
    
 
    GET /wallet/:id/balance
    
@@ -6413,21 +6437,23 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 
    Get wallet coins.
    
 
    HTTP Request
    
 
    GET /wallet/:id/coin/:hash/:index
    
-
    Wallet Transactions
    Send a transaction
    let id, rate, value, address;
-
    id='foo'
+
    Wallet Transactions
    Send a transaction
    let id, passphrase, rate, value, address;
+
    id="foo"
+passphrase="bar"
 rate=100
-value=.3
+value=3000
 address="moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA"
-
    bcoin cli wallet send --id=$id --value=$value --address=$address
+
    bcoin cli wallet send --id=$id --value=$value --address=$address ---passphrase=$passphrase
 
    curl $url/wallet/$id/send \
   -X POST \
   --data '{
+    "passphrase":"'$passphrase'",
     "rate":'$rate',
     "outputs":[
       {"address":"'$address'", "value":'$value'}
-    ] 
+    ]
   }'
-
    const httpWallet = bcoin.http.wallet({ id: id });
+
    const httpWallet = bcoin.http.Wallet({ id: id });
 const options = {
   rate: rate,
   outputs: [{ value: value, address; address }]
@@ -6439,7 +6465,7 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 })();
 
    
 
    
-
    Sample response: 
    
+
    Sample response:
    
 
    
 
    {
 {
@@ -6487,7 +6513,7 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 
    
 
    Create, sign, and send a transaction.
    
 
    HTTP Request
    
-
    POST /wallet/:id/send 
    
+
    POST /wallet/:id/send
    
 
    Post Paramaters
    
 
@@ -6525,40 +6551,44 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 
-
+
    
 
    
 
    
 value 
     int    		Value to send in bitcoin (as of beta-1.14)Value to send in satoshis
 
    
 
    
 address 
     string    		
 destination address for transaction
 
    
 
    
-
    Create a Transaction
    let id, rate, value, address;
-
    id='foo'
+
    Create a Transaction
    let id, rate, value, address, passphrase;
+
    id="foo"
+passphrase="bar"
 rate=100
 value=.3
 address="moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA"
-
    bcoin cli wallet mktx --id=$id --rate=$rate --value=$value --address=$address
+
    bcoin cli wallet mktx --id=$id --rate=$rate --value=$value --address=$address --passphrase=$passphrase
 
    curl $url/wallet/$id/create \
   -X POST \
   --data '{
-    "rate":'$rate',
+    "rate":"'$rate'",
+    "passphrase": "'$passphrase'"
     "outputs":[
       {"address":"'$address'", "value":'$value'}
-    ] 
+    ]
   }'
-
    const httpWallet = new bcoin.http.wallet({ id: id });
-const outputs: [{ value: value, address; address }]
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
+const outputs = [{ value: value, address: address }]
 const options = {
+  passphrase: passphrase,
+  outputs: outputs,
   rate: rate,
 };
 
 (async () => {
-  const tx = await httpWallet.createTX(options, outputs);
+  const tx = await httpWallet.createTX(options);
   console.log(tx);
 })();
 
    
 
    
-
    Sample response: 
    
+
    Sample response:
    
 
    
 
    {
   "hash": "0799a1d3ebfd108d2578a60e1b685350d42e1ef4d5cd326f99b8bf794c81ed17",
@@ -6605,7 +6635,7 @@ Note that, except for the CLI which assumes 'default' account, an account must b
 
    Create and template a transaction (useful for multisig).
 Do not broadcast or add to wallet.
    
 
    HTTP Request
    
-
    POST /wallet/:id/create 
    
+
    POST /wallet/:id/create
    
 
    Post Paramters
    
 
@@ -6650,7 +6680,7 @@ Do not broadcast or add to wallet.
    id="foo"
 passphrase="bar"
 tx="01000000010d72c6b2582c2b2e625d29dd5ad89209de7e2600ab12a1a8e05813c28b703d2c000000006b483045022100af93a8761ad22af858c5bc4e68b5991eac017dcddd933cf125553ec0b83eb8f30220373a4d8ee331ac4c3975718e2a789f873af0520ddbd2db18957cdf488ccd4ee301210215a9110e2a9b293c332c28d69f88081aa2a949fde67e35a13fbe19410994ffd9ffffffff0280969800000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac80c3c901000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac00000000"
-
    bcoin cli wallet sign --id=$id --passphrase=$passphrase --tx=$tx 
+
    bcoin cli wallet sign --id=$id --passphrase=$passphrase --tx=$tx
 
    curl $url/wallet/$id/sign \
   -X POST \
   --data '{"tx": "'$tx'", "passphrase":"'$passphrase'"}'
@@ -6708,7 +6738,7 @@ Do not broadcast or add to wallet.
    
 
    Sign a templated transaction (useful for multisig).
    HTTP Request
    
-
    POST /wallet/:id/sign 
    
+
    POST /wallet/:id/sign
    Post Paramters
    
 
    
 
 
 
 
 
    
@@ -6736,7 +6766,7 @@ Do not broadcast or add to wallet.
    
             "account": "'$account'",
             "age": "'$age'"
           }'
-
    const httpWallet = new bcoin.http.wallet({ id: id });
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
 
 (async () => {
   const response = httpWallet.zap(account, age);
@@ -6752,7 +6782,7 @@ Do not broadcast or add to wallet.
    
 
    Remove all pending transactions older than a specified age.
    HTTP Request
    
-
    POST /wallet/:id/zap?age=3600 
    
+
    POST /wallet/:id/zap?age=3600
    Post Parameters
    
 
    
 
 
 
 
    
@@ -6774,15 +6804,15 @@ Do not broadcast or add to wallet.
    hash="2a22606ee555d2c26ec979f0c45cd2dc18c7177056189cb345989749fd58786"passphrase="bar"
    # Not available in CLI
-
    curl $url/wallet/$id/tx/$hash \ 
+
    curl $url/wallet/$id/tx/$hash \
   -X DELETE \
   --data '{"passphrase": "'$passphrase'"}'
-
     // Not available in javascript wallet client. 
+
     // Not available in javascript wallet client.
 
    Abandon single pending transaction. Confirmed transactions will throw an error.
 "TX not eligible"
    HTTP Request
    
-
    DEL /wallet/:id/tx/:hash 
    
+
    DEL /wallet/:id/tx/:hash
    
 
    
 
 
 
 
 
 
 
    
@@ -6802,23 +6832,23 @@ Do not broadcast or add to wallet.
    GET /wallet/:id/tx/history
    Get wallet TX history. Returns array of tx details.
    HTTP Request
    
-
    GET /wallet/:id/tx/history 
    
+
    GET /wallet/:id/tx/history
    GET /wallet/:id/tx/unconfirmed
    Get pending wallet transactions. Returns array of tx details.
    HTTP Request
    
-
    GET /wallet/:id/tx/unconfirmed 
    
+
    GET /wallet/:id/tx/unconfirmed
    GET /wallet/:id/tx/range
    Get range of wallet transactions by timestamp. Returns array of tx details.
    HTTP Request
    
-
    GET /wallet/:id/tx/range 
    
+
    GET /wallet/:id/tx/range
    GET /wallet/:id/tx/last
    Get last N wallet transactions.
    HTTP Request
    
-
    GET /wallet/:id/tx/last 
    
+
    GET /wallet/:id/tx/last
    GET /wallet/:id/tx/:hash
    Get wallet transaction details.
    HTTP Request
    
-
    GET /wallet/:id/tx/:hash 
    
+
    GET /wallet/:id/tx/:hash
    Wallet Accounts
    Account Object
    
 
    An account object looks like this:
    
@@ -6843,7 +6873,7 @@ Do not broadcast or add to wallet.
    
     "changeAddress": "n3nFYgQR2mrLwC3X66xHNsx4UqhS3rkSnY",
     "accountKey": "tpubDC5u44zLNUVo2gPVdqCbtX644PKccH5VZB3nqUgeCiwKoi6BQZGtr5d6hhougcD6PqjszsbR3xHrQ5k8yTbUt64aSthWuNdGi7zSwfGVuxc",
     "keys": []
-  } 
+  }
 
 
 
    Represents a BIP44 Account belonging to a Wallet.
@@ -6873,7 +6903,7 @@ Note that this object does not enforce locks. Any method that does a write is in
         Hardened derivation is used at this level.
     
 
    
-
    Get Wallet Account List
    id='test' 
+
    Get Wallet Account List
    id='test'
 
    bcoin cli wallet account list --id=$id
 
    const client = new bcoin.http.Client();
 (async () => {
@@ -6882,13 +6912,13 @@ Note that this object does not enforce locks. Any method that does a write is in
 })();
 
    
 
    
-
    Sample response: 
    
+
    Sample response:
    
 
    
 
    [
   "default"
 ]
 
    
-
    List all account names (array indicies map directly to bip44 account indicies) associated with a specific wallet id.
    
+
    List all account names (array indices map directly to bip44 account indices) associated with a specific wallet id.
    
 
    HTTP Request
    
 
    GET /wallet/:id/account
    
 
@@ -6919,7 +6949,7 @@ Note that command defaults to primary (default) wallet if no wallet id is passed
 })();
 
    
 
    
-
    Sample response: 
    
+
    Sample response:
    
 
    
 
    {
   "wid": 1,
@@ -6945,7 +6975,7 @@ Note that command defaults to primary (default) wallet if no wallet id is passed
 
    
 
    Get account info.
    
 
    HTTP Request
    
-
    GET /wallet/:id/account/:account 
    
+
    GET /wallet/:id/account/:account
    
 
 
    
 
    
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
    
@@ -6962,23 +6992,24 @@ Note that command defaults to primary (default) wallet if no wallet id is passed
 
    
 
    id of account you would to retrieve information for
 
    
 
    
-
    Create new wallet account
    let id, name;
+
    Create new wallet account
    let id, name, type;
 
    id='test'
 name='menace'
-
    bcoin cli wallet --id=$id account create $name --type=multisig
+type='multisig'
+
    bcoin cli wallet --id=$id account create $name --type=$type
 
    curl $url/wallet/$id/account/$name \
     -X PUT
-    --data '{"type": "multisig"}'
-
    const client = new bcoin.http.Client();
-const options = {type: 'multisig'};// options are the same as available wallet options
+    --data '{"type": "'$type"}'
+
    const httpWallet = new bcoin.http.Wallet({ id: id });
+const options = {type: type}
 
 (async () => {
-  const account = await client.createAccount(name, options);
+  const account = await httpWallet.createAccount(name, options);
   console.log(account);
-});
+})();
 
    
 
    
-
    Sample response: 
    
+
    Sample response:
    
 
    
 
    {
   "wid": 1,
@@ -7004,7 +7035,39 @@ Note that command defaults to primary (default) wallet if no wallet id is passed
 
    
 
    Create account with specified account name.
    
 
    HTTP Request
    
-
    PUT /wallet/:id/account/:name 
    
+
    PUT /wallet/:id/account/:name
    
+
    Options object
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    ParameterDescription
    name 
     string    		name to give the account. Option can be account or name
    witness 
     bool    		whether or not to act as segregated witness wallet account
    watchOnly 
     bool    		whether or not to make watch only account. Watch only accounts can't accept private keys for import (or sign transactions)
    type 
     string    		what type of wallet to make it ('multisig', 'pubkeyhash')
    m 
     int    		for multisig accounts, what to make m in m-of-n
    n 
     int    		for multisig accounts, what to make the n in m-of-n
    
 
    Errors
    
 
    Any errors will be returned with an http status code other than 200, containing a JSON object in the form: