unisat-dev-docs

Blockchain API

Blockchain API is a RESTful API for accessing Bitcoin blockchain data. It provides endpoints to retrieve information about blocks, transactions, addresses, and more. The API supports both mainnet and testnet environments.

👉 View Swagger UI


đź“‘ Table of Contents

Route Summary
GET /v1/indexer/blockchain/info Get chain tip, header height, and best block metadata
GET /v1/indexer/fees/recommended Get recommended Bitcoin fee rates by confirmation target
GET /v1/indexer/height/(height)/block Get block metadata by height
GET /v1/indexer/block/id/(blockid) Get block metadata by block hash
GET /v1/indexer/block/(height)/txs List indexed transactions in a block by height
GET /v1/indexer/tx/(txid) Get indexed transaction summary by txid
GET /v1/indexer/tx/(txid)/ins List inputs spent by a transaction
GET /v1/indexer/tx/(txid)/outs List outputs created by a transaction
GET /v1/indexer/rawtx/(txid) Get raw transaction hex by txid
GET /v1/indexer/utxo/(txid)/(index) Get one transaction output by txid and vout
POST /v1/indexer/local_pushtx Broadcast one raw transaction to the selected network
POST /v1/indexer/local_pushtxs Broadcast multiple raw transactions to the selected network
GET /v1/indexer/address/(address)/balance Get address balance split by BTC and inscription UTXOs
GET /v1/indexer/address/(address)/history List indexed transaction history for an address
GET /v1/indexer/address/(address)/utxo-data List UTXOs for an address
GET /v1/indexer/address/(address)/all-utxo-data List all indexed UTXOs for an address
GET /v1/indexer/address/(address)/available-balance Get address balance grouped by available and unavailable UTXOs
GET /v1/indexer/address/(address)/available-utxo-data List available UTXOs for an address
POST /v1/indexer/unavailable-utxo/unlock/prepare Prepare a message for unlocking unavailable UTXOs
POST /v1/indexer/unavailable-utxo/unlock Unlock unavailable UTXOs after wallet authorization
POST /v1/indexer/unavailable-utxo/lock/prepare Prepare a message for locking UTXOs
POST /v1/indexer/unavailable-utxo/lock Lock UTXOs after wallet authorization
POST /v1/indexer/check/utxo/unlock Check whether UTXOs were manually unlocked

Indexer-Blockchain

Get chain tip, header height, and best block metadata

Method: GET
Path: /v1/indexer/blockchain/info
Swagger Link: View in Swagger UI

Description

Returns the indexed blockchain state, including chain name, block and header heights, best and previous block hashes, median time, and accumulated chainwork.

Response (200)

Successful operation

Response (401)

Invalid API Key


Method: GET
Path: /v1/indexer/fees/recommended
Swagger Link: View in Swagger UI

Description

Returns fee-rate estimates for fastest, half-hour, hour, economy, and minimum confirmation targets, together with the update timestamp for freshness checks.

Response (200)

Successful operation

Response (401)

Invalid API Key


Get block metadata by height

Method: GET
Path: /v1/indexer/height/{height}/block
Swagger Link: View in Swagger UI

Description

Returns indexed block details such as hash links, transaction count, satoshi totals, coinbase output, timestamp, bits, and serialized size for the requested height.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Get block metadata by block hash

Method: GET
Path: /v1/indexer/block/id/{blockid}
Swagger Link: View in Swagger UI

Description

Returns the same indexed block model as height lookup, including chain links, transaction count, value totals, timestamp, difficulty bits, and block size.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List indexed transactions in a block by height

Method: GET
Path: /v1/indexer/block/{height}/txs
Swagger Link: View in Swagger UI

Description

Returns paginated transaction summaries for a block, including each transaction’s input/output counts, satoshi totals, locktime, size, block position, confirmations, and timestamp.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Get indexed transaction summary by txid

Method: GET
Path: /v1/indexer/tx/{txid}
Swagger Link: View in Swagger UI

Description

Returns transaction-level metadata such as input/output counts, satoshi totals, locktime, size, witness offset, block hash, confirmations, and timestamp.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List inputs spent by a transaction

Method: GET
Path: /v1/indexer/tx/{txid}/ins
Swagger Link: View in Swagger UI

Description

Returns paginated previous-output records consumed by a transaction, including address, script data, satoshi value, inscription metadata, source txid, vout, and indexed height fields.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List outputs created by a transaction

Method: GET
Path: /v1/indexer/tx/{txid}/outs
Swagger Link: View in Swagger UI

Description

Returns paginated transaction outputs with address, script type and scriptPubKey, satoshi value, inscription metadata, output index, and spend status fields when indexed.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Get raw transaction hex by txid

Method: GET
Path: /v1/indexer/rawtx/{txid}
Swagger Link: View in Swagger UI

Description

Returns the serialized raw transaction hex for decoding, verification, rebroadcast analysis, or offline transaction inspection.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Get one transaction output by txid and vout

Method: GET
Path: /v1/indexer/utxo/{txid}/{index}
Swagger Link: View in Swagger UI

Description

Returns indexed output details including satoshi value, script type, scriptPubKey, address, inscription metadata, RBF marker, and whether the output is spent.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key

Notes

The return result of this UTXO interface will have three scenarios:

  1. When UTXO has not been spent, it will return the information of this UTXO, and isSpent will be set to false.

    image

  2. When UTXO has been spent, but the transaction that spent it has not yet been confirmed, it will return the information of this UTXO, and isSpent will be set to true.

    image

  3. When UTXO has been spent and the transacted spend has been confirmed, it will return null. image

This endpoint was updated on 2025-05-20

BRC20 inscriptions of type TRANSFER (those that have undergone transfers) and MINT inscriptions, which no longer hold value, will no longer be available for query after this update. Before Upgrade:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "txid": "...",
    "vout": 0,
    "satoshi": 546,
    "scriptType": "5120",
    "scriptPk": "...",
    "codeType": 9,
    "address": "...",
    "height": 815539,
    "idx": 2516,
    "isOpInRBF": false,
    "isSpent": false,
    "inscriptionsCount": 2,
    "inscriptions": [
      {
        "inscriptionNumber": 38012882,
        "inscriptionId": "...",
        "offset": 0,
        "moved": false,
        "sequence": 0,
        "isCursed": false,
        "isVindicate": false,
        "isBRC20Ext": false,
        "isBRC20": true
      },
      {
        "inscriptionNumber": 38012883,
        "inscriptionId": "....",
        "offset": 0,
        "moved": false,
        "sequence": 0,
        "isCursed": false,
        "isVindicate": false,
        "isBRC20Ext": false,
        "isBRC20": false
      }
    ]
  }
}

After Upgrade:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "txid": "...",
    "vout": 0,
    "satoshi": 546,
    "scriptType": "5120",
    "scriptPk": "...",
    "codeType": 9,
    "address": "...",
    "height": 815539,
    "idx": 2516,
    "isOpInRBF": false,
    "isSpent": false,
    "inscriptionsCount": 2,
    "inscriptions": [
    {
        "inscriptionNumber": 38012883,
        "inscriptionId": "....",
        "offset": 0,
        "moved": false,
        "sequence": 0,
        "isCursed": false,
        "isVindicate": false,
        "isBRC20Ext": false,
        "isBRC20": false
      }
     ]
  }
}

Migration Guidance:


Broadcast one raw transaction to the selected network

Method: POST
Path: /v1/indexer/local_pushtx
Swagger Link: View in Swagger UI

Description

Submits a signed transaction hex and optional maximum fee rate for local validation and propagation. This can move funds or assets and requires explicit confirmation before execution.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Broadcast multiple raw transactions to the selected network

Method: POST
Path: /v1/indexer/local_pushtxs
Swagger Link: View in Swagger UI

Description

Submits a batch of signed transaction hex strings with optional maximum fee rate. Use only after validating order, dependencies, fees, and target network because each transaction may move funds or assets.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key


Get address balance split by BTC and inscription UTXOs

Method: GET
Path: /v1/indexer/address/{address}/balance
Swagger Link: View in Swagger UI

Description

Returns confirmed and pending satoshi totals plus UTXO counts for the address, separated into overall, plain BTC, and inscription-related balances.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List indexed transaction history for an address

Method: GET
Path: /v1/indexer/address/{address}/history
Swagger Link: View in Swagger UI

Description

Returns paginated transaction summaries involving the address, including transaction size, satoshi totals, block position, confirmations, and timestamp for wallet activity views.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List UTXOs for an address

Method: GET
Path: /v1/indexer/address/{address}/utxo-data
Swagger Link: View in Swagger UI

Description

Returns paginated UTXO records with confirmed, unconfirmed, and unconfirmed-spend totals. Each UTXO includes address, satoshi value, script data, inscriptions, RBF marker, and output coordinates.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List all indexed UTXOs for an address

Method: GET
Path: /v1/indexer/address/{address}/all-utxo-data
Swagger Link: View in Swagger UI

Description

Returns paginated UTXO records and aggregate totals across confirmed, unconfirmed, and unconfirmed-spend states, including inscription and low-fee metadata when indexed.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Get address balance grouped by available and unavailable UTXOs

Method: GET
Path: /v1/indexer/address/{address}/available-balance
Swagger Link: View in Swagger UI

Description

Returns total, available, and unavailable satoshi balances with matching UTXO counts. The optional low-fee flag controls whether UTXOs below 1 sat/vB are included in availability calculations.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


List available UTXOs for an address

Method: GET
Path: /v1/indexer/address/{address}/available-utxo-data
Swagger Link: View in Swagger UI

Description

Returns paginated UTXOs considered available for spending, along with aggregate confirmed, unconfirmed, and unconfirmed-spend totals. The low-fee option controls inclusion of UTXOs below 1 sat/vB.

Parameters

Response (200)

Successful operation

Response (401)

Invalid API Key


Prepare a message for unlocking unavailable UTXOs

Method: POST
Path: /v1/indexer/unavailable-utxo/unlock/prepare
Swagger Link: View in Swagger UI

Description

Available only on Bitcoin Mainnet and Fractal Bitcoin Mainnet. Validates the requested UTXOs against the address’s current lock state and returns the exact message and nonce that the wallet must sign. This step does not change UTXO availability. Unlocking is a high-risk action because protocol-asset UTXOs may subsequently be selected and spent as BTC.

Request Body

Content-Type: application/json (required)

Response (200)

Message prepared, or a validation error returned in the response envelope

Response (401)

Invalid API Key


Unlock unavailable UTXOs after wallet authorization

Method: POST
Path: /v1/indexer/unavailable-utxo/unlock
Swagger Link: View in Swagger UI

Description

Available only on Bitcoin Mainnet and Fractal Bitcoin Mainnet. Verifies the signed prepare message and marks eligible UTXOs as manually unlocked. Unlocked UTXOs may appear in available balance and available UTXO results even when they carry inscriptions or other protocol assets. Spending such UTXOs can transfer or destroy those assets; obtain explicit user confirmation before submitting this request.

Request Body

Content-Type: application/json (required)

Response (200)

Unlock applied, or an error returned in the response envelope

Response (401)

Invalid API Key


Prepare a message for locking UTXOs

Method: POST
Path: /v1/indexer/unavailable-utxo/lock/prepare
Swagger Link: View in Swagger UI

Description

Available only on Bitcoin Mainnet and Fractal Bitcoin Mainnet. Validates the requested UTXOs against the address’s current unlock state and returns the exact message and nonce that the wallet must sign. This step does not change UTXO availability. Use the returned values with the lock execution endpoint.

Request Body

Content-Type: application/json (required)

Response (200)

Message prepared, or a validation error returned in the response envelope

Response (401)

Invalid API Key


Lock UTXOs after wallet authorization

Method: POST
Path: /v1/indexer/unavailable-utxo/lock
Swagger Link: View in Swagger UI

Description

Available only on Bitcoin Mainnet and Fractal Bitcoin Mainnet. Verifies the signed prepare message and restores eligible UTXOs to the protected or unavailable set. Locked UTXOs are excluded from normal available balance and coin-selection results, helping prevent accidental spending of inscriptions and other protocol assets.

Request Body

Content-Type: application/json (required)

Response (200)

Lock applied, or an error returned in the response envelope

Response (401)

Invalid API Key


Check whether UTXOs were manually unlocked

Method: POST
Path: /v1/indexer/check/utxo/unlock
Swagger Link: View in Swagger UI

Description

Available only on Bitcoin Mainnet and Fractal Bitcoin Mainnet. Returns one boolean for each submitted outpoint, in the same order. true means the UTXO is present in the manual unlock history; false means it is not. This endpoint checks manual unlock state only and does not independently prove that a UTXO is unspent or currently spendable.

Request Body

Content-Type: application/json (required)

Response (200)

Successful operation

Response (401)

Invalid API Key