# Bitcoin Balance API

The simplest api to get Bitcoin Address and Wallet balances

## API Endpoints

**Mainnet:** `https://api.bitcoin-balance-api.com`

## Rate Limiting

We hav a handsome rate-limiting of `60 requests / minute` , but can be adjusted depending on your needs. Batch processing is limited to `20 requests / minute`.

## Swagger Documentation

**Mainnet:** `https://api.bitcoin-balance-api.com/docs/`


# Payments

Everything about our paid plans.

## Plans

We offer one simple plan for **80 USD per month**, which allows you to do as many requests as you want (rate limiting applied). If you require a custom solution please contact us.

The payment is processed via Lemon Squeezy and payments are possible via Credit Card or Paypal. All your payment information are **PCI-DSS compliance** on the Lemon Squeezy and no such information are stored on our systems.

## How to make a payment?

1. Create a API Key

   You can create a free api key on our [website](https://api.bitcoin-balance-api.com/keys). The key can be used for testing as well.
2. Make Payment

   Once you obtained an api key you can [make a payment](https://api.bitcoin-balance-api.com/payment) and get unlimited requests.

## I have questions!

Please feel free to reach out to use via [Email](mailto:hello@bitcoin-balance-api.com) or [Telegram](https://t.me/BitcoinBalanceAPI) and we hope to answer all your questions.


# Error Codes

The response codes you might experience.

**200** - OK

**401** - Authentication Error

**402** - Payment Required

**422** - Wrong Bitcoin Address

**429** - You have hit your assigned rate limit for the API

**500** - We could not process your request (Wrong Input or too many utxo transactions per address)


# Postman

Postman Example on how to retrieve a Bitcoin wallet balance

<figure><img src="https://35432300-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKcMHzDT33emwWOpdKa43%2Fuploads%2FQgsNszAfr0D8Rru8yc3d%2Fimage.png?alt=media&amp;token=fe6bd2ee-a96a-4646-b925-fd76c31ae552" alt=""><figcaption><p>Postman with connection to Bitcoin Balance API</p></figcaption></figure>

## Configuration

{% file src="/files/rvEm0T1FcNlj5rWw7Z7H" %}

Download the above file and import it into Postman for easy access to the testnet and mainnet of the Bitcoin Balance API.


# Balance

Get the balance of any Bitcoin address

## Make a request (mainnet)

For mainnet a valid apikey is needed and needs to be send as a query parameter. You can [create a temporary mainnet api key](https://api.bitcoin-balance-api.com/keys) for testing the api. The correct url for mainnet is:

```
https://api.bitcoin-balance-api.com/v1/address/34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo?apikey=$SECRET
```

Where `$SECRET` needs to be replaced with your own apikey.

## Response

The response from the api contains two fields, `status` and `balance`. When status is `200` the request was successful and it will contain the value in the `balance` field. E.g.:

```json
{ "status": 200, "balance": 19989726659 }
```

The `status` field can contain different responses like [400, 401, 404, 422 or 500](/error-codes) depending on the request.

### Balance Calculation

The `balance` is in satoshi's and if you want to change it to BTC, it needs to be divided by **100000000**. E.g.:

```python
# Python Example
balance=7821967447
balance_btc=balance/100000000
print(f'Balance in Bitcoin: %s' % (balance_btc))
```


# UTXO

Get all unspent UTXO of an address

{% hint style="warning" %}
The `utxo`limit is 500 transactions for each address. Contact us if you need more.
{% endhint %}

## Make a request (mainnet)

For mainnet a valid apikey is needed and needs to be send as a query parameter. You can [create a temporary mainnet api key](https://api.bitcoin-balance-api.com/keys) for testing the api. The correct url for mainnet is:

```
https://api.bitcoin-balance-api.com/v1/utxo/mqJpUp5yt3m5in6pMJEW7rN2SifGoFKTJQ?apikey=$SECRET
```

Where `$SECRET` needs to be replaced with your own apikey.

## Response

The response from the api contains two fields, `status` and `utxo`. When status is `200` the request was successful and it will contain an array of the utxo. E.g.:

```json
{ "status": 200, "utxo": [{"txid": "07c9ab25dd88b9bb81e0d0f720df70f4642009fb205b0a63af3f5ca96a2e2e0c", "vout": 0, "status": {"confirmed": true, "block_height": 3924924, "block_hash": "0000000000443e317917844329700a8f7ff32992560b0f728a2874a1f037fff9", "block_time": 1740913388}, "value": 23592760}] }
```

The `status` field can contain different responses like [400, 401, 404, 422 or 500](/error-codes) depending on the request.


# Batch Processing

Batch processing of multiple addresses in one request.

## Make a request

{% hint style="warning" %}
This feature is limited to 10 addresses.
{% endhint %}

The best way to interact with our API:

{% tabs %}
{% tab title="Curl" %}

```bash
curl -X POST "https://api.bitcoin-balance-api.com/v1/address/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "tb1qlw09ycnp3qgqw9alqgx93ed7cg5kmnyud326ky",
      "2N8qAsMRn4WvEZJmTWf2K5Vn1C69JH9XjTW"
    ]
  }'
```

{% endtab %}
{% endtabs %}

## Response

The response from the api contains the same fields as a single balance request, but in an array of all addresses. E.g.:

```json
{
  "status": 200,
  "results": [
    {
      "address": "tb1qlw09ycnp3qgqw9alqgx93ed7cg5kmnyud326ky",
      "balance": 954929635,
      "status": "success"
    },
    {
      "address": "2N8qAsMRn4WvEZJmTWf2K5Vn1C69JH9XjTW",
      "balance": 541997,
      "status": "success"
    }
  ]
}
```


# MCP

Model Context Protocol for Bitcoin Account Balance's

Our MCP server allow's you to connect your development tools and AI tools to connect directly to our  infrastructure. This allows you to integrate anything Bitcoin Balance related to be used in your workflow.

**MCP URL:** <https://api.bitcoin-balance-api.com/mcp>

The connection needs the api key to be in the `X-API-Key` header.

### Cursor Implementation

When configuring the MCP in Cursor you can easily do this in your project directory via `.cursor/mcp.json`

```
{
  "mcpServers": {
    "bitcoin-balance-api": {
      "url": "https://api.bitcoin-balance-api.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_SECRET_API_KEY"
      }
    }
  }
}
```

Or via the UI in **Cursor** -> **Settings** -> **Tools & MCPs**:

<figure><img src="https://35432300-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKcMHzDT33emwWOpdKa43%2Fuploads%2F0Q6FCJtoDFPOmRDNfSNM%2Fimage.png?alt=media&amp;token=a2417c19-dc45-4184-bad3-a53a2a46ab01" alt=""><figcaption></figcaption></figure>

**Don't forget to enable it**, also when configured via the configuration file. Once it is enabled, the AI can access the server:

<figure><img src="https://35432300-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKcMHzDT33emwWOpdKa43%2Fuploads%2FA9Ozfz4cIL5muqVoGYXg%2Fimage.png?alt=media&amp;token=69cb2f2d-4917-496b-90e4-55bc211ea9e3" alt=""><figcaption></figcaption></figure>


# SKILL.md

Install our agent SKILL.md for your AI to work with us

Find our **SKILL.md** on Github: <https://github.com/BitconBalanceAPI/bitcoin-balance-api-skill>

## Github CLI

Install the **SKILL.md** from the Github CLI:

```
gh skill install BitconBalanceAPI/bitcoin-balance-api-skill
```

For more agent support check the [official documentation](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/#supported-agent-hosts).

### Cursor Integration Example

```
% gh skill install BitconBalanceAPI/bitcoin-balance-api-skill --agent cursor
Using ref v1.0.0 (7f780695)
? Select skill(s) to install: bitcoin-balance-api-skill - Looks up confirmed Bitcoin mainnet address balances, batch balances, and UTXOs via the Bitcoin Balance API (MCP streamable HTTP or REST at api.bitcoin-balance-api.com). U...

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.

? Installation scope: Global: install in home directory (available everywhere)
✓ Installed bitcoin-balance-api-skill (from BitconBalanceAPI/bitcoin-balance-api-skill@v1.0.0) in ~/.cursor/skills

  bitcoin-balance-api-skill/
  ├── SKILL.md
  └── references/
      └── INTEGRATION.md

! Skills may contain prompt injections or malicious scripts.
  Review installed content before use:

    gh skill preview BitconBalanceAPI/bitcoin-balance-api-skill bitcoin-balance-api-skill@7f780695dccfdcdd0c480fcbf1f3e177e21ffdd0

```