Web API: BTC

The BTC API of the VerifiedX explorer provides Bitcoin address information and vBTC (Verified Bitcoin) vault data.

Base URL

/api/btc/

Endpoints

Get Bitcoin Address Information

GET /api/btc/address/{address}/

Returns Bitcoin address balance, transactions, and UTXOs.

Parameters:

• address (string): The Bitcoin address
• offset (query parameter): Pagination offset (default: 0)

Response:

{
  "balance": {
    "confirmed": 50000000,
    "unconfirmed": 0,
    "total": 50000000
  },
  "transactions": {
    "total": 25,
    "results": [
      {
        "txid": "abc123...",
        "confirmations": 6,
        "time": 1640995200,
        "inputs": [...],
        "outputs": [...]
      }
    ]
  },
  "utxos": {
    "total": 3,
    "results": [
      {
        "txid": "def456...",
        "vout": 0,
        "value": 25000000,
        "confirmations": 10
      }
    ]
  }
}

List All VBTC Tokens

GET /api/btc/vbtc/

Returns a list of all VBTC tokens in the system.

Response:

{
  "count": 100,
  "results": [
    {
      "id": 1,
      "smart_contract_uid": "SC123...",
      "vfx_address": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
      "btc_amount": "0.001",
      "status": "active",
      "created_at": "2024-01-01T12:00:00Z"
    }
  ]
}

Get VBTC Tokens by VFX Address

GET /api/btc/vbtc/{vfx_address}/

Returns VBTC tokens associated with a specific VFX address.

Parameters:

• vfx_address (string): The VFX blockchain address

Response:

{
  "count": 5,
  "results": [
    {
      "id": 1,
      "smart_contract_uid": "SC123...",
      "vfx_address": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
      "btc_amount": "0.001",
      "btc_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "status": "active",
      "transfers": [
        {
          "from_address": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
          "to_address": "RNiQrW3aBUWZhfadqKxPuN46iGaR13ox7P",
          "amount": "0.0005",
          "timestamp": "2024-01-01T12:00:00Z"
        }
      ]
    }
  ]
}

Get VBTC Token Details

GET /api/btc/vbtc/detail/{sc_identifier}/

Returns detailed information for a specific VBTC token.

Parameters:

• sc_identifier (string): The smart contract identifier

Response:

{
  "id": 1,
  "smart_contract_uid": "SC123...",
  "vfx_address": "R9Ng1rDS2YgB7R2bJMU3RKzVXSriXLRsBR",
  "btc_amount": "0.001",
  "btc_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "status": "active",
  "metadata": {
    "name": "VBTC Token #1",
    "description": "VFX Bitcoin Token",
    "image": "data:image/png;base64,..."
  },
  "transfers": [],
  "created_at": "2024-01-01T12:00:00Z"
}

Get VBTC Compile Data

GET /api/btc/vbtc-compile-data/{address}/

Returns compilation data for VBTC token creation by address.

Parameters:

• address (string): The VFX address

Response:

{
  "success": true,
  "compile_data": {
    "smart_contract_code": "...",
    "constructor_args": "...",
    "compilation_artifacts": "..."
  }
}

Get Default VBTC Image Data

GET /api/btc/vbtc-image-data/

Returns the default base64 image data for VBTC tokens.

Response:

{
  "image_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

vBTC V2

The /api/btc/vbtc/ routes above list V1 vBTC tokens, which were retired at block 7,400,500 on mainnet. vBTC V2 vaults are under /api/btc/vbtc-v2/. The explorer indexes them from the chain; for a withdrawal’s live state, read the node (see below).

Note

These routes and fields are served by the testnet explorer now and by the mainnet explorer from the 9.0 release.

Attestation heights

GET /api/btc/vbtc-v2/heights/

{ "record_height": 400, "enforcement_height": 401, "latest_block_height": 4217 }

From record_height a new vault is watched; from enforcement_height older vaults are frozen. A height is null while Core has not set it.

List vaults

GET /api/btc/vbtc-v2/
GET /api/btc/vbtc-v2/{vfx_address}/

All vaults, or those an address owns or has sent or received vBTC on, as {"results": [...]}.

Vault details

GET /api/btc/vbtc-v2/detail/{sc_identifier}/

{
  "sc_identifier": "<contract UID>",
  "name": "Treasury vault",
  "description": "",
  "owner_address": "<owner>",
  "pending_owner_address": null,
  "is_watched": true,
  "image_url": "…",
  "deposit_address": "bc1p…",
  "frost_group_public_key": "03…",
  "required_threshold": 51,
  "proof_block_height": 2839,
  "global_balance": "0.0001",
  "total_received": "…",
  "total_sent": "…",
  "tx_count": 1,
  "is_pending_withdrawal": false,
  "addresses": { "<owner>": "0.00007", "<holder>": "0.00003" },
  "available_balances": { "<owner>": "0.00007", "<holder>": "0.00003" },
  "nft": { "…": "…" },
  "withdrawal_requests": [ ],
  "created_at": "2026-10-23T13:01:20Z"
}

• is_watched: the vault was created from the recording height, and the chain records its Bitcoin. A watched vault’s backing is global_balance, read from the chain; total_received and total_sent come from Bitcoin providers and are kept up to date only for vaults the chain does not watch.
• addresses is each address’s gross vBTC on the vault; available_balances nets out its open withdrawals and is what a wallet should size sends from.
• pending_owner_address: a reserve owner’s ownership transfer that takes effect at its unlock.

Transfers and withdrawals of a vault

GET /api/btc/vbtc-v2/transfers/{sc_identifier}/
GET /api/btc/vbtc-v2/withdrawals/{sc_identifier}/

A withdrawal row (one per vault share of a request):

{
  "requestor_address": "<requester>",
  "btc_address": "bc1q…",
  "amount": "0.00002",
  "fee_rate": 3,
  "btc_transaction_hash": "c314d462…",
  "status": "completed",
  "request_transaction_hash": "<request hash>",
  "completion_transaction_hash": null,
  "pin_state": null,
  "pin_txid": null,
  "pin_fee_rate": null,
  "releasing": null,
  "expires_at_height": null,
  "closed_because": null,
  "refunded_amount": null
}

• status is requested, pending_btc, completed, cancellation_requested or cancelled. A watched vault’s withdrawal goes from requested to completed (paid, with the paying btc_transaction_hash) or cancelled.
• closed_because says why a cancelled row closed without payment: Cancelled, Released, Expired or Void. refunded_amount is set when less than the amount came back (a release keeps its Bitcoin fee).
• While a watched vault’s withdrawal is open, pin_state is Waiting or Pinned, with the newest pin’s pin_txid and pin_fee_rate, releasing, and expires_at_height while it waits.

Follow open withdrawals through the node

The node reports a withdrawal’s pin in the block that mines the request. The explorer reads it later, after a following Bitcoin report, so pin_state and pin_txid can be empty while a withdrawal is already pinned. Integrators should follow open withdrawals with the node’s GetWithdrawalPin and GetWithdrawalRequestShares routes (vBTC).

The /api/btc/vbtc-v2/…/prepare/ and …/send/ routes forward raw builds and signed submissions to a node’s vbtcapi/VBTC raw routes. They take snake-case fields (for a withdrawal request sc_identifier, requestor_address, btc_address, amount, fee_rate; for a send hash, signature, public_key) and answer with the node’s answer and success, or with success: false, message and the node’s answer under raw. The steps and checks are those of vBTC Raw Integration.

A multi-vault withdrawal is built with POST /api/btc/vbtc-v2/withdraw/multi/prepare/, which forwards to the node’s GetRawRequestWithdrawalMultiTxData. It takes requestor_address, btc_address, total_amount, fee_rate and inputs, one {"sc_identifier", "amount"} per vault (at most 10, summing to total_amount). The node checks every share against the vault, the per-share fee floor and the destination before answering with the hash to sign. The signed hash goes through withdraw/request/send/, like a single-vault request. A refusal answers HTTP 500 with the node’s message, and a missing field HTTP 400.

The explorer has no route for a fee raise or release; send those to a node.

Field Descriptions

Bitcoin Address Data

• balance.confirmed: Confirmed Bitcoin balance in satoshis
• balance.unconfirmed: Unconfirmed Bitcoin balance in satoshis
• balance.total: Total Bitcoin balance (confirmed + unconfirmed)

VBTC Token Data

• smart_contract_uid: Unique identifier for the VBTC smart contract
• vfx_address: Associated VFX blockchain address
• btc_amount: Bitcoin amount represented by this token (in BTC)
• btc_address: Original Bitcoin address used to create the token
• status: Token status (active, burned, etc.)
• transfers: Array of transfer records for this token

Notes

• vBTC is Bitcoin held one to one in vaults whose keys are split among VerifiedX validators
• Bitcoin amounts are typically represented as strings to preserve precision
• UTXOs (Unspent Transaction Outputs) are used for Bitcoin transaction construction
• All endpoints support caching for improved performance
• Bitcoin address validation follows standard Bitcoin address formats