👀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

---

👀 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

Currently supports Bitcoin addresses only. Spark & Starknet will be added soon and follow the same model.

post

Register a subscription for events.

Authorizations

x-api-keystringRequired

Body

Responses

200

Default Response

No content

post/v1/subscription

POST /v1/subscription HTTP/1.1
Host: api.secretkeylabs.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "webhookEndpoint": {
    "url": "text"
  },
  "subscriptionAddressPredicate": {
    "addresses": [
      "text"
    ]
  }
}

200

Default Response

No content

---

📬 Webhook Payload (Bitcoin)

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

[
  {
    "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

Get registered subscriptions.

Authorizations

x-api-keystringRequired

Query parameters

offsetnumberOptionalDefault: 0

limitnumber · min: 25 · max: 25OptionalDefault: 25

Responses

200

Default Response

application/json

limitnumberRequired

offsetnumberRequired

totalnumberRequired

400

Invalid input

application/json

401

Unauthorized

application/json

404

Not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

get/v1/subscription

GET /v1/subscription HTTP/1.1
Host: api.secretkeylabs.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "limit": 1,
  "offset": 1,
  "total": 1,
  "items": [
    {
      "id": 1,
      "webhookEndpoint": {
        "url": "text",
        "updatedAt": "text"
      },
      "subscriptionAddressPredicate": {
        "addresses": [
          "text"
        ],
        "updatedAt": "text"
      }
    }
  ]
}

---

❌ 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

Delete subscriptions.

Authorizations

x-api-keystringRequired

Path parameters

subscriptionIdnumberRequired

Responses

200

Default Response

No content

delete/v1/subscription/{subscriptionId}

DELETE /v1/subscription/{subscriptionId} HTTP/1.1
Host: api.secretkeylabs.io
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

No content