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

# Address Registry

Address Registry lets you verify the legal entity controlling a blockchain address before sending or receiving a transaction. When enabled, Address Registry allows you to query blockchain addresses and receive certain legal entity information about the institution controlling the associated vault. The Address Registry is designed solely to facilitate counterparty discovery and verification in connection with digital asset transactions.

Address Registry is a free capability available to all Fireblocks customers and enabled by default. Coverage is currently limited to addresses within the Fireblocks network.

## Look up an address

Query a blockchain address to retrieve the legal entity information associated with it. If the address resolves to an opted-in Fireblocks customer, the response returns the entity name, jurisdiction, LEI, and any declared Travel Rule providers and contact email. Each result also indicates whether the data is sourced from an approved, Fireblocks-validated LEI or from unverified Fireblocks data.

If the address is not found — because the counterparty is not a Fireblocks customer, has opted out, or is on an unsupported environment — the lookup returns `not_found`.

See [Look up legal entity by blockchain address](/api-reference/compliance/look-up-legal-entity-by-blockchain-address) in the API reference.

<Note>
  **Notes about the Address Registry lookup**

  * A `not_found` result does not indicate that the address is unhosted, illicit, or non-compliant.
  * The registry is designed to prevent bulk data extraction or misuse. We put in place various controls like query authentication, API rate limiting, daily request caps, and alerts to ensure the number of queries remains proportional to the number of transactions. See [the FAQ](https://support.fireblocks.io/hc/en-us/articles/26105830582940-Address-Registry#h_01KP5Z8EQMTNW36W3RSNQJV9C9) for more details.
</Note>

## Register a legal entity

To appear as a verified entity when counterparties look up your addresses, register your Legal Entity Identifier (LEI) with Fireblocks. This step is optional if you only want to query addresses, but required to return verified data and to use Address Registry in compliance workflows. Fireblocks validates the submitted LEI against the GLEIF registry, and each workspace can register multiple legal entities.

See [Register a new legal entity](/api-reference/compliance/register-a-new-legal-entity) in the API reference.

### LEI states

After you submit an LEI, it moves through the following states:

| State      | Description                                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| `Pending`  | Submitted and under Fireblocks review. Your addresses appear as unverified to counterparties during this time. |
| `Approved` | Verified by Fireblocks. Queries against your addresses return your legal entity name, jurisdiction, and LEI.   |
| `Denied`   | Rejected by Fireblocks. You can view the reason and resubmit.                                                  |
| `Revoked`  | Previously approved, then revoked due to an expired or invalid LEI.                                            |

### Map vault accounts to legal entities

After Fireblocks approves your first LEI, all vault accounts map to that entity by default. If you register additional legal entities and want to map specific vault accounts to them, use the [Assign vault accounts to a legal entity](/api-reference/compliance/assign-vault-accounts-to-a-legal-entity) endpoint. Each vault account supports a maximum of one legal entity.

## Opt out of Address Registry

All workspaces are enrolled in Address Registry by default. New workspaces created after enrollment also inherit opted-in status automatically. Account-level opt-out — which excludes all current and future workspaces from the registry — must be requested through your Customer Success Manager. Workspaces that remain opted in can independently opt out individual vault accounts or the entire workspace programmatically via the API or through the Console.

You can opt out your entire workspace or individual vault accounts. When you opt out, lookups against your addresses return `not_found`. You can disable and re-enable at any time.

<Note>
  **Notes about opting out**

  * Opting out prevents you from querying addresses or using compliance workflows that depend on Address Registry.
  * Opting out disables all compliance workflows built on Address Registry. Re-enabling restores them.
</Note>

### Opt out an entire workspace

Opt your entire workspace out of Address Registry. A successful response returns a participation status of `OPTED_OUT`.

See [Opt the workspace out of the Address Registry](/api-reference/compliance/opt-the-workspace-out-of-the-address-registry) in the API reference.

### Opt out individual vault accounts

Add specific vault account IDs to the opt-out list to exclude them from Address Registry while keeping the rest of the workspace opted in.

See [Add vault accounts to the Address Registry opt-out list](/api-reference/compliance/add-vault-accounts-to-the-address-registry-opt-out-list) in the API reference.

## Use Address Registry in compliance workflows

You can use Address Registry inside your transaction screening policy to automate compliance decisions based on counterparty identity. The workflow has two parts: define counterparty groups, then apply rules to those groups in a screening policy.

### Define counterparty groups

A *counterparty group* is a named set of counterparties that share specific attributes. You can create as many groups as you need. Jurisdiction is the only available grouping attribute initially. Additional attributes such as business type and license type are planned.

Manage counterparty groups with the following endpoints:

* [Create a counterparty group](/api-reference/compliance/create-a-counterparty-group) — define a new group, matching counterparties by jurisdiction.
* [List counterparty groups](/api-reference/compliance/list-counterparty-groups) — retrieve all groups in the workspace, with pagination.
* [Get a counterparty group](/api-reference/compliance/get-a-counterparty-group) — fetch a single group by ID.
* [Update a counterparty group](/api-reference/compliance/update-a-counterparty-group) — change a group's name, description, jurisdiction codes, or active state.
* [Delete a counterparty group](/api-reference/compliance/delete-a-counterparty-group) — remove a group from the workspace.

### Set a screening policy

The screening policy consists of two parts:

* **Transaction screening policy**: Defines which transactions trigger a counterparty check. Build rules using source, destination, asset, and amount. Rules evaluate from top to bottom, and the first match wins. A catch-all default rule is required as the last entry. You also configure timeout behavior separately to define what happens if the registry check times out during a transaction (accept or reject).
* **Post-screening policy**: Defines the action to take based on the counterparty check result.

| Condition                     | Action           |
| ----------------------------- | ---------------- |
| Counterparty is in \[Group]   | Accept or Reject |
| Address not found in registry | Accept or Reject |

This section covers how to programmatically configure and manage your transaction authorization policies using the [Fireblocks Policies API](/docs/set-transaction-authorization-policy)

#### Activate Address Registry Screening

Activates Address Registry Screening (ARS) for the workspace. Once active, ARS applies to transactions that match your screening rules. The workspace must be opted in to Address Registry, otherwise the request fails.

See [Activate ARS (Address Registry Screening)](/api-reference/compliance/activate-ars-address-registry-screening) in the API reference.

#### Deactivate Address Registry Screening

Deactivates ARS for the workspace. Once deactivated, ARS no longer applies to transactions until it is activated again.

See [Deactivate ARS (Address Registry Screening)](/api-reference/compliance/deactivate-ars-address-registry-screening) in the API reference.

## Availability and limitations

Fireblocks does not currently support Address Registry for workspaces hosted on European or Swiss environments due to infrastructure isolation between production instances. We plan to add support for these environments shortly after the initial release. In the meantime, queries against addresses from European or Swiss-hosted workspaces return `not_found`.

Address Registry is not available in Developer Sandbox workspaces.