Skip to main content

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.

​
Overview

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.
Early accessThis feature is currently in Early Access (a Beta Service). To request access, enable it in Settings > Labs or contact your Fireblocks Customer Success Manager. Early Access features are subject to the beta terms under Product Specific Terms.

​
Look up an address

Query a blockchain address to retrieve the legal entity information associated with it.

​
Request

GET /v1/address_registry/legal_entities/{address}
ParameterTypeRequired?Description
addressstringYesThe blockchain address to look up.

​
Response

If the address resolves to an opted-in Fireblocks customer: 
{
  "verified": true,
  "entityName": "ACME Corporation",
  "jurisdiction": "US",
  "lei": "254900GC33RBE6FQA817",
  "travelRuleProviders": [
    "TRAVEL_RULE_PROVIDER_NOTABENE",
    "TRAVEL_RULE_PROVIDER_SYGNA"
  ],
  "email": "compliance@example.com"
}
FieldTypeDescription
verifiedbooleantrue if entity data is sourced from an approved LEI and validated by Fireblocks. false if sourced from Fireblocks data without independent validation.
entityNamestringLegal entity name associated with the vault controlling the address.
jurisdictionstringISO country code of the legal entity.
leistringLegal Entity Identifier (LEI) of the counterparty, if available.
travelRuleProvidersarrayTravel Rule providers the counterparty supports, if declared.
emailstringCounterparty’s Travel Rule contact email, if declared.
If the address is not found — because the counterparty is not a Fireblocks customer, has opted out, or is on an unsupported environment — the response returns HTTP 404: 
{
  "code": "2142",
  "message": "Address could not be resolved"
}
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 for more details.
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. Each workspace can register multiple legal entities.

​
Request

POST /v1/legal_entities

{
  "lei": "529900HNOAA1KXQJUQ27",
  "travelRuleProviders": [
    "MY_OWN"
  ],
  "travelRuleContactEmail": "compliance@example.com"
}
ParameterTypeRequired?Description
leistringYesA valid 20-character LEI present in the GLEIF registry.
travelRuleProvidersarrayNoTravel Rule providers to associate with this entity. Enum: CODE, GTR, MY_OWN, NOTABENE, SYGNA, SUMSUB, TRISA, TRUST, TWENTY_ONE_ANALYTICS, VERIFY_VASP.
travelRuleContactEmailstringNoContact email for Travel Rule communications.

​
Response (success)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "lei": "529900HNOAA1KXQJUQ27",
  "status": "PENDING",
  "isDefault": false,
  "travelRuleProviders": [
    "MY_OWN"
  ],
  "travelRuleContactEmail": "compliance@example.com",
  "gleifData": {
    "lei": "529900HNOAA1KXQJUQ27",
    "legalName": "Example Corporation Ltd.",
    "otherNames": [
      "ExCorp",
      "Example Corp"
    ],
    "legalAddressRegion": "NY",
    "legalAddressCountry": "US",
    "nextRenewalDate": "2025-12-31T00:00:00Z"
  },
  "createdAt": "1700000000000",
  "updatedAt": "1700000000000"
}

​
Error responses

CodeMeaning
HTTP 400Invalid LEI or request parameters.
HTTP 404LEI not found in the GLEIF registry.
HTTP 409A legal entity with this LEI is already registered for the workspace.

​
LEI states

After you submit an LEI, it moves through the following states:
StateDescription
PendingSubmitted and under Fireblocks review. Your addresses appear as unverified to counterparties during this time.
ApprovedVerified by Fireblocks. Queries against your addresses return your legal entity name, jurisdiction, and LEI.
DeniedRejected by Fireblocks. You can view the reason and resubmit.
RevokedPreviously approved, then revoked due to an expired or invalid LEI.
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, refer to the legal entity endpoints in the API reference. Each vault account supports a maximum of one legal entity.

​
Opt out of Address Registry

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

​
Opt out an entire workspace

DELETE /v1/address_registry/tenant
No request body is required. A successful response returns a status of OPTED_OUT using the same JSON structure as the GET participation status endpoint.

​
Opt out individual vault accounts

Add vault account IDs to the opt-out list: 
POST /v1/address_registry/vaults

{
  "vaultAccountIds": [
    10001,
    "10002"
  ]
}
ParameterTypeRequired?Description
vaultAccountIdsarrayYesVault account IDs to add to the opt-out list. Accepts both integers and strings.

​
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.
Feature coming soonCompliance workflows are not yet available but will be added during the Early Access phase.

​
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. API endpoints: 
POST   /v1/counterparty-groups          # Create a group
GET    /v1/counterparty-groups          # List all groups
PUT    /v1/counterparty-groups/{id}     # Update a group
DELETE /v1/counterparty-groups/{id}     # Delete a group

​
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.
ConditionAction
Counterparty is in [Group]Accept or Reject
Counterparty is not in [Group]Accept or Reject
Address not found in registryAccept or Reject
API endpoints: 
PUT    /v1/counterparty-groups/policy   # Configure screening policy
GET    /v1/counterparty-groups/policy   # Get current policy
GET    /v1/counterparty-groups/address  # Get group context for an address

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