# Change structure

With our API, you can schedule a child transaction that spends from a pending transaction whose fee we manage (explained in child requests tutorial). To make this task easier, it's good to know how you can retrieve information about pending change and how it is structured. This article explains with some examples of how this information is structured.

# Theoretical example

The following diagram shows a hypothetical wallet and its UTXOs (blue) that all have a value of 10 mBTC. This wallet is attempting to send bitcoin to five addresses; the amounts being 1,2,3,4 and 5 mBTC. In each attempt to send bitcoin, the wallet relayed several pre-signed transactions (PSTs) to Bitpost, creating a fee adjustment request.

diagram

All the relayed PSTs have a simple structure: they spend from one confirmed UTXO (except for those of the request to send 5 mBTC) and produce two outputs - the amount to be sent (red) and the change (green) with the transaction fee discounted into it. We could have had five changes, one from each request, but due to spending of the 2-mBTC request's change by the 1-mBTC request and the spending of the 4-mBTC request's change by the 5-mBTC request, we only have three changes.

# /utxos answer

[
  {
    "used": [{ "txid": "A", "vout": 0 }],
    "groupsize": 2,
    "change": [
      {
        "broadcasts": 12,
        "target": 1594052727,
        "id": "Kh7dyJan",
        "minamount": 0.005,
        "utxos": [
          [{ "txid": "...", "vout": 1, "scriptPubKey": "...", "amount": 0.0068}] // ...
        ]
      }
    ]
  },
  {
    "used": [{ "txid": "B", "vout": 0 }],
    "groupsize": 1,
    "change": [
      {
        "broadcasts": 0,
        "target": 1594052900,
        "id": "js918UqW",
        "minamount": 0.006,
        "utxos": [
          [{ "txid": "...", "vout": 1, "scriptPubKey": "..." , "amount": 0.0069}] // ...
        ]
      }
    ]
  },
  {
    "used": [
      { "txid": "C", "vout": 0 },
      { "txid": "D", "vout": 0 }
    ],
    "groupsize": 2,
    "change": [
      {
        "broadcasts": 1,
        "target": 1594063799,
        "id": "1b0Zndrt",
        "minamount": 0.009,
        "utxos": [
          [{ "txid": "...", "vout": 1, "scriptPubKey": "...",, "amount": 0.0108 }] // ...
        ]
      }
    ]
  }
]
  • used: if you scheduled or allowed PSTs to be first broadcasted in the future, this field tells you what UTXOs you shouldn't spend because they are already scheduled to be spent. You should lock them out of the coin selection or risk getting a double-spend error. If you want to use them somewhere else instead, cancel the request(s) in the group with curl -X DELETE /request?id=***.
  • groupsize: the size of each request group. In this example, the groups are made of the following requests: (2 mBTC, 1 mBTC), (3 mBTC) and (4 mBTC, 5 mBTC). As a general rule, the larger the group is, the higher the number of PSTs in its child request(s) and therefore the more it should be avoided because child requests will consume more bandwidth - go here for some bandwidth considerations.
  • broadcasts: the number of broadcasts that have occurred in the request in question. If you wish to spend this request's change, you should create a child PST for every previous broadcast as a fallback if an old broadcast is mined. The length of utxos will be no smaller than broadcasts for this reason. If the number of broadcasts is too high, and there is an alternative to spend this change, it might be better to avoid this request to prevent high bandwidth consumption.
  • minamount: The amount of the change varies, because it will depend on the actual fee of the mined transactions. Because we don't know which transactions will be mined yet, any spending of change should account for the worst scenario. The minimum amount for each change will be given in this field.
  • target: if you make a high-priority child request of a low-priority parent request, you are effectively increasing the priority of the parent request. Because you might want to avoid the mentioned scenario or group together requests with the same priority, this field is present.

# Complete example

This data was obtained with the option showrawtx=true and showunknownchange=true, which shows more data. The option filter=false will simply show less entries in the response['data'][.]['change']['utxos'] array.

[
  {
    "change": [
      {
        "broadcasts": 0,
        "utxos": [
          [
            {
              "scriptPubKey": "0014ef07b48807d2e38f634c61b5fa69c7a848610676",
              "amount": 0.00351914,
              "rawtx": "0200000000010145730cadc170494ed03ef6da58b0f9bc3d5e50de1f0008755fcce566597cc60e0100000000fdffffff02360200000000000017a914a30dc487169fa6fc72ce89a5d943ee6d5527e60b87aa5e050000000000160014ef07b48807d2e38f634c61b5fa69c7a8486106760247304402204b9755ff2d6e7f5565591538840e089d9bbc3d7e81b373774ecee4eba7ce66f902200ffa6903d16357fd0acbbd369f0ee0864907b4aba8c61db6e6a21d22062eceb20121027e1563a0bbdeb1229203672707a061b61b6de109d1e7a06f45bbd258537a4bf700000000",
              "txid": "29b884ca1a021cbc070ab6438dece30cdfb3f01f1707fc44a331c9358a4ee171",
              "vout": 1
            }
          ],
          [
            {
              "scriptPubKey": "0014ef07b48807d2e38f634c61b5fa69c7a848610676",
              "amount": 0.00364572,
              "rawtx": "0200000000010145730cadc170494ed03ef6da58b0f9bc3d5e50de1f0008755fcce566597cc60e0100000000fdffffff02360200000000000017a914a30dc487169fa6fc72ce89a5d943ee6d5527e60b871c90050000000000160014ef07b48807d2e38f634c61b5fa69c7a84861067602473044022056fd84854bef179c2233161f95ece3f49a16885c3201399e412e17a74f6339ca022035fc33fce0d7cd2ee6cbe70845fea5c8c7821b92fee1da2f4f598f08c5d9cd9b0121027e1563a0bbdeb1229203672707a061b61b6de109d1e7a06f45bbd258537a4bf700000000",
              "txid": "af32193e29794cb6476497a95c97998aa2a96430bb41c5bd50f9d12869560b5f",
              "vout": 1
            }
          ],
          [
            {
              "scriptPubKey": "0014ef07b48807d2e38f634c61b5fa69c7a848610676",
              "amount": 0.00354446,
              "rawtx": "0200000000010145730cadc170494ed03ef6da58b0f9bc3d5e50de1f0008755fcce566597cc60e0100000000fdffffff02360200000000000017a914a30dc487169fa6fc72ce89a5d943ee6d5527e60b878e68050000000000160014ef07b48807d2e38f634c61b5fa69c7a84861067602473044022035178b7b94a6812de745cab763445c625097d63bb183d43e8f124ae96c635eb702205f46e82dcf65fbe95d517f62bcc04826ab2b3d7bb965d6f0fb7facd2dbb1ff3e0121027e1563a0bbdeb1229203672707a061b61b6de109d1e7a06f45bbd258537a4bf700000000",
              "txid": "34ccb39bf75d894b98205d681230d6ed5e51476afef1c2037164f0cdcd8d6fc4",
              "vout": 1
            }
          ],
          [
            {
              "scriptPubKey": "0014ef07b48807d2e38f634c61b5fa69c7a848610676",
              "amount": 0.00374699,
              "rawtx": "0200000000010145730cadc170494ed03ef6da58b0f9bc3d5e50de1f0008755fcce566597cc60e0100000000fdffffff02360200000000000017a914a30dc487169fa6fc72ce89a5d943ee6d5527e60b87abb7050000000000160014ef07b48807d2e38f634c61b5fa69c7a8486106760247304402206a12c9e6e5e441410b021b579b21a575eef63859aba44a3d5a27581a244cd85e02202ebf536ab396d5a2ed21ba05a757176368fc18ce749f7e05920adcba0246e2eb0121027e1563a0bbdeb1229203672707a061b61b6de109d1e7a06f45bbd258537a4bf700000000",
              "txid": "b8ea3d721513da9ce3ee341e9e2aae3a6325e4e649a0c002268935d46246f249",
              "vout": 1
            }
          ]
        ],
        "id": "R9RJJBLz8Kd",
        "minamount": 0.00351914,
        "target": 1595018880
      }
    ],
    "groupsize": 1,
    "used": [
      {
        "txid": "0ec67c5966e5cc5f7508001fde505e3dbcf9b058daf63ed04e4970c1ad0c7345",
        "vout": 1
      }
    ],
    "verification": {}
  }
]

← Verifying change →