📈 Get Bitcoin block by height

Code samples

GET /api/v1/btc/block/{blockNumber}

curl 'https://settla.net/api/v1/btc/block/965000' \
  -H 'X-API-Key: $SETTLA_API_KEY' \
  -H 'Accept: application/json'

Returns a specific block by its height using getblockhash followed by getblock with verbosity 2. As with /block/last, the full transaction list comes with it — expect megabytes. "Not found" is reported as 500. The handler collapses every node- level failure into the same Could not connect to BTC node. message, so a height above the tip is indistinguishable from an actual outage. Check the tip via GET /api/v1/btc/health before treating a 500 here as an incident. Only a negative height is caught early and answered 400.

🛠️ Parameters

Name	In	Type	Required	Description
blockNumber	path	integer(int64)	true	Block height in the best chain (non-negative integer).

Example responses

200 Response

{
  "hash": "00000000000000000001595977e6000ce56129f5c9b4073e31ccc30b90b97da9",
  "confirmations": 136,
  "height": 965000,
  "version": 537018368,
  "versionHex": "20024000",
  "merkleroot": "9e18369e2535ca62ec5731188be8a537fa3751f3ba832aa5c3c74bca6f48f79d",
  "time": 1788244455,
  "mediantime": 1788243415,
  "nonce": 2991619710,
  "bits": "17023cc1",
  "target": "000000000000000000023cc10000000000000000000000000000000000000000",
  "difficulty": 125807076547197.5,
  "chainwork": "000000000000000000000000000000000000000143ea54c80d80b7599543d17f",
  "nTx": 216,
  "previousblockhash": "0000000000000000000060ec48e65af7e6a5c521ed026b6053b3f59841a4deeb",
  "nextblockhash": "000000000000000000015aaf7bd406c54e2f09b97941e8ed7fc41a48a26f52a1",
  "strippedsize": 56071,
  "size": 105590,
  "weight": 273803,
  "tx": [
    "… 216 full transaction objects, omitted here — see the transaction schema below"
  ]
}

400 Response

{
  "error": "Block number must be non-negative"
}

500 Response

{
  "error": "Could not connect to BTC node."
}

🔁 Responses

Status	Meaning	Description	Schema
200	OK	Bitcoin block	Inline
400	Bad Request	Invalid block number (negative)	Inline
500	Internal Server Error	Could not connect to BTC node	Inline

🔄 Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» hash	string	false	none	Hash of the block.
» confirmations	integer(int64)	false	none	Depth below the node's current tip. `-1` if the block was reorged out.
» height	integer(int64)	false	none	Block height.
» version	integer	false	none	Block version.
» versionHex	string	false	none	none
» merkleroot	string	false	none	Merkle root of the block's transactions.
» time	integer(int64)	false	none	Block time in seconds since the Unix epoch — unlike Tron, which uses milliseconds. Set by the miner and only loosely monotonic; use `mediantime` if you need a value that never goes backwards.
» mediantime	integer(int64)	false	none	Median time of the preceding 11 blocks. Monotonically increasing.
» nonce	integer(int64)	false	none	none
» bits	string	false	none	Compact encoding of the target.
» target	string	false	none	Full 256-bit target as hex. Added in Bitcoin Core v28 — absent on older nodes, so treat it as optional.
» difficulty	number(double)	false	none	Difficulty as a JSON float. Already past 2^53 in absolute terms is not a problem here, but the fractional part (`…197.5`) means naive integer parsing will fail.
» chainwork	string	false	none	none
» nTx	integer(int64)	false	none	Number of transactions in the block, coinbase included. Same value the `/transactions/count` endpoints return.
» strippedsize	integer(int64)	false	none	Block size in bytes excluding witness data.
» size	integer(int64)	false	none	Block size in bytes including witness data.
» weight	integer(int64)	false	none	none
» previousblockhash	string¦null	false	none	Absent on the genesis block.
» nextblockhash	string¦null	false	none	Absent while this block is the tip. Its appearance is what tells you a block has been built on top.
» tx	[object]	false	none	Full transaction objects — verbosity is fixed at 2, so you never get a bare array of txids here. Element 0 is always the coinbase, recognisable by its single `vin` carrying `coinbase` instead of `txid`/`vout`.
»» txid	string	false	none	Transaction ID — the hash without witness data. This is the identifier to use everywhere: in explorers, in `GET /transactions/{hash}`, as the value returned by `send-raw`.
»» hash	string	false	none	Witness hash (wtxid). Differs from `txid` for any segwit transaction — do not use it as a lookup key, `getrawtransaction` will not find it.
»» version	integer	false	none	none
»» size	integer	false	none	Serialised size in bytes, witness included.
»» vsize	integer	false	none	Virtual size — this is what fee rates (sat/vB) are computed against.
»» weight	integer	false	none	none
»» locktime	integer	false	none	none
»» blockhash	string¦null	false	none	Absent while the transaction is unconfirmed.
»» confirmations	integer(int64)¦null	false	none	Absent while unconfirmed. Grows with every new block, so two calls a few minutes apart return different values for the same transaction.
»» time	integer(int64)¦null	false	none	Same value as `blocktime` for a confirmed transaction. Seconds.
»» blocktime	integer(int64)¦null	false	none	none
»» hex	string	false	none	Full raw transaction. Feed it to `decoderawtransaction` through the JSON-RPC proxy if you want to re-parse it yourself.
»» vin	[object]	false	none	none
»»» txid	string¦null	false	none	Previous transaction being spent. Absent on a coinbase input.
»»» vout	integer¦null	false	none	Index of the output being spent in `txid`. Absent on a coinbase input.
»»» coinbase	string¦null	false	none	Arbitrary miner data — height, pool tag, extranonce. Present only on the coinbase input.
»»» scriptSig	object¦null	false	none	Empty for segwit inputs — see the note above.
»»»» asm	string	false	none	none
»»»» hex	string	false	none	none
»»» txinwitness	[string]	false	none	Witness stack, hex-encoded. Present only on segwit inputs. The last item of a P2WSH stack is the redeem script; the example transaction is a 2-of-2 multisig, hence the leading empty item (Bitcoin's OP_CHECKMULTISIG off-by-one) followed by two signatures and the script.
»»» sequence	integer(int64)	false	none	`4294967295` (`0xffffffff`) means locktime and RBF are both disabled for this input. Any value below `0xfffffffe` opts the transaction into replace-by-fee.
»» vout	[object]	false	none	none
»»» value	number(double)	false	none	Amount in BTC, as a JSON number — not satoshis, not a string. This is the single most common integration bug on this API: `0.012` cannot be represented exactly in IEEE-754, and small outputs come back in exponential notation (a real dust output in block 965000 serialises as `5.46e-06`). Parse it with a decimal type, or multiply by 1e8 and round to get satoshis — never compare two values with `==` and never accumulate them as floats.
»»» n	integer	false	none	Output index within the transaction.
»»» scriptPubKey	object	false	none	The locking script. Bitcoin Core v30 — which this node runs — removed `reqSigs` and `addresses`. Integrations written against older docs that read `scriptPubKey.addresses[0]` will silently see `undefined` here; read the singular `address` instead.
»»»» asm	string	false	none	Human-readable disassembly of the script.
»»»» desc	string	false	none	Output descriptor with its checksum.
»»»» hex	string	false	none	none
»»»» address	string	false	none	Destination address. Absent for outputs that have no address form — `nulldata` (OP_RETURN) and non-standard scripts. Always check that the field exists before reading it.
»»»» type	string	false	none	Script type: `pubkeyhash`, `scripthash`, `witness_v0_keyhash`, `witness_v0_scripthash`, `witness_v1_taproot`, `nulldata`, `nonstandard`.

Status Code 400

Name	Type	Required	Restrictions	Description
» error	string	false	none	Human-readable reason.

Status Code 500

Name	Type	Required	Restrictions	Description
» error	string	false	none	Human-readable reason.