Get UTxO details on BitcoinIn this guide, you will learn to query Bitcoin and extract UTxO information by leveraging the UTxOs by Address endpoint.

​
Prerequisites

Before submitting an API request, ensure you have completed the following:

​
Steps to Submit an API Request

The API allows applications to retrieve a list of all UTxOs that are located at a specific address or controlled by a particular script (script pubkey). In this example, we will use the Bitcoin Testnet as the selected network for our project.

​
1. Select the Network

  • Ensure your project is configured to use Bitcoin Testnet.

​
2. Retrieve Transaction Output

  • Use the following endpoint to get a list of all UTxOs that reside at the specified Bitcoin address or script pubkey:
/addresses/:address/utxos

​
3. Specify Path Parameters

  • Include the required path parameters in your request:
ParameterData TypeDescriptionRequired
addressStringThe Bitcoin address or hex-encoded script pubkey.yes

​
4. Specify Query Parameters (Optional)

  • Include optional query parameters as needed:
ParameterData TypeDescriptionRequired
filter_dustBooleanIgnore UTxOs containing less than 100,000 sats.no
filter_dust_thresholdIntegerIgnore UTxOs containing less than the specified number of satoshis.no
countanyMaximum number of results per page.no
orderanyThe order in which the results are sorted (by height at which UTxO was produced).no
fromint64Return only UTxOs created on or after a specific height.no
toint64Return only UTxOs created on or before a specific height.no
cursorStringPagination cursor string; use the cursor included in a page of results to fetch the next page.no

​
5. Send the API Request

  • Use cURL or your preferred tool to send the API request:
For this example, we will use:
  • address: bc1qh62wlr6cv349jg2ltpfe6dgrjt585gzhlmecdu
  • filter_dust: true
  • order: desc
qfkWFyfdd8WZIxrXZTCgzRqZyphMA0hk 
curl -X GET \
-H "api-key: <your_project_api_key>" \
-H "Accept: application/json" \
"https://xbt-testnet.gomaestro-api.org/v0/addresses/tb1qphcdyah2e4vtpxn56hsz3p6kapg90pl4x525kc/utxos?filter_dust=true&order=desc"

​
6. Review the Response

The API will return a response like the following:
JSON
{
    "data": [{
        "txid": "caff433f77a1458696280be82a9bdb7298260e5d85b81e7a77a762c47bbb89c2",
        "vout": 1,
        "address": "tb1qphcdyah2e4vtpxn56hsz3p6kapg90pl4x525kc",
        "script_pubkey": "00140df0d276eacd58b09a74d5e0288756e8505787f5",
        "satoshis": "9813110",
        "confirmations": 186347,
        "height": 2815507,
        "runes": [],
        "inscriptions": []
    }, {
        "txid": "9e46003cb9ae4906a81b4be663c0b3ea5acb8947857bbc20594e9d76144be6ff",
        "vout": 2,
        "address": "tb1qphcdyah2e4vtpxn56hsz3p6kapg90pl4x525kc",
        "script_pubkey": "00140df0d276eacd58b09a74d5e0288756e8505787f5",
        "satoshis": "980362",
        "confirmations": 186373,
        "height": 2815481,
        "runes": [],
        "inscriptions": []
    }],
    "last_updated": {
        "block_hash": "000000000538766058d37b6ca5e2cd6d313aed48f16da2633eceec75a417e4ea",
        "block_height": 3001854
    },
    "next_cursor": null
}

​
7. Understanding the Response

TermDefinition
txidThe transaction ID where the UTXO was created.
voutThe index of the output in the transaction (txid).
addressThe Bitcoin address that received the UTXO.
script_pubkeyThe script public key associated with the UTXO, usually in hex format.
satoshisThe amount of satoshis (smallest unit of Bitcoin) in the UTXO.
confirmationsThe number of confirmations that the UTXO has received on the blockchain.
heightThe block height at which the UTXO was created.
runesAdditional data related to runes, if any (empty in this response).
inscriptionsAdditional data related to inscriptions, if any (empty in this response).
last_updatedInformation about the last block update related to this request.
block_hashThe hash of the last block where the UTXOs were updated or retrieved.
block_heightThe height of the last block where the UTXOs were updated or retrieved.
next_cursorA cursor for pagination to fetch the next page of results, if applicable (null if no further pages).
Next StepsCongrats! Now that you’ve made your API request, let’s Submit Your First Transaction.