Skip to main content
An address watch follows an on-chain address that is not one of your wallets. This guide covers the address-watch endpoints with the TypeScript and Go SDKs. To do the same from the dashboard, see Watch addresses.

Prerequisites

  • A service account or user with these permissions:
    • AddressWatches:Create to create a watch
    • AddressWatches:Read to list watches and read their balances, history, and events
    • AddressWatches:Delete to delete a watch
  • @dfns/sdk 0.8.37 or later, or dfns-sdk-go v2.2.1 or later

Set up the client

Create a watch

Pass the network and the address. name and externalId are optional. Creating a watch is a signed user action: the SDK signs it with your signer.
The request returns 400 Bad Request when:
  • the network does not support address watches,
  • the address is not valid for the network,
  • the address is already watched on this network by your organization.
It is also rejected when your organization has reached its wallet limit: address watches count against it. If you create a watch for an address you watched and deleted before, DFNS reactivates the deleted watch. It keeps its ID, name, external ID, and history, and the name and externalId in the request are ignored.

List watches

List Address Watches returns your active watches, oldest first. Pass nextPageToken back as paginationToken to get the next page. Deleted watches are not listed, but Get Address Watch still returns them with status: Archived.

Read balances

Get Address Watch Assets returns the native and fungible token balances of the address, in the same format as wallet assets. Add netWorth: 'true' to get the total USD value.
Balances are available on Tier-1 and Tier-2 networks.

Read history and contract events

Get Address Watch History returns the confirmed transfers that touch the address, in the same format as wallet history. Filter by direction (In or Out), kind, or contract.
Get Address Watch Blockchain Events returns the decoded smart contract events that involve the address.
History and blockchain events are available on Tier-1 networks. They start when the address is first watched: earlier activity is not indexed.

Receive webhooks

Subscribe a webhook to these events to be notified of activity on watched addresses:

Delete a watch

Delete Address Watch archives the watch (status: Archived) and stops its webhooks immediately. Deleting is a signed user action.
To watch the address again, create a watch for the same address and network: DFNS reactivates the archived one.
Last modified on November 20, 2026