Skip to content

Commit 622cdf0

Browse files
nodechnodech
committed
api-docs: update tx history and tx pending docs.
1 parent 6dd861a commit 622cdf0

File tree

1 file changed

+78
-104
lines changed

1 file changed

+78
-104
lines changed

‎src/api-docs/source/includes/_wallet_tx.md‎

Lines changed: 78 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -148,19 +148,22 @@ hash <br> _string_ | hash of transaction you would like to remove.
148148
## Get Wallet TX History
149149

150150
```javascript
151-
let id;
151+
let id, limit, time, reverse;
152152
```
153153

154154
```shell--vars
155155
id='primary'
156+
limit=5
157+
time=1736413154
158+
reverse=true
156159
```
157160

158161
```shell--cli
159-
hsw-cli --id=$id history
162+
hsw-cli --id=$id history --limit=$limit --time=$time --reverse=$reverse
160163
```
161164

162165
```shell--curl
163-
curl http://x:[email protected]:14039/wallet/$id/tx/history
166+
curl http://x:[email protected]:14039/wallet/$id/tx/history?limit=$limit&time=$time&reverse=$reverse
164167
```
165168

166169
```javascript
@@ -178,7 +181,12 @@ const wallet = walletClient.wallet(id);
178181
const account = 'default';
179182

180183
(async () => {
181-
const result = await wallet.getHistory(account);
184+
const options = {
185+
limit,
186+
time,
187+
reverse
188+
};
189+
const result = await wallet.getHistory(options);
182190
console.log(result);
183191
})();
184192
```
@@ -247,83 +255,50 @@ const account = 'default';
247255
]
248256
```
249257

250-
Get wallet TX history. Returns array of tx details.
258+
Get wallet transaction history chronologically (oldest to newest, unless reversed), including both confirmed and pending transactions. Returns an array of transaction details.
251259

252260
### HTTP Request
253261
`GET /wallet/:id/tx/history`
254262

255-
### Request Parameters
256-
Parameter | Description
257-
-------- | -------------------------
258-
id <br> _string_ | id of wallet to get history of
263+
Parameter | Description
264+
---------------- | -----------
265+
id <br> _string_ | Wallet ID
259266

260-
## Get Pending Transactions
267+
### Query Parameters
261268

262-
```javascript
263-
let id;
264-
```
269+
Parameter | Default | Description
270+
--------------------- | ------- | -----------
271+
account <br> _string_ | Optional | Account name to filter transactions. All TXs by default.
272+
after <br> _hex_ | Optional | List transactions after this tx hash (priority 1)
273+
time <br> _int_ | Optional | List transactions after this timestamp in epoch seconds (priority 2)
274+
limit <br> _int_ | `maxTXs`* | Maximum number of transactions to return
275+
reverse <br> _bool_ | `false` | TX Ordering, whether it should reverse the chronological order (oldest to newest)
265276

266-
```shell--vars
267-
id='primary'
268-
```
277+
Notes:
269278

270-
```shell--cli
271-
hsw-cli --id=$id pending
272-
```
273-
274-
```shell--curl
275-
curl http://x:[email protected]:14039/wallet/$id/tx/unconfirmed
276-
```
277-
278-
```javascript
279-
const {WalletClient} = require('hs-client');
280-
const {Network} = require('hsd');
281-
const network = Network.get('regtest');
282-
283-
const walletOptions = {
284-
port: network.walletPort,
285-
apiKey: 'api-key'
286-
}
287-
288-
const walletClient = new WalletClient(walletOptions);
289-
const wallet = walletClient.wallet(id);
290-
291-
(async () => {
292-
const result = await wallet.getPending();
293-
console.log(result);
294-
})();
295-
```
296-
297-
Get pending wallet transactions. Returns array of tx details.
298-
299-
### HTTP Request
300-
301-
`GET /wallet/:id/tx/unconfirmed`
302-
303-
### Request Parameters
304-
Parameter | Description
305-
-------- | -------------------------
306-
id <br> _string_ | id of wallet to get pending/unconfirmed txs
279+
- When using `time`, the timestamp is indexed based on median-time-past (MTP).
280+
- *`maxTXs` refers to wallet `maxHistoryTXs` configuration.
281+
- `limit` can not exceed `maxHistoryTXs` configuration.
307282

283+
## Get Pending Transactions
308284

309-
## Get Range of Transactions
310285
```javascript
311-
let id, account, start, end;
286+
let id, limit, after, reverse;
312287
```
313288

314289
```shell--vars
315-
id="primary"
316-
account="default"
317-
start="1527184612"
318-
end="1527186612"
290+
id='primary'
291+
limit=5
292+
reverse=true
293+
after='6cfd18f4e5810cc4285964df3cda75b8249d336e3544c2db9b30f066d349d0cc'
319294
```
320295

321296
```shell--cli
322-
# range not available in CLI
297+
hsw-cli --id=$id pending --limit=$limit --after=$after --reverse=$reverse
323298
```
324299

325300
```shell--curl
326-
curl http://x:[email protected]:14039/wallet/$id/tx/range?start=$start'&'end=$end
301+
curl http://x:[email protected]:14039/wallet/$id/tx/unconfirmed?limit=$limit&after=$after&reverse=$reverse
327302
```
328303

329304
```javascript
@@ -340,95 +315,94 @@ const walletClient = new WalletClient(walletOptions);
340315
const wallet = walletClient.wallet(id);
341316

342317
(async () => {
343-
const result = await wallet.getRange(account, {start: start, end: end});
318+
const options = {
319+
limit,
320+
reverse,
321+
after
322+
};
323+
const result = await wallet.getPending(options);
344324
console.log(result);
345325
})();
346326
```
327+
347328
> Sample Response
348329
349330
```json
350331
[
351332
{
352-
"hash": "bc0f93bb233fdf42a25a086ffb744fcb4f64afe6f5d4243da8e3745835fd57b3",
333+
"hash": "57dd1e1b306de8da08d38b68b77e239bffe6d6b0b32bd734cf72684c21a03068",
353334
"height": -1,
354335
"block": null,
355336
"time": 0,
356-
"mtime": 1528468930,
337+
"mtime": 1736411031,
357338
"date": "1970-01-01T00:00:00Z",
358-
"mdate": "2018-06-08T14:42:10Z",
339+
"mdate": "2025-01-09T08:23:51Z",
359340
"size": 215,
360341
"virtualSize": 140,
361-
"fee": 2800,
362-
"rate": 20000,
342+
"fee": 0,
343+
"rate": 0,
363344
"confirmations": 0,
364345
"inputs": [
365346
{
366-
"value": 500002800,
367-
"address": "rs1q7qumafugfglg268djelwr7ps4l2uh2vsdpfnuc",
368-
"path": {
369-
"name": "default",
370-
"account": 0,
371-
"change": false,
372-
"derivation": "m/0'/0/0"
373-
}
347+
"value": 0,
348+
"address": "rs1qannv3v0wacekpsfk9ysa2p7mnepd86c63543sh",
349+
"path": null
374350
}
375351
],
376352
"outputs": [
377353
{
378-
"value": 100000000,
379-
"address": "rs1q7rvnwj3vaqxrwuv87j7xc6ye83tpevfkvhzsap",
354+
"value": 9000000,
355+
"address": "rs1qgjpc0kpty45za0dwdf4jgqmw9e3yjtej3gvadw",
380356
"covenant": {
381357
"type": 0,
358+
"action": "NONE",
382359
"items": []
383360
},
384361
"path": {
385362
"name": "default",
386363
"account": 0,
387364
"change": false,
388-
"derivation": "m/0'/0/1"
365+
"derivation": "m/0'/0/2"
389366
}
390367
},
391368
{
392-
"value": 400000000,
393-
"address": "rs1q2x2suqr44gjn2plm3f99v2ae6ead3rpat9qtzg",
369+
"value": 1990997200,
370+
"address": "rs1qpaf5s2qyl8pyu0upgpq95m68kfp7gnflgcscsr",
394371
"covenant": {
395372
"type": 0,
373+
"action": "NONE",
396374
"items": []
397375
},
398-
"path": {
399-
"name": "default",
400-
"account": 0,
401-
"change": true,
402-
"derivation": "m/0'/1/4"
403-
}
376+
"path": null
404377
}
405378
],
406-
"tx": "0000000001758758e600061e62b92831cb40163011e07bd42cac34467f7d34f57c4a921e35000000000241825ebb96f395c02d3cdce7f88594dab343347879dd96af29320bf020f2c5677d4ab7ef79349007d562a4cdafb54d8e1cbd538275deef1b78eb945155315ae648012102deb957b2e4ebb246e1ecb27a4dc7d142504e70a420adb3cf40f9fb5d3928fdf9ffffffff0200e1f505000000000014f0d9374a2ce80c377187f4bc6c68993c561cb13600000084d71700000000001451950e0075aa253507fb8a4a562bb9d67ad88c3d000000000000"
407-
}
379+
"tx": "00000000013e298505af6b7176afedcaa25528e0b118f263a7e0fff2318eb62800dc07497400000000ffffffff0240548900000000000014448387d82b25682ebdae6a6b24036e2e62492f320000d034ac760000000000140f53482804f9c24e3f8140405a6f47b243e44d3f000000000000024156129fcf21f7de6a7e4b62569b050495e1168c7a69f5e8db6dc37c41d216e3ed27842585b94fa353108981671068989a0b742225f3c93bfc4838352a165fefce0121027a7e5e2e8a0447e7e76d27247af1a7c2b2c19fbd3dc77512a8ee96dc3612c453"
380+
},
408381
...
409382
]
410383
```
411-
Get range of wallet transactions by timestamp. Returns array of tx details.
412384

413-
<aside class="notice">
414-
Note that there are other options documented that `getRange` accepts in the options body, `limit` and `reverse`. At the time of writing however they do not have any effect.
415-
</aside>
385+
Get pending (unconfirmed) wallet transactions chronologically (oldest to newest, unless reversed). Returns an array of transaction details.
416386

417387
### HTTP Request
418388

419-
`GET /wallet/:id/tx/range`
420-
421-
### Body Parameters
422-
Parameter | Description
423-
-------- | -------------------------
424-
account <br>_string_ | account to get the tx history from
425-
start <br> _int_ | start time to get range from
426-
end <br> _int_ | end time to get range from
389+
`GET /wallet/:id/tx/unconfirmed`
427390

428-
<!-- ##GET /wallet/:id/tx/last
391+
Parameter | Description
392+
---------------- | -----------
393+
id <br> _string_ | Wallet ID
429394

430-
Get last N wallet transactions.
395+
### Query Parameters
396+
Parameter | Default | Description
397+
--------------------- | -------- | -----------
398+
account <br> _string_ | None | Account name to filter transactions
399+
after <br> _string_ | None | List transactions after this transaction ID (Priority 1)
400+
time <br> _int_ | None | List transactions after this timestamp in epoch seconds (Priority 2)
401+
limit <br> _int_ | `maxTXs`* | Maximum number of transactions to return
402+
reverse <br> _bool_ | `false` | TX Ordering, whether it should reverse the chronological order (oldest to newest)
431403

432-
### HTTP Request
404+
Notes:
433405

434-
`GET /wallet/:id/tx/last` -->
406+
- For unconfirmed transactions, the `time` parameter is based on when the transaction was added to the wallet.
407+
- *`maxTXs` refers to wallet `maxHistoryTXs` configuration
408+
- `limit` can not exceed `maxHistoryTXs` configuration

0 commit comments

Comments
 (0)