Guides
SupportStatusSign UpLogin

Bitcoin - Getting Started (REST API)

Suggest Edits

This article covers the steps required to create a Bitcoin wallet, generate Addresses, Private Keys, and make transfers. It also includes an example of checking your address balance and transferring funds to another Bitcoin address.

📘

The following steps and examples are based on Bitcoin (Testnet).

Steps

Step_1: Generate a Mnemonic

Generating a mnemonic means creating a 24-word phrase that will be the foundation for your wallet. This phrase is like a master key from which all your wallet addresses and their private keys can be generated.

  • Tatum does not store Mnemonics and or Private Keys.
  • The responsibility of keeping your Mnemonics and Private Keys secure rests solely with you, the User.
  • Additional information about Mnemonics and Private Keys is available in the following article.

Example request:

  • The response returns a Mnemonic and a Bitcoin XPUB
curl --location 'https://api.tatum.io/v3/bitcoin/wallet' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
  "mnemonic": "pull leader deputy custom invest hat panel behind reward fancy tribe valley elite wish mistake letter bounce sing anchor electric #### #### #### ####",
  "xpub": "tpubDFRDRgtnYJcXdhC4eE1HktF86nLwLodEopxvmAePWyZPXR6zGnu5XtQ2S4TBjHgF6rPnxGdJ8MinjYKAGqoumF4L9TL8wMJJoAGW1XR####"
}

📘

Be mindful of Tatum's Derivation Path.

Step_2: Generate a Bitcoin Private Key from mnemonic and index

Request example:

  • The response returns a Bitcoin Private Key based on index 1
curl --location 'https://api.tatum.io/v3/bitcoin/wallet/priv' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "index": 1,
  "mnemonic": "pull leader deputy custom invest hat panel behind reward fancy tribe valley elite wish mistake letter bounce sing anchor electric #### #### #### ####"
}'

//response:
{
    "key": "####"
}

Step_3: Generate a Bitcoin address from XPUB and index

Request example:

  • The response returns a Bitcoin public address based on index 1
curl --location 'https://api.tatum.io/v3/bitcoin/address/tpubDFRDRgtnYJcXdhC4eE1HktF86nLwLodEopxvmAePWyZPXR6zGnu5XtQ2S4TBjHgF6rPnxGdJ8MinjYKAGqoumF4L9TL8wMJJoAGW1XR####/1' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
  "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}

Step_4: Add funds to the Bitcoin address

  • We take the address generated in step_3.
  • For testnet, you can get free coins from a faucet.
{
  "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}

Step_5: Check the balance of a Bitcoin address

Request example:

  • Following the address from the example.
  • The response returns the balance of the address, based on UTXOs
curl --location 'https://api.tatum.io/v3/bitcoin/address/balance/tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma' \
--header 'x-api-key: {YOUR_API_KEY}'

//response:
{
    "incoming": "0.00828",
    "outgoing": "0",
    "incomingPending": "0.00008",
    "outgoingPending": "0"
}

Step_6: Get unspent UTXOs from a Bitcoin address

It's strongly recommended that you validate which UTXOs you may want to build your transactions from.

🚧

For rapid transaction firing from the same address (less than 25 seconds per broadcast attempt) it's recommended that you confirm the UTXOs were not spent already via the following v3 REST API endpoint.

Request example:

  • Address: tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma (this is the address from which we get the unspent UTXOs)
  • Amount: 0.00042 btc. This is the amount we want to send to another blockchain address "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf"
  • The response returns an array of UTXOs you can use to build a transaction
curl --location 'https://api.tatum.io/v4/data/utxos?chain=bitcoin-testnet&address=tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma&totalValue=0.002' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
[
    {
        "txHash": "b041ef2fa3f39a095784ca0e37d2ee9c6fe08c1026702bebd57eadd3cfc88c5e",
        "index": 0,
        "value": 0.0001,
        "valueAsString": "0.0001",
        "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma",
        "chain": "bitcoin-testnet"
    },
    {
        "txHash": "71c8c90c87e6e268741b4989c497adbccb1a24c405603fdf396dbba503252304",
        "index": 0,
        "value": 0.0001,
        "valueAsString": "0.0001",
        "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma",
        "chain": "bitcoin-testnet"
    },
    {
        "txHash": "8159a453cb2914479b2ae8bf13d9109798581301194ccf69b51fae2814580c3b",
        "index": 0,
        "value": 0.008,
        "valueAsString": "0.008",
        "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma",
        "chain": "bitcoin-testnet"
    }
]

Step_7: Estimate the fees of a Bitcoin transaction

Find additional information about Bitcoin and Fee Estimate in the following article.

Request example:

  • The response returns an estimated fee based on the current price and the transaction size.
curl --location 'https://api.tatum.io/v3/blockchain/estimate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "chain": "BTC",
  "type": "TRANSFER",
  "fromUTXO": [
    {
      "txHash": "b041ef2fa3f39a095784ca0e37d2ee9c6fe08c1026702bebd57eadd3cfc88c5e",
      "index": 0
    },
    {
      "txHash": "71c8c90c87e6e268741b4989c497adbccb1a24c405603fdf396dbba503252304",
      "index": 0
    },
    {
      "txHash": "8159a453cb2914479b2ae8bf13d9109798581301194ccf69b51fae2814580c3b",
      "index": 0
    }
  ],
  "to": [
    {
      "address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf",
      "value": 0.00042
    }
  ]
}'
//Response:
{
    "slow": "0.00003145",
    "medium": "0.00005529",
    "fast": "0.00006645"
}

Step_8: Sign and broadcast a Bitcoin transaction

Request example variant_1:

  • We are explicitly specifying the "fee" and a "changeAddress" (where the rest of the coin from the x3 UTXOs will go to)
  • The response returns a transaction hash
curl --location 'https://api.tatum.io/v3/bitcoin/transaction' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "fromUTXO": [
    {
      "txHash": "b041ef2fa3f39a095784ca0e37d2ee9c6fe08c1026702bebd57eadd3cfc88c5e",
      "index": 0,
      "privateKey": "####"
    },
    {
      "txHash": "71c8c90c87e6e268741b4989c497adbccb1a24c405603fdf396dbba503252304",
      "index": 0,
      "privateKey": "####"
    },
     {
      "txHash": "8159a453cb2914479b2ae8bf13d9109798581301194ccf69b51fae2814580c3b",
      "index": 0,
      "privateKey": "####"
    }
  ],
  "to": [
    {
      "value": 0.00042,
      "address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf"
    }
  ],
    "fee": "0.0009945", //Congested testnet required a much higher fee
    "changeAddress": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
}'

//response:
{
    "txId": "63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395"
}

Request example variant_2:

  • We ensure we have x2 to addresses with explicit amounts:
    • Where we want to send some coin as the "receiver"
    • Where we want to send the rest of the coin

📘

You need to deduce the fee for the miners (implicit).

curl --location 'https://api.tatum.io/v3/bitcoin/transaction' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {YOUR_API_KEY}' \
--data '{
  "fromUTXO": [
    {
      "txHash": "63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395",
      "index": 1,
      "privateKey": "####"
    }
  ],
  "to": [
    {
      "value": 0.0001,
      "address": "tb1qguyupqrsd36c0fta99rf6prxe2lfr73ahxkvpf"
    },
    {
      "value": 0.0065,
      "address": "tb1q7hec37mcmfk6hmqn67echzdf8zwg5n5pqnfzma"
    }
  ]
}'
//Response:
{
    "txId": "5ac36c6b327170f6c6975e8469d77f9bc417b503ee20f255ab8a9c1dd68d7c41"
}

Step_9: Get the details of a Bitcoin transaction

Request example:

  • The response returns the details of a Bitcoin transaction hash
curl --location 'https://api.tatum.io/v3/bitcoin/transaction/63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395' \
--header 'x-api-key: {YOUR_API_KEY}'
//Response:
{
    "blockNumber": 2821966, 
    "fee": 99450,
    "hash": "63b02f60968800202ee211ac14520e51b4b2e25335cf0523fee38beb1b154395",
    "hex": "020000000001035e8cc8cfd3ad7ed5eb2b7026108ce06f9ceed2370eca8457099af3a32...

📘

For unconfirmed transactions (in mempool), an error may be returned. If a response is returned, they will have no block.

Good to Know

  • You can find the official guide on how to build a RAW BTC Transaction in the following article.
  • If your transaction has low fees, it may get stuck in the mempool for two (2) weeks. To speed it up, you may use Child Pays for Parent - Replace By Fee is unavailable for transactions broadcasted via core API.
  • Fee Estimates may fluctuate one way or the other, within seconds.
    • Tatum Mainnet Fee Estimates are generally in line with other providers.
    • The Testnet Fee Estimate is generally unreliable. Since testnet coins have "no value", users tend to set random amounts greatly skewing the estimates.
  • Be mindful of Tatum's derivation path. Find additional information in the following article.
  • Familiarize yourself with the Safety & Security Basics in the following article.

Updated about 2 months ago