# Watch Addresses

The Xverse API lets you **watch blockchain addresses** and receive transaction events as they happen.

This is built for apps that need to react to on-chain activity — **without polling** — such as wallets, payment flows, portfolio trackers, and backend reconciliation systems.

Address watching is currently available for **Bitcoin**.\
Support for **Spark** and **Starknet** webhooks is coming soon.

***

## 🔔 Transaction Webhooks

Webhooks are how Xverse delivers **address activity events** to your application.

Once a webhook subscription is registered for a set of addresses:

* Xverse monitors the addresses
* Transaction events are pushed to your backend via HTTP POST
* No custom indexing or node infrastructure is required

#### Supported networks

| Network                    | Status        |
| -------------------------- | ------------- |
| Bitcoin                    | ✅ Live        |
| Runes, Ordinals and BRC-20 | ✅ Live        |
| Spark                      | ⏳ Coming soon |
| Starknet                   | ⏳ Coming soon |
| Stacks                     | ⏳ Coming soon |

You can subscribe to:

* Incoming transactions
* Outgoing transactions

***

## :eyes: Register a Webhook Subscription

Start watching a set of addresses.

* Registers the address for transaction monitoring
* Enables webhook notifications for relevant transactions involving the addresses

{% hint style="info" %}
Currently supports Bitcoin addresses only.\
Spark & Starknet will be added soon and follow the same model.
{% endhint %}

## POST /v1/subscription

> Register a subscription for events.

```json
{"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription":{"post":{"tags":["Subscription"],"description":"Register a subscription for events.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhookEndpoint":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]},"subscriptionAddressPredicate":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string"}}},"required":["addresses"]}},"required":["webhookEndpoint","subscriptionAddressPredicate"]}}},"required":true},"responses":{"200":{"description":"Default Response"}}}}}}
```

***

### 📬 Webhook Payload (Bitcoin)

When a transaction involving any of the watched addresses is confirmed, Xverse sends a POST request to your webhook URL:

```json
[
  {
    "status": "confirmed",
    "address": "bc1qjpnsvwgsxtf005x2qd28l3zlmexa3095fa6g4e",
    "totalSatsIn": "0",
    "totalSatsOut": "1421459",
    "txid": "cc46ce35c459cd91585ec3848e0ec58b10a24770da5cdd264da41da7b3f07649",
    "blockHeight": 928800,
    "blockTime": "2025-12-21T07:42:08.000+02:00"
  }
]
```

Payloads for Spark and Starknet will follow a similar structure.

***

### 📄 List Webhook Subscriptions

Returns all active address-watching webhook subscriptions for your API key.

**Use this to**

* Inspect active address watchers
* Debug webhook behavior
* Manage multiple monitored sets of addresses

## GET /v1/subscription

> Get registered subscriptions.

```json
{"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription":{"get":{"tags":["Subscription"],"description":"Get registered subscriptions.","parameters":[{"schema":{"default":0,"minimum":0,"multipleOf":25,"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"default":25,"minimum":25,"maximum":25,"type":"number"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"webhookEndpoint":{"type":"object","properties":{"url":{"type":"string"},"updatedAt":{"type":"string"}},"required":["url","updatedAt"]},"subscriptionAddressPredicate":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["addresses","updatedAt"]}},"required":["id","webhookEndpoint","subscriptionAddressPredicate"]}}},"required":["limit","offset","total","items"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"description":"Invalid input","type":"string"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"description":"Unauthorized","type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"description":"Not found","type":"string"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"string"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"description":"Internal server error","type":"string"}}}}}}}}}
```

***

### ❌ Delete a Subscription

Stop watching a set of addresses by deleting the webhook subscription.

**Use this to**

* Stop receiving notifications for an address
* Clean up unused subscriptions

## DELETE /v1/subscription/{subscriptionId}

> Delete subscriptions.

```json
{"openapi":"3.0.3","info":{"title":"SecretKeyLabs API","version":"1.0.0"},"tags":[],"servers":[{"url":"https://api.secretkeylabs.io"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v1/subscription/{subscriptionId}":{"delete":{"tags":["Subscription"],"description":"Delete subscriptions.","parameters":[{"schema":{"type":"number"},"in":"path","name":"subscriptionId","required":true}],"responses":{"200":{"description":"Default Response"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xverse.app/api/watch-addresses.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.