API Documentation

Everything you need to integrate the BTC Address Checker API.

Overview

Base URL

https://btcaddresschecker.com/api/v1

Authentication

All requests require an API key passed via the x-api-key header. You can generate an API key from your Dashboard.

Rate Limits

Up to 120 requests per minute per API key — exceeding this returns a 429. Each request may include a maximum of 500 addresses, and each address check consumes 1 credit from your balance. Paid users who need a higher limit can request one at support@btcaddresschecker.com.

Request / Response Format

All requests and responses use JSON. Set Content-Type: application/json on all requests.

Known Limitations

For the Bitcoin genesis address (1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa), the original 50 BTC block-0 coinbase reward is permanently unspendable and was never added to the UTXO set, so it is excluded from the balance we (and every explorer) report. The reported balance reflects only the normal, spendable UTXOs the address has since received. See the FAQ for more edge cases and address-format questions.

Endpoint Reference

POST/api/v1/balance/check

Request Headers

Header	Value	Required
`Content-Type`	application/json	Yes
`x-api-key`	Your API key	Yes

Request Body

Field	Type	Description
`addresses`	string[]	Array of BTC addresses (max 500)

json

{
  "addresses": [
    "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
    "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
    "1LVYbnSX6f6vE2Zn4zs2oZ4eKyBgzkqaay"
  ]
}

Success Response 200

Field	Type	Description
`results`	object[]	Array of balance results
`.address`	string	The queried BTC address
`.confirmed`	number	Confirmed balance in satoshis
`.unconfirmed`	number	Unconfirmed balance in satoshis
`creditsUsed`	number	Credits consumed by this request
`creditsRemaining`	number	Your remaining credit balance

json

{
  "results": [
    {
      "address": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
      "confirmed": 24859758242645,
      "unconfirmed": 0
    },
    {
      "address": "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
      "confirmed": 14057482654100,
      "unconfirmed": 0
    },
    {
      "address": "1LVYbnSX6f6vE2Zn4zs2oZ4eKyBgzkqaay",
      "confirmed": 864733609713,
      "unconfirmed": 0
    }
  ],
  "creditsUsed": 3,
  "creditsRemaining": 29990
}

Code Examples

bash

curl -X POST https://btcaddresschecker.com/api/v1/balance/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "addresses": [
      "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
      "bc1ql49ydapnjafl5t2cp9zqpjwe6pdgmxy98859v2",
      "1LVYbnSX6f6vE2Zn4zs2oZ4eKyBgzkqaay"
    ]
  }'

Error Codes

Code	Title	Description
400	Bad Request	Missing or invalid "addresses" field, array exceeds 500 items, or one or more addresses are not valid Bitcoin addresses.
401	Unauthorized	Missing or invalid API key in x-api-key header.
402	Payment Required	Insufficient credits to complete the request.
403	Forbidden	API key is disabled.
429	Too Many Requests	Rate limit exceeded. Max 120 requests per minute per API key.
500	Internal Server Error	Unexpected server error. Try again later.
502	Bad Gateway	Upstream Bitcoin nodes are unreachable. Try again shortly.

Insufficient Credits Response

json

{
  "error": "Insufficient credits",
  "creditsRemaining": 0,
  "creditsRequired": 5
}

Invalid API Key Response

json

{
  "error": "Invalid API key"
}