> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The current DFNS API specification is https://docs.dfns.co/openapi.yaml. Files under /openapi-versions/ are archives of past releases; do not use them for new code.
> Prefer the official DFNS SDKs to raw HTTP calls: they sign requests for you. See https://docs.dfns.co/sdks.md.
> Requests that change state need a User Action Signature in the X-DFNS-USERACTION header, in addition to the Authorization bearer token. See https://docs.dfns.co/guides/developers/signing-requests.md.
> Do not use appId or the X-DFNS-APPID header: applications are deprecated.
> For a summary of how to build on DFNS, read https://docs.dfns.co/skill.md.

# Watch addresses via API

> Create address watches with the DFNS API and SDK, read a watched address's balances, history, and contract events, receive webhooks, and delete watches.

An [address watch](https://docs.dfns.co/core-concepts/address-watches.md) 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](https://docs.dfns.co/guides/watch-addresses.md).

## Prerequisites

* A [service account](https://docs.dfns.co/guides/developers/service-account.md) 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

```typescript TypeScript theme={null}
import { AddressWatchesClient } from '@dfns/sdk/generated/addressWatches'
import { AsymmetricKeySigner } from '@dfns/sdk-keysigner'

const signer = new AsymmetricKeySigner({
  credId: process.env.DFNS_CRED_ID!,
  privateKey: process.env.DFNS_PRIVATE_KEY!,
})

// Takes the same options as DfnsApiClient
const addressWatches = new AddressWatchesClient({
  baseUrl: 'https://api.dfns.io',
  authToken: process.env.DFNS_AUTH_TOKEN!,
  signer,
})
```

```go Go theme={null}
import (
    dfns "github.com/dfns/dfns-sdk-go/v2"
    "github.com/dfns/dfns-sdk-go/v2/addresswatches"
)

// keySigner: your user action signer, see the SDK README
client, err := dfns.NewClient(dfns.Options{
    AuthToken: os.Getenv("DFNS_AUTH_TOKEN"),
    Signer:    keySigner,
})
```

## 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.

```typescript TypeScript theme={null}
const watch = await addressWatches.createAddressWatch({
  body: {
    network: 'Ethereum',
    address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
    name: 'Counterparty settlement',
    externalId: 'cp-settlement-001',
  },
})

console.log(watch.id, watch.status) // aw-..., Active
```

```go Go theme={null}
name := "Counterparty settlement"
externalID := "cp-settlement-001"
watch, err := client.AddressWatches.CreateAddressWatch(ctx, addresswatches.CreateAddressWatchRequest{
    Network:    "Ethereum",
    Address:    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    Name:       &name,
    ExternalID: &externalID,
})

fmt.Println(watch.ID, watch.Status) // aw-..., Active
```

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](https://docs.dfns.co/api-reference/address-watches/list-address-watches.md) 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](https://docs.dfns.co/api-reference/address-watches/get-address-watch.md) still returns them with `status: Archived`.

```typescript TypeScript theme={null}
const { items, nextPageToken } = await addressWatches.listAddressWatches({
  query: { limit: 50 },
})
```

```go Go theme={null}
limit := int64(50)
page, err := client.AddressWatches.ListAddressWatches(ctx, &addresswatches.ListAddressWatchesQuery{
    Limit: &limit,
})
```

## Read balances

[Get Address Watch Assets](https://docs.dfns.co/api-reference/address-watches/get-address-watch-assets.md) returns the native and fungible token balances of the address, in the same format as [wallet assets](https://docs.dfns.co/api-reference/wallets/get-wallet-assets.md). Add `netWorth: 'true'` to get the total USD value.

```typescript TypeScript theme={null}
const { assets, netWorth } = await addressWatches.getAddressWatchAssets({
  addressWatchId: watch.id,
  query: { netWorth: 'true' },
})
```

```go Go theme={null}
netWorth := "true"
balances, err := client.AddressWatches.GetAddressWatchAssets(ctx, watch.ID, &addresswatches.GetAddressWatchAssetsQuery{
    NetWorth: &netWorth,
})
```

Balances are available on [Tier-1 and Tier-2 networks](https://docs.dfns.co/networks.md).

## Read history and contract events

[Get Address Watch History](https://docs.dfns.co/api-reference/address-watches/get-address-watch-history.md) returns the confirmed transfers that touch the address, in the same format as [wallet history](https://docs.dfns.co/api-reference/wallets/get-wallet-history.md). Filter by `direction` (`In` or `Out`), `kind`, or `contract`.

```typescript TypeScript theme={null}
const history = await addressWatches.getAddressWatchHistory({
  addressWatchId: watch.id,
  query: { direction: 'In' },
})
```

```go Go theme={null}
direction := "In"
history, err := client.AddressWatches.GetAddressWatchHistory(ctx, watch.ID, &addresswatches.GetAddressWatchHistoryQuery{
    Direction: &direction,
})
```

[Get Address Watch Blockchain Events](https://docs.dfns.co/api-reference/address-watches/get-address-watch-blockchain-events.md) returns the decoded smart contract events that involve the address.

```typescript TypeScript theme={null}
const events = await addressWatches.getAddressWatchBlockchainEvents({
  addressWatchId: watch.id,
})
```

```go Go theme={null}
events, err := client.AddressWatches.GetAddressWatchBlockchainEvents(ctx, watch.ID, nil)
```

History and blockchain events are available on [Tier-1 networks](https://docs.dfns.co/networks.md#tier-1-blockchain-networks). They start when the address is first watched: earlier activity is not indexed.

## Receive webhooks

Subscribe a [webhook](https://docs.dfns.co/guides/developers/webhooks.md) to these events to be notified of activity on watched addresses:

| Event | Fires when |
| - | - |
| [`address_watch.blockchain_event.transfer.confirmed`](https://docs.dfns.co/api-reference/wallets/address-watch-blockchain-event-transfer-confirmed) | A transfer touching a watched address is confirmed on chain, such as a deposit. |
| [`address_watch.blockchain_event.misc.confirmed`](https://docs.dfns.co/api-reference/wallets/address-watch-blockchain-event-misc-confirmed) | A contract event that is not an asset transfer, and involves a watched address, is confirmed on chain. |

## Delete a watch

[Delete Address Watch](https://docs.dfns.co/api-reference/address-watches/delete-address-watch.md) archives the watch (`status: Archived`) and stops its webhooks immediately. Deleting is a signed user action.

```typescript TypeScript theme={null}
await addressWatches.deleteAddressWatch({ addressWatchId: watch.id })
```

```go Go theme={null}
_, err = client.AddressWatches.DeleteAddressWatch(ctx, watch.ID)
```

To watch the address again, create a watch for the same address and network: DFNS reactivates the archived one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.