gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/api/Wallet.md (about) 1 Wallet 2 ====== 3 4 The Sia API documentation can be found here: 5 [Sia API](https://sia.tech/docs/ "Sia API") 6 7 There may be functional API calls which are not documented. These are not 8 guaranteed to be supported beyond the current release, and should not be used 9 in production. 10 11 Overview 12 -------- 13 14 The wallet stores and manages siacoins and siafunds. The wallet's API endpoints 15 expose methods for creating and loading wallets, locking and unlocking, sending 16 siacoins and siafunds, and getting the wallet's balance. 17 18 You must create a wallet before you can use the wallet's API endpoints. You can 19 create a wallet with the `/wallet/init` endpoint. Wallets are always encrypted 20 on disk. Calls to some wallet API endpoints will fail until the wallet is 21 unlocked. The wallet can be unlocked with the `/wallet/unlock` endpoint. Once 22 the wallet is unlocked calls to the API endpoints will succeed until the wallet 23 is locked again with `/wallet/lock`, or Siad is restarted. The host and renter 24 require the miner to be unlocked. 25 26 Index 27 ----- 28 29 | Route | HTTP verb | 30 | ----------------------------------------------------------------------- | --------- | 31 | [/wallet](#wallet-get) | GET | 32 | [/wallet/033x](#wallet033x-post) | POST | 33 | [/wallet/address](#walletaddress-get) | GET | 34 | [/wallet/addresses](#walletaddresses-get) | GET | 35 | [/wallet/backup](#walletbackup-get) | GET | 36 | [/wallet/changepassword](#walletchangepassword-post) | POST | 37 | [/wallet/init](#walletinit-post) | POST | 38 | [/wallet/init/seed](#walletinitseed-post) | POST | 39 | [/wallet/lock](#walletlock-post) | POST | 40 | [/wallet/seed](#walletseed-post) | POST | 41 | [/wallet/seeds](#walletseeds-get) | GET | 42 | [/wallet/siacoins](#walletsiacoins-post) | POST | 43 | [/wallet/siafunds](#walletsiafunds-post) | POST | 44 | [/wallet/siagkey](#walletsiagkey-post) | POST | 45 | [/wallet/sign](#walletsign-post) | POST | 46 | [/wallet/sweep/seed](#walletsweepseed-post) | POST | 47 | [/wallet/transaction/___:id___](#wallettransactionid-get) | GET | 48 | [/wallet/transactions](#wallettransactions-get) | GET | 49 | [/wallet/transactions/___:addr___](#wallettransactionsaddr-get) | GET | 50 | [/wallet/unlock](#walletunlock-post) | POST | 51 | [/wallet/unlockconditions](#walletunlockconditions-post) | POST | 52 | [/wallet/unlockconditions/___:addr___](#walletunlockconditionsaddr-get) | GET | 53 | [/wallet/unspent](#walletunspent-get) | GET | 54 | [/wallet/verify/address/:___addr___](#walletverifyaddressaddr-get) | GET | 55 | [/wallet/watch](#walletwatch-post) | POST | 56 57 58 #### /wallet [GET] 59 60 returns basic information about the wallet, such as whether the wallet is 61 locked or unlocked. 62 63 ###### JSON Response 64 ```javascript 65 { 66 // Indicates whether the wallet has been encrypted or not. If the wallet 67 // has not been encrypted, then no data has been generated at all, and the 68 // first time the wallet is unlocked, the password given will be used as 69 // the password for encrypting all of the data. 'encrypted' will only be 70 // set to false if the wallet has never been unlocked before (the unlocked 71 // wallet is still encryped - but the encryption key is in memory). 72 "encrypted": true, 73 74 // Indicates whether the wallet is currently locked or unlocked. Some calls 75 // become unavailable when the wallet is locked. 76 "unlocked": true, 77 78 // Indicates whether the wallet is currently rescanning the blockchain. This 79 // will be true for the duration of calls to /unlock, /seeds, /init/seed, 80 // and /sweep/seed. 81 "rescanning": false, 82 83 // Number of siacoins, in hastings, available to the wallet as of the most 84 // recent block in the blockchain. 85 "confirmedsiacoinbalance": "123456", // hastings, big int 86 87 // Number of siacoins, in hastings, that are leaving the wallet according 88 // to the set of unconfirmed transactions. Often this number appears 89 // inflated, because outputs are frequently larger than the number of coins 90 // being sent, and there is a refund. These coins are counted as outgoing, 91 // and the refund is counted as incoming. The difference in balance can be 92 // calculated using 'unconfirmedincomingsiacoins' - 'unconfirmedoutgoingsiacoins' 93 "unconfirmedoutgoingsiacoins": "0", // hastings, big int 94 95 // Number of siacoins, in hastings, are entering the wallet according to 96 // the set of unconfirmed transactions. This number is often inflated by 97 // outgoing siacoins, because outputs are frequently larger than the amount 98 // being sent. The refund will be included in the unconfirmed incoming 99 // siacoins balance. 100 "unconfirmedincomingsiacoins": "789", // hastings, big int 101 102 // Number of siafunds available to the wallet as of the most recent block 103 // in the blockchain. 104 "siafundbalance": "1", // big int 105 106 // Number of siacoins, in hastings, that can be claimed from the siafunds 107 // as of the most recent block. Because the claim balance increases every 108 // time a file contract is created, it is possible that the balance will 109 // increase before any claim transaction is confirmed. 110 "siacoinclaimbalance": "9001", // hastings, big int 111 112 // Number of siacoins, in hastings per byte, below which a transaction output 113 // cannot be used because the wallet considers it a dust output 114 "dustthreshold": "1234", // hastings / byte, big int 115 } 116 ``` 117 118 #### /wallet/033x [POST] 119 120 loads a v0.3.3.x wallet into the current wallet, harvesting all of the secret 121 keys. All spendable addresses in the loaded wallet will become spendable from 122 the current wallet. An error will be returned if the given `encryptionpassword` 123 is incorrect. 124 125 ###### Query String Parameters 126 ``` 127 // Path on disk to the v0.3.3.x wallet to be loaded. 128 source 129 130 // Encryption key of the wallet. 131 encryptionpassword 132 ``` 133 134 ###### Response 135 standard success or error response. See 136 [API.md#standard-responses](/doc/API.md#standard-responses). 137 138 #### /wallet/address [GET] 139 140 gets a new address from the wallet generated by the primary seed. An error will 141 be returned if the wallet is locked. 142 143 ###### JSON Response 144 ```javascript 145 { 146 // Wallet address that can receive siacoins or siafunds. Addresses are 76 character long hex strings. 147 "address": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab" 148 } 149 ``` 150 151 #### /wallet/addresses [GET] 152 153 fetches the list of addresses from the wallet. If the wallet has not been 154 created or unlocked, no addresses will be returned. After the wallet is 155 unlocked, this call will continue to return its addresses even after the 156 wallet is locked again. 157 158 ###### JSON Response 159 ```javascript 160 { 161 // Array of wallet addresses owned by the wallet. 162 "addresses": [ 163 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab", 164 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", 165 "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" 166 ] 167 } 168 ``` 169 170 #### /wallet/backup [GET] 171 172 creates a backup of the wallet settings file. Though this can easily be done 173 manually, the settings file is often in an unknown or difficult to find 174 location. The /wallet/backup call can spare users the trouble of needing to 175 find their wallet file. The destination file is overwritten if it already 176 exists. 177 178 ###### Query String Parameters 179 ``` 180 // path to the location on disk where the backup file will be saved. 181 destination 182 ``` 183 184 ###### Response 185 standard success or error response. See 186 [API.md#standard-responses](/doc/API.md#standard-responses). 187 188 #### /wallet/changepassword [POST] 189 190 changes the wallet's encryption password. 191 192 ###### Query String Parameter 193 ``` 194 // encryptionpassword is the wallet's current encryption password. 195 encryptionpassword 196 // newpassword is the new password for the wallet. 197 newpassword 198 ``` 199 200 ###### Response 201 standard success or error response. See 202 [#standard-responses](#standard-responses). 203 204 #### /wallet/init [POST] 205 206 initializes the wallet. After the wallet has been initialized once, it does not 207 need to be initialized again, and future calls to /wallet/init will return an 208 error, unless the force flag is set. The encryption password is provided by the 209 api call. If the password is blank, then the password will be set to the same 210 as the seed. 211 212 ###### Query String Parameters 213 ``` 214 // Password that will be used to encrypt the wallet. All subsequent calls 215 // should use this password. If left blank, the seed that gets returned will 216 // also be the encryption password. 217 encryptionpassword 218 219 // Name of the dictionary that should be used when encoding the seed. 'english' 220 // is the most common choice when picking a dictionary. 221 dictionary // Optional, default is english. 222 223 // boolean, when set to true /wallet/init will Reset the wallet if one exists 224 // instead of returning an error. This allows API callers to reinitialize a new 225 // wallet. 226 force 227 ``` 228 229 ###### JSON Response 230 ```javascript 231 { 232 // Wallet seed used to generate addresses that the wallet is able to spend. 233 "primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello" 234 } 235 ``` 236 237 #### /wallet/init/seed [POST] 238 239 initializes the wallet using a preexisting seed. After the wallet has been 240 initialized once, it does not need to be initialized again, and future calls to 241 /wallet/init/seed will return an error unless the force flag is set. The 242 encryption password is provided by the api call. If the password is blank, then 243 the password will be set to the same as the seed. Note that loading a 244 preexisting seed requires scanning the blockchain to determine how many keys 245 have been generated from the seed. For this reason, /wallet/init/seed can only 246 be called if the blockchain is synced. 247 248 ###### Query String Parameters 249 ``` 250 // Password that will be used to encrypt the wallet. All subsequent calls 251 // should use this password. If left blank, the seed that gets returned will 252 // also be the encryption password. 253 encryptionpassword 254 255 // Name of the dictionary that should be used when encoding the seed. 'english' 256 // is the most common choice when picking a dictionary. 257 dictionary // Optional, default is english. 258 259 // Dictionary-encoded phrase that corresponds to the seed being used to 260 // initialize the wallet. 261 seed 262 263 // boolean, when set to true /wallet/init will Reset the wallet if one exists 264 // instead of returning an error. This allows API callers to reinitialize a new 265 // wallet. 266 force 267 ``` 268 269 ###### Response 270 standard success or error response. See 271 [API.md#standard-responses](/doc/API.md#standard-responses). 272 273 #### /wallet/seed [POST] 274 275 gives the wallet a seed to track when looking for incoming transactions. The 276 wallet will be able to spend outputs related to addresses created by the seed. 277 The seed is added as an auxiliary seed, and does not replace the primary seed. 278 Only the primary seed will be used for generating new addresses. 279 280 ###### Query String Parameters 281 ``` 282 // Key used to encrypt the new seed when it is saved to disk. 283 encryptionpassword 284 285 // Name of the dictionary that should be used when encoding the seed. 'english' 286 // is the most common choice when picking a dictionary. 287 dictionary 288 289 // Dictionary-encoded phrase that corresponds to the seed being added to the 290 // wallet. 291 seed 292 ``` 293 294 ###### Response 295 standard success or error response. See 296 [API.md#standard-responses](/doc/API.md#standard-responses). 297 298 #### /wallet/seeds [GET] 299 300 returns a list of seeds in use by the wallet. The primary seed is the only seed 301 that gets used to generate new addresses. This call is unavailable when the 302 wallet is locked. 303 304 A seed is an encoded version of a 256 bit random seed. The output is 29 words 305 chosen from a small dictionary as indicated by the input. The most common 306 choice for the dictionary is going to be 'english'. The underlying seed is the 307 same no matter what dictionary is used for the encoding. The encoding also 308 contains a small checksum of the seed, to help catch simple mistakes when 309 copying. The library 310 [entropy-mnemonics](https://gitlab.com/SiaPrime/entropy-mnemonics) is used 311 when encoding. 312 313 ###### Query String Parameters 314 ``` 315 // Name of the dictionary that should be used when encoding the seed. 'english' 316 // is the most common choice when picking a dictionary. 317 dictionary 318 ``` 319 320 ###### JSON Response 321 ```javascript 322 { 323 // Seed that is actively being used to generate new addresses for the wallet. 324 "primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello", 325 326 // Number of addresses that remain in the primary seed until exhaustion has 327 // been reached. Once exhaustion has been reached, new addresses will 328 // continue to be generated but they will be more difficult to recover in the 329 // event of a lost wallet file or encryption password. 330 "addressesremaining": 2500, 331 332 // Array of all seeds that the wallet references when scanning the blockchain 333 // for outputs. The wallet is able to spend any output generated by any of 334 // the seeds, however only the primary seed is being used to generate new 335 // addresses. 336 "allseeds": [ 337 "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello", 338 "foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo", 339 ] 340 } 341 ``` 342 343 #### /wallet/siacoins [POST] 344 345 Function: Send siacoins to an address or set of addresses. The outputs are 346 arbitrarily selected from addresses in the wallet. If 'outputs' is supplied, 347 'amount' and 'destination' must be empty. The number of outputs should not 348 exceed 400; this may result in a transaction too large to fit in the 349 transaction pool. 350 351 ###### Query String Parameters 352 ``` 353 // Number of hastings being sent. A hasting is the smallest unit in SiaPrime. There 354 // are 10^24 hastings in a siacoin. 355 amount // hastings 356 357 // Address that is receiving the coins. 358 destination // address 359 360 // JSON array of outputs. The structure of each output is: 361 // {"unlockhash": "<destination>", "value": "<amount>"} 362 outputs 363 ``` 364 365 ###### JSON Response 366 ```javascript 367 { 368 // Array of IDs of the transactions that were created when sending the coins. 369 // The last transaction contains the output headed to the 'destination'. 370 // Transaction IDs are 64 character long hex strings. 371 transactionids [ 372 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 373 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", 374 "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" 375 ] 376 } 377 ``` 378 379 ### Examples 380 381 #### Send to single address 382 383 ###### Example POST Request 384 Use _amount_ and _destination_ parameters. 385 ``` 386 /wallet/siacoins?amount=1000000000000000000000000&destination=1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab 387 ``` 388 389 ###### Expected Response Code 390 ``` 391 200 OK 392 ``` 393 394 ###### Example Response Body 395 ```json 396 { 397 "transactionids": [ 398 "3918e4a4b4cee46b3e5b28b8a1cc41c064a6f6002d162d396f296c201e6edc13", 399 "18b85b7d20f8a87bdadacf11e135ad44db1d93efd0613d23116e8cf255502762" 400 ] 401 } 402 ``` 403 404 405 #### Send to set of addresses 406 Use _outputs_ parameter in the form of a JSON array. _amount_ and _destination_ parameters must be empty. 407 408 409 ###### Example POST Request 410 ``` 411 /wallet/siacoins?outputs=[{"unlockhash":"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab","value":"1000000000000000000000000"},{"unlockhash":"abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab1234567890","value":"8000000000000000000000000"},{"unlockhash":"cdef0123456789abcdef0123456789abcdef0123456789ab1234567890abcdef0123456789ab","value":"5000000000000000000000000"}] 412 ``` 413 414 ###### (sample JSON request body for reference) 415 ```json 416 { 417 "outputs": [ 418 { 419 "unlockhash": 420 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab", 421 "value": "1000000000000000000000000" 422 }, 423 { 424 "unlockhash": 425 "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab1234567890", 426 "value": "8000000000000000000000000" 427 }, 428 { 429 "unlockhash": 430 "cdef0123456789abcdef0123456789abcdef0123456789ab1234567890abcdef0123456789ab", 431 "value": "20000000000000000000000000" 432 } 433 ] 434 } 435 436 ``` 437 438 ###### Expected Response Code 439 ``` 440 200 OK 441 ``` 442 443 ###### Example Response Body 444 ```json 445 { 446 "transactionids": [ 447 "21962e0118f3ca5d6fab0262c65bca0220fbcc828c499974d86e7cc4047a0ce5", 448 "f2471d550823f2c0616565d8476a7fea5f2b9a841612bf109923c3a54e760721" 449 ] 450 } 451 ``` 452 453 #### /wallet/siafunds [POST] 454 455 sends siafunds to an address. The outputs are arbitrarily selected from 456 addresses in the wallet. Any siacoins available in the siafunds being sent (as 457 well as the siacoins available in any siafunds that end up in a refund address) 458 will become available to the wallet as siacoins after 144 confirmations. To 459 access all of the siacoins in the siacoin claim balance, send all of the 460 siafunds to an address in your control (this will give you all the siacoins, 461 while still letting you control the siafunds). 462 463 ###### Query String Parameters 464 ``` 465 // Number of siafunds being sent. 466 amount // siafunds 467 468 // Address that is receiving the funds. 469 destination // address 470 ``` 471 472 ###### JSON Response 473 ```javascript 474 { 475 // Array of IDs of the transactions that were created when sending the coins. 476 // The last transaction contains the output headed to the 'destination'. 477 // Transaction IDs are 64 character long hex strings. 478 "transactionids": [ 479 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 480 "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", 481 "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" 482 ] 483 } 484 ``` 485 486 #### /wallet/siagkey [POST] 487 488 Function: Load a key into the wallet that was generated by siag. Most siafunds 489 are currently in addresses created by siag. 490 491 ###### Query String Parameters 492 ``` 493 // Key that is used to encrypt the siag key when it is imported to the wallet. 494 encryptionpassword 495 496 // List of filepaths that point to the keyfiles that make up the siag key. 497 // There should be at least one keyfile per required signature. The filenames 498 // need to be commna separated (no spaces), which means filepaths that contain 499 // a comma are not allowed. 500 keyfiles 501 ``` 502 503 ###### Response 504 standard success or error response. See 505 [API.md#standard-responses](/doc/API.md#standard-responses). 506 507 #### /wallet/sign [POST] 508 509 Function: Sign a transaction. The transaction's TransactionSignatures should 510 be complete except for the Signature field. If `tosign` is provided, the 511 wallet will attempt to fill in signatures for each TransactionSignature 512 specified. If `tosign` is not provided, the wallet will add signatures for 513 every TransactionSignature that it has keys for. 514 515 ###### Request Body 516 ```javascript 517 { 518 // Unsigned transaction 519 "transaction": { 520 "siacoininputs": [ 521 { 522 "parentid": "af1a88781c362573943cda006690576b150537c1ae142a364dbfc7f04ab99584", 523 "unlockconditions": { 524 "timelock": 0, 525 "publickeys": [ "ed25519:8b845bf4871bcdf4ff80478939e508f43a2d4b2f68e94e8b2e3d1ea9b5f33ef1" ], 526 "signaturesrequired": 1 527 } 528 } 529 ], 530 "siacoinoutputs": [ 531 { 532 "value": "5000000000000000000000000", 533 "unlockhash": "17d25299caeccaa7d1598751f239dd47570d148bb08658e596112d917dfa6bc8400b44f239bb" 534 }, 535 { 536 "value": "299990000000000000000000000000", 537 "unlockhash": "b4bf662170622944a7c838c7e75665a9a4cf76c4cebd97d0e5dcecaefad1c8df312f90070966" 538 } 539 ], 540 "minerfees": [ "1000000000000000000000000" ], 541 "transactionsignatures": [ 542 { 543 "parentid": "af1a88781c362573943cda006690576b150537c1ae142a364dbfc7f04ab99584", 544 "publickeyindex": 0, 545 "coveredfields": {"wholetransaction": true} 546 } 547 ] 548 }, 549 550 // Optional IDs to sign; each should correspond to a parentid in the transactionsignatures. 551 "tosign": [ 552 "af1a88781c362573943cda006690576b150537c1ae142a364dbfc7f04ab99584" 553 ] 554 } 555 ``` 556 557 ###### Response 558 ```javascript 559 { 560 // signed transaction 561 "transaction": { 562 "siacoininputs": [ 563 { 564 "parentid": "af1a88781c362573943cda006690576b150537c1ae142a364dbfc7f04ab99584", 565 "unlockconditions": { 566 "timelock": 0, 567 "publickeys": [ "ed25519:8b845bf4871bcdf4ff80478939e508f43a2d4b2f68e94e8b2e3d1ea9b5f33ef1" ], 568 "signaturesrequired": 1 569 } 570 } 571 ], 572 "siacoinoutputs": [ 573 { 574 "value": "5000000000000000000000000", 575 "unlockhash": "17d25299caeccaa7d1598751f239dd47570d148bb08658e596112d917dfa6bc8400b44f239bb" 576 }, 577 { 578 "value": "299990000000000000000000000000", 579 "unlockhash": "b4bf662170622944a7c838c7e75665a9a4cf76c4cebd97d0e5dcecaefad1c8df312f90070966" 580 } 581 ], 582 "minerfees": [ "1000000000000000000000000" ], 583 "transactionsignatures": [ 584 { 585 "parentid": "af1a88781c362573943cda006690576b150537c1ae142a364dbfc7f04ab99584", 586 "publickeyindex": 0, 587 "coveredfields": {"wholetransaction": true}, 588 "signature": "CVkGjy4The6h+UU+O8rlZd/O3Gb1xRJdyQ2vzBFEb/5KveDKDrrieCiFoNtUaknXEQbdxlrDqMujc+x3aZbKCQ==" 589 } 590 ] 591 } 592 } 593 ``` 594 595 #### /wallet/sweep/seed [POST] 596 597 Function: Scan the blockchain for outputs belonging to a seed and send them to 598 an address owned by the wallet. 599 600 ###### Query String Parameters 601 ``` 602 // Name of the dictionary that should be used when decoding the seed. 'english' 603 // is the most common choice when picking a dictionary. 604 dictionary // Optional, default is english. 605 606 // Dictionary-encoded phrase that corresponds to the seed being added to the 607 // wallet. 608 seed 609 ``` 610 611 ###### JSON Response 612 ```javascript 613 { 614 // Number of siacoins, in hastings, transferred to the wallet as a result of 615 // the sweep. 616 "coins": "123456", // hastings, big int 617 618 // Number of siafunds transferred to the wallet as a result of the sweep. 619 "funds": "1", // siafunds, big int 620 } 621 ``` 622 623 #### /wallet/lock [POST] 624 625 locks the wallet, wiping all secret keys. After being locked, the keys are 626 encrypted. Queries for the seed, to send siafunds, and related queries become 627 unavailable. Queries concerning transaction history and balance are still 628 available. 629 630 ###### Response 631 standard success or error response. See 632 [API.md#standard-responses](/doc/API.md#standard-responses). 633 634 #### /wallet/transaction/___:id___ [GET] 635 636 gets the transaction associated with a specific transaction id. 637 638 ###### Path Parameters 639 ``` 640 // ID of the transaction being requested. 641 :id 642 ``` 643 644 ###### JSON Response 645 ```javascript 646 { 647 "transaction": { 648 // Raw transaction. The rest of the fields in the resposne are determined 649 // from this raw transaction. It is left undocumented here as the processed 650 // transaction (the rest of the fields in this object) are usually what is 651 // desired. 652 "transaction": { 653 // See types.Transaction in https://gitlab.com/SiaPrime/SiaPrime/blob/master/types/transactions.go 654 }, 655 656 // ID of the transaction from which the wallet transaction was derived. 657 "transactionid": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 658 659 // Block height at which the transaction was confirmed. If the transaction 660 // is unconfirmed the height will be the max value of an unsigned 64-bit 661 // integer. 662 "confirmationheight": 50000, 663 664 // Time, in unix time, at which a transaction was confirmed. If the 665 // transaction is unconfirmed the timestamp will be the max value of an 666 // unsigned 64-bit integer. 667 "confirmationtimestamp": 1257894000, 668 669 // Array of processed inputs detailing the inputs to the transaction. 670 "inputs": [ 671 { 672 // The id of the output being spent. 673 "parentid": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 674 675 // Type of fund represented by the input. Possible values are 676 // 'siacoin input' and 'siafund input'. 677 "fundtype": "siacoin input", 678 679 // true if the address is owned by the wallet. 680 "walletaddress": false, 681 682 // Address that is affected. For inputs (outgoing money), the related 683 // address is usually not important because the wallet arbitrarily 684 // selects which addresses will fund a transaction. 685 "relatedaddress": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab", 686 687 // Amount of funds that have been moved in the input. 688 "value": "1234", // hastings or siafunds, depending on fundtype, big int 689 } 690 ], 691 // Array of processed outputs detailing the outputs of the transaction. 692 // Outputs related to file contracts are excluded. 693 "outputs": [ 694 { 695 // The id of the output that was created. 696 "id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 697 698 // Type of fund is represented by the output. Possible values are 699 // 'siacoin output', 'siafund output', 'claim output', and 'miner 700 // payout'. Siacoin outputs and claim outputs both relate to siacoins. 701 // Siafund outputs relate to siafunds. Miner payouts point to siacoins 702 // that have been spent on a miner payout. Because the destination of 703 // the miner payout is determined by the block and not the transaction, 704 // the data 'maturityheight', 'walletaddress', and 'relatedaddress' are 705 // left blank. 706 "fundtype": "siacoin output", 707 708 // Block height the output becomes available to be spent. Siacoin 709 // outputs and siafund outputs mature immediately - their maturity 710 // height will always be the confirmation height of the transaction. 711 // Claim outputs cannot be spent until they have had 144 confirmations, 712 // thus the maturity height of a claim output will always be 144 larger 713 // than the confirmation height of the transaction. 714 "maturityheight": 50000, 715 716 // true if the address is owned by the wallet. 717 "walletaddress": false, 718 719 // Address that is affected. For outputs (incoming money), the related 720 // address field can be used to determine who has sent money to the 721 // wallet. 722 "relatedaddress": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", 723 724 // Amount of funds that have been moved in the output. 725 "value": "1234", // hastings or siafunds, depending on fundtype, big int 726 } 727 ] 728 } 729 } 730 ``` 731 732 #### /wallet/transactions [GET] 733 734 returns a list of transactions related to the wallet. 735 736 ###### Query String Parameters 737 ``` 738 // Height of the block where transaction history should begin. 739 startheight // block height 740 741 // Height of of the block where the transaction history should end. If 742 // 'endheight' is greater than the current height, or if it is '-1', all 743 // transactions up to and including the most recent block will be provided. 744 endheight // block height 745 ``` 746 747 ###### JSON Response 748 ```javascript 749 { 750 // All of the confirmed transactions appearing between height 'startheight' 751 // and height 'endheight' (inclusive). 752 "confirmedtransactions": [ 753 { 754 // See the documentation for '/wallet/transaction/:id' for more information. 755 } 756 ], 757 758 // All of the unconfirmed transactions. 759 "unconfirmedtransactions": [ 760 { 761 // See the documentation for '/wallet/transaction/:id' for more information. 762 } 763 ] 764 } 765 ``` 766 767 #### /wallet/transactions/___:addr___ [GET] 768 769 returns all of the transactions related to a specific address. 770 771 ###### Path Parameters 772 ``` 773 // Unlock hash (i.e. wallet address) whose transactions are being requested. 774 :addr 775 ``` 776 777 ###### JSON Response 778 ```javascript 779 { 780 // Array of processed transactions that relate to the supplied address. 781 "transactions": [ 782 { 783 // See the documentation for '/wallet/transaction/:id' for more information. 784 } 785 ] 786 } 787 ``` 788 789 #### /wallet/unlock [POST] 790 791 unlocks the wallet. The wallet is capable of knowing whether the correct 792 password was provided. 793 794 ###### Query String Parameters 795 ``` 796 // Password that gets used to decrypt the file. Most frequently, the encryption 797 // password is the same as the primary wallet seed. 798 encryptionpassword string 799 ``` 800 801 ###### Response 802 standard success or error response. See 803 [API.md#standard-responses](/doc/API.md#standard-responses). 804 805 #### /wallet/unlockconditions [POST] 806 807 stores a set of unlock conditions in the wallet database. 808 809 ###### Request Body 810 ```javascript 811 { 812 "unlockconditions": { 813 // the minimum blockheight required 814 "timelock": 0, 815 // the number of signatures required 816 "signaturesrequired": 1, 817 // the set of keys whose signatures count towards signaturesrequired 818 "publickeys": [{ 819 "algorithm": "ed25519", 820 "key": "/XUGj8PxMDkqdae6Js6ubcERxfxnXN7XPjZyANBZH1I=" 821 }] 822 } 823 } 824 ``` 825 826 ###### Response 827 standard success or error response. See 828 [API.md#standard-responses](/doc/API.md#standard-responses). 829 830 #### /wallet/unlockconditions/___:addr___ [GET] 831 832 returns the unlock conditions of :addr, if they are known to the wallet. 833 834 ###### Response 835 ```javascript 836 { 837 "unlockconditions": { 838 // the minimum blockheight required 839 "timelock": 0, 840 // the number of signatures required 841 "signaturesrequired": 1, 842 // the set of keys whose signatures count towards signaturesrequired 843 "publickeys": [{ 844 "algorithm": "ed25519", 845 "key": "/XUGj8PxMDkqdae6Js6ubcERxfxnXN7XPjZyANBZH1I=" 846 }] 847 } 848 } 849 ``` 850 851 #### /wallet/unspent [GET] 852 853 returns a list of unspent outputs that the wallet is tracking. 854 855 ###### Response 856 ```javascript 857 { 858 // Array of outputs that the wallet can spend. 859 "outputs": [ 860 { 861 // The id of the output. 862 "id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 863 864 // Type of output, either 'siacoin output' or 'siafund output'. 865 "fundtype": "siacoin output", 866 867 // Height of block in which the output appeared. To calculate the 868 // number of confirmations, subtract this number from the current 869 // block height. 870 "confirmationheight": 50000, 871 872 // Hash of the output's unlock conditions, commonly known as the "address". 873 "unlockhash": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab", 874 875 // Amount of funds in the output; hastings for siacoin outputs, and 876 // siafunds for siafund outputs. 877 "value": "1234", // big int 878 879 // Whether the output comes from a watched address or from the wallet's seed. 880 "iswatchonly": false 881 } 882 ] 883 } 884 ``` 885 886 #### /wallet/verify/address/___:addr___ [GET] 887 888 takes the address specified by :addr and returns a JSON response indicating if the address is valid. 889 890 ###### JSON Response 891 ```javascript 892 { 893 // valid indicates if the address supplied to :addr is a valid UnlockHash. 894 "valid": true 895 } 896 ``` 897 898 #### /wallet/watch [GET] 899 900 returns the set of addresses that the wallet is watching. This set only 901 includes addresses that were explicitly requested to be watched; addresses 902 that were generated automatically by the wallet, or by /wallet/address, are 903 not included. 904 905 ###### JSON Response [(with comments)](/doc/api/Wallet.md#json-response-12) 906 ```javascript 907 { 908 // The addresses currently watched by the wallet. 909 "addresses": [ 910 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 911 "abcdef0123456789abcdef0123456789abcd1234567890ef0123456789abcdef" 912 ] 913 } 914 ``` 915 916 #### /wallet/watch [POST] 917 918 updates the set of addresses watched by the wallet. 919 920 ###### Request Body 921 ``` 922 { 923 // The addresses to add or remove from the current set. 924 "addresses": [ 925 "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 926 "abcdef0123456789abcdef0123456789abcd1234567890ef0123456789abcdef" 927 ], 928 929 // If true, remove the addresses instead of adding them. 930 "remove": false, 931 932 // If true, the wallet will not rescan the blockchain. Only set this flag if 933 // the addresses have never appeared in the blockchain. 934 "unused": true, 935 } 936 937 ``` 938 939 ###### Response 940 standard success or error response. See 941 [#standard-responses](#standard-responses).