Skip to main content

Getting UTXOs

Return UTXOs and some useful information regarding it.

Multiple filters for UTXOs selection.

Parameters​

Optional Parameters - UTXOs' Filters​

  • max_utxos: Maximum number of UTXOs to return. The default value is 255.
  • token: Token UID to select UTXOs. If not set, only HTR UTXOs will be returned.
  • filter_address: Address to filter UTXOs.
  • amount_smaller_than: Maximum limit of UTXO amount. Only UTXOs having an amount lower than this value will be returned.
  • amount_bigger_than: Minimum limit of UTXO amount. Only UTXOs having an amount bigger than this value will be returned.
  • maximum_amount: Maximum total value of UTXOs considering the sum of all their amounts.
  • only_available_utxos: Select only available UTXOs; locked ones are ignored. The default value is false.
info

All decimal values must follow the integer representation, i.e. 100 = 1.00. This is the case for the amount_smaller_than, amount_bigger_than, and maximum_amount parameters.

Request all UTXOs - no filters​

curl -X GET -H "X-Wallet-Id: default-wallet" \
        http://localhost:8000/wallet/utxo-filter

Response​

{
   "total_amount_available":446,
   "total_utxos_available":4,
   "total_amount_locked":0,
   "total_utxos_locked":0,
   "utxos":[
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":97,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":0
      },
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":100,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":1
      },
      {
         "address":"WQpnzqTugK6woUmWgXEhN3YtR8e4iTQi56",
         "amount":200,
         "tx_id":"0094a48fa955c0a77927616414ff40665b040ec0823a471e35259dfe3b399e75",
         "locked":false,
         "index":1
      },
      {
         "address":"WkGLxUVv8kbpNHf1sNh2amzdyvGcXYSN71",
         "amount":49,
         "tx_id":"005844898b5f1e5f953d1a45ccbb41afc0d200b4e4a3b45d7f177f692b1a6c91",
         "locked":false,
         "index":0
      }
   ]
}

Request a max number of UTXOs from a specific address​

curl -X GET -H "X-Wallet-Id: default-wallet" \
        "http://localhost:8000/wallet/utxo-filter?max_utxos=1&address=WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE"

Response​

Note from the previous response that there are two UTXOs associated with the address WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE. As the max_utxos parameter was set to 1, only one UTXO was retrieved.

{
   "total_amount_available":97,
   "total_utxos_available":1,
   "total_amount_locked":0,
   "total_utxos_locked":0,
   "utxos":[
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":97,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":0
      }
   ]
}

Request UTXOs whose amount is in a range​

curl -X GET -H "X-Wallet-Id: default-wallet" \
        "http://localhost:8000/wallet/utxo-filter?amount_bigger_than=50&amount_smaller_than=150"

Response​

Among the four UTXOs available in the default-wallet, only two of them have amounts within the specified range, i. e., bigger than 50 and smaller than 150. So, these UTXOs are returned.

{
   "total_amount_available":197,
   "total_utxos_available":2,
   "total_amount_locked":0,
   "total_utxos_locked":0,
   "utxos":[
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":97,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":0
      },
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":100,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":1
      }
   ]
}

Request UTXOs whose summed amount is below a threshold​

curl -X GET -H "X-Wallet-Id: default-wallet" \
        http://localhost:8000/wallet/utxo-filter?maximum_amount=150

Response​

The API sums the UTXO amounts up to the threshold value defined by the maximum_amount parameter. All UTXOs that make up this sum are returned.

{
   "total_amount_available":146,
   "total_utxos_available":2,
   "total_amount_locked":0,
   "total_utxos_locked":0,
   "utxos":[
      {
         "address":"WTj91s6cWrA6Fu2NRP7ZugzoZNN75PDPsE",
         "amount":97,
         "tx_id":"00a72f9e3e2d23a831f3dfb26a2480364ee78111f9b2a9722806e32268b8e545",
         "locked":false,
         "index":0
      },
      {
         "address":"WkGLxUVv8kbpNHf1sNh2amzdyvGcXYSN71",
         "amount":49,
         "tx_id":"005844898b5f1e5f953d1a45ccbb41afc0d200b4e4a3b45d7f177f692b1a6c91",
         "locked":false,
         "index":0
      }
   ]
}