Manage the Watchlist

The watchlist is the set of wallet addresses that Active Monitoring screens with TRM. This guide covers the three watchlist operations: add addresses from a CSV file, add addresses from an identity registry, and view the list. For how screening uses the watchlist, see Watchlist and Screening.

The watchlist belongs to your organization and is shared by all your monitored tokens. Add the addresses you want to watch, such as holders of your token. Each address is listed with one or more networks, identified by chain selector: the unique ID that Chainlink assigns to a network. Find selectors in Supported Networks.

The watchlist has no fixed size limit. The Platform UI accepts up to 100 rows per CSV upload: upload several files to add more. The API does not enforce this limit per request.

Prerequisites

• To upload a file, a CSV with one row per address. The format is described in the next section.
• To import from a registry, an identity registry in your organization that contains registered identities. Only organizations that use the Identity Manager can use this option.
• To use the API tab, an ACE API key, sent in the Authorization: Apikey <API_KEY> header of each request. See Create an API key.

Add addresses from a CSV file

curl -X POST https://ace.api.chain.link/v1/active-monitoring/monitored-addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "source": "list",
    "addresses": [
      {
        "title": "Holder 1",
        "address": "0x5555555555555555555555555555555555555555",
        "chain_selectors": ["16015286601757825753"]
      },
      {
        "address": "0x6666666666666666666666666666666666666666",
        "chain_selectors": ["16015286601757825753", "3478487238524512106"]
      }
    ]
  }'

{
  "results": [
    {
      "id": "0d4f6c1e-7b2a-4c55-9e0b-3f1a8d2c4b10",
      "title": "Holder 1",
      "address": "0x5555555555555555555555555555555555555555",
      "chain_selectors": ["16015286601757825753"],
      "source_reference_id": null,
      "monitored_address_trm_score": null
    }
    // ... one entry per address
  ]
}

CSV format

The file needs two columns, with these exact header names (case-insensitive): address and chain_selector.

• Use one row per address.
• Set chain_selector to the chain selector of the network, not its name. Find selectors in Supported Networks.
• To list several networks for one address, wrap the selectors in quotes and separate them with commas.

The following file adds two addresses. The second address is listed on two networks:

address,chain_selector
0x5555555555555555555555555555555555555555,16015286601757825753
0x6666666666666666666666666666666666666666,"16015286601757825753,3478487238524512106"

The Platform UI checks the file before it sends anything: the headers, the address format, that each network is supported, and the 100-row limit. It does not check for duplicates. If an address appears twice in the file, or is already on the watchlist, the whole upload fails and no address is added.

The networks you list for an address do not change what is screened or where decisions are created. TRM screens an address across all the networks it covers, and Active Monitoring evaluates a risk event on every network of each monitored token.

Add addresses from an identity registry

An identity registry holds the wallet addresses of your registered identities. Importing a registry adds every active onchain address of its identities to the watchlist, so you do not maintain a separate list.

curl -X POST https://ace.api.chain.link/v1/active-monitoring/monitored-addresses \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "source": "registry",
    "registry_id": "<REGISTRY_ID>"
  }'

The import is a snapshot of the registry at the time you import it. Addresses you add to the registry later are not added to the watchlist.

View the watchlist

curl "https://ace.api.chain.link/v1/active-monitoring/monitored-addresses?page=1&page_size=100" \
  -H "Authorization: Apikey <API_KEY>"

Remove addresses

You cannot remove an address from the watchlist in Beta, in the Platform UI or in the API.

Next steps

• Configure the TRM API Key and Screening Schedule: start screening the watchlist.
• Review Decisions and Track Operations: see the decisions that screening produces.