21 Travel Rule Documentation
Exchange Travel Rule data with other virtual asset service providers (VASPs) and verify ownership of self-hosted wallets. 21 Travel Rule runs in your own infrastructure, with a Compliance Dashboard for your team, a GraphQL API for automation, and proof portals for your customers.
Start with Your Goal
Evaluate the Product
Check how 21 Travel Rule fits your systems and requirements.
Use the Compliance Dashboard
Set up your VASP and handle day-to-day compliance tasks.
Integrate Your Systems
Connect your custody and compliance workflows to the API.
Deploy and Administer
Install 21 Travel Rule and manage access in your environment.
Understand the Two Core Workflows
- Transfers with another VASP: exchange originator and beneficiary data through TRUST, TRP, or encrypted email.
- Transfers with a self-hosted wallet: collect and review address ownership evidence using digital signatures (AOPP), Satoshi tests, or visual proofs.
New to the terminology? Start with the Travel Rule overview and glossary.
Sandbox Access
Evaluate the Compliance Dashboard and GraphQL API without installing the software. Prospective customers can request free, time-limited sandbox access by arranging an introductory call.
The sandbox is shared between prospective customers. Use fictitious test data only; do not enter real customer or personal data.
Help and Releases
For technical help, use the support desk. For all other inquiries, contact info@21analytics.co.
Use the version selector in the toolbar to match the docs to your deployment. See the release and support lifecycle for release timing and supported versions, or the upgrade guide when updating an existing installation.
Software Architecture
The 21 Travel Rule software solution consists of containerised microservices. The backend daemons are available as separate “FROM scratch” images (referred to as “micro images”). With a micro image, each executable runs in an empty container, which isolates the execution environment of a process. Even if an attacker successfully hacks 21 Travel Rule, they find themselves in an empty container with no further exploitable software.
Container Images
Backend Services
Each daemon is distributed as its own container image: trustd, trpd, aopd
and autod. Each image contains only its corresponding executable, allowing the
services to be deployed, scaled and updated independently.
compliance-dashboard (Back Office GUI)
This image serves the optional internal Compliance Dashboard web application.
aopp-portal (Front Office GUI)
This image serves the optional AOPP Portal web application which automates interactions with your customers without the need for authentication by relying on unique URLs instead.
Microservices and Network Overview
Microservices
trustd (TRUST)
trustd is the processing engine for exchanging travel rule data through the TRUST protocol. It handles communication with the counterparty discovery service, as well as with all counterparty VASPs using the TRUST protocol. It's possible to run multiple instances of trustd for HA, failover and zero-downtime updates.
trpd (TRP)
trpd is the processing engine for exchanging travel rule data through Travel Rule Protocol (TRP). It handles communication with all counterparty VASPs using TRP. It's possible to run multiple instances of trpd for HA, failover and zero-downtime updates.
aopd (AOPP)
aopd is the processing engine for registering ownership proofs through Address Ownership Proof Protocol (AOPP; Digital Signatures), Visual Proofs and Satoshi Tests. It handles communication with non-custodial (self-hosted) wallets. It's possible to run multiple instances of aopd for HA, failover and zero-downtime updates.
autod (Internal API)
autod is the internal API that provides unified access to all databases and services of 21 Travel Rule. Its GraphQL API is used by the Web User Interface and custom integrated services from the VASP.
Databases
The SQL databases are handled by PostgreSQL, a free and open-source (OSI-approved license) relational database management system. PostgreSQL can be run as a container, standalone application, or is also available as a fully managed service from various cloud providers.
TRUST
The TRUST database contains all data related to transfers through the TRUST protocol, as well as additional data for those transfers sourced from the TRUST counterparty discovery service.
TRP
The TRP database contains all data related to transfers through the Travel Rule Protocol, as well as additional data for those transfers sourced from Blockchain Analytics, Screening and Exchange Rate services.
The Email database contains all data related to transfers sent out via email, as well as additional data for those transfers sourced from Blockchain Analytics, Screening and Exchange Rate services.
AOPP
The AOPP database contains all data related to transfers with self-hosted wallets, as well as additional data for those transfers sourced from Blockchain Analytics and Exchange Rate services.
Offline
The Offline database contains all data related to incoming-transfers registered manually by receiving VASP through the Compliance Dashboard or the API.
Compliance Dashboard
The Compliance Dashboard is served from a container of the compliance-dashboard image. It runs a HTTP file server. The Compliance Dashboard is only accessible to users (typically compliance officers) from within the VASP and should never be exposed to the outside world. It only accesses autod, the internal API.
It's possible to run multiple instances of the Compliance Dashboard.
SeaweedFS
SeaweedFS is an open-source fast distributed storage system for blobs, objects, files, and data lake, for billions of files. In the 21 Travel Rule software solution it's used to store and access of visual proofs. Alternatively, any S3-compatible storage can be used instead.
Keycloak
Keycloak is an open source identity and access management software. It provides the account management and single-sign on functionality. Keycloak has built-in support to connect to existing LDAP or Active Directory servers.
Physical Architecture
21 Travel Rule can be run on a single machine, as demonstrated in the Reference Deployment, which is based on Helm charts.
The 21 Travel Rule container-based architecture also effortlessly enables more advanced setups, such as deploying a cluster of machines on OpenShift to provide HA and automatic failover.
Security
This section gives an overview of 21 Analytics' security processes and the security designs and mitigations in 21 Travel Rule.
Security-first Development Policies
Development Collaboration Platform
Gitlab is 21 Analytics' development collaboration platform where all development policies are enforced, continuous integration checks are run and dependency management tools are integrated.
Access rights to developers are granted conservatively, i.e. developers cannot change policies but need to request those changes from upper management.
Rust
21 Travel Rule uses Rust as its backend development language. Rust is a memory-safe language that compiles to machine code and thus doesn't compromise on performance while eliminating the primary source for security-related bugs 1 2 3.
Rust has seen growing adoption in both critical open source software 4 5 6 7 and at Fortune 500 companies 8 9 10 11.
Rust's safety guarantees are softened when using so-called unsafe blocks. 21
Analytics' policy is to forbid unsafe code blocks which is enforced through a
dedicated compiler setting.
Code Review
21 Analytics has strict code review policies in place that demand that every change to the source code needs to be reviewed and approved by another developer. Only then it can be merged into master. Among other aspects the reviewer is asked to focus on security. As a side-effect of these code review practices, know-how is spread across the team that shares the responsibility for the source code. This eliminates malware injection or sabotage from malicious insiders.
The code review policy is enforced by Gitlab.
Continuous Integration
The 21 Travel Rule continuous integration pipeline runs tests, linter checks and builds. Only if all tasks run successfully a change can be merged into master.
This continuous integration check policy is enforced by Gitlab.
Employing a security-in-depth approach, 21 Analytics uses the cargo-audit
12 vulnerability scanner to automatically scan the entire 21 Travel Rule
dependency tree for versions with reported security vulnerabilities. This is
also run by the continuous integration system and hence, will block offending
changes from being merged into master. If issues arise on the master branch then
all merge requests will be blocked until the issue has been fixed on master.
This continuous integration check policy is enforced by Gitlab.
Dependency Management
21 Analytics uses tools that monitor 21 Travel Rule dependencies (libraries, OCI images, etc.) and open merge requests once newer versions of dependencies become available. After they pass continuous integration they are reviewed and can be confidently merged into master without introducing regressions or breaking the build. Updates that fail continuous integration are handled manually to ensure a quick update.
Having an efficient and effortless dependency management process enables 21 Analytics to constantly ship up-to-date software to its customers.
Security by Design
On-premises/Self-hosted Solution
21 Travel Rule is an on-premises/self-hosted solution, i.e. the software runs in the customer's data centre or cloud provider of the customer's choice.
21 Analytics has no means to access your deployment. In particular, 21 Analytics cannot access PII data, logging data or configuration data. In case of support requests the customer needs to grant access to 21 Analytics (e.g. via screen sharing during a video call) or share logging information (e.g. via upload to the 21 Analytics help desk) such that 21 Analytics can provide them with advice.
Secure Architecture
Separation of Concerns
21 Travel Rule has a micro service architecture that applies the separation of concerns 13 principle. APIs accessible from the public internet are exposed in different micro services than APIs that interface with the custodial system.
In the 21 Travel Rule reference deployment 14 those logical separations are enforced with a configuration that also splits them on a network level.
Principle of Least Privilege
21 Travel Rule services are stateless and use a database for persistence. They use database roles and permissions in accordance to the principle of least privilege 15 to refuse one microservice from accessing another's data.
Mitigation
Even when a memory-safe language like Rust is used disaster can strike nonetheless. 21 Travel Rule services are containerised to isolate them from the host system. Furthermore, 21 Travel Rule binaries are statically compiled, which allows them to run in empty containers. This significantly limits the attack surface in case of a successful memory-corruption exploit. For example, an attacker could not even gain access to libc or any binary useful for escalating the exploit chain like e.g. a shell.
Vendored Software
21 Travel Rule does not include vendored software components.
Open-source Software with Track Record
21 Travel Rule uses some off-the-shelf open-source software components with a high track record that are well-established in enterprise computing. The complete list of those components is as follows:
Resources
-
https://www.chromium.org/Home/chromium-security/memory-safety/ ↩
-
https://www.zdnet.com/article/microsoft-70-percent-of-all-security-bugs-are-memory-safety-issues/ ↩
-
https://security.googleblog.com/2021/02/mitigating-memory-safety-issues-in-open.html ↩
-
https://daniel.haxx.se/blog/2021/02/09/curl-supports-rustls/ ↩
-
https://security.googleblog.com/2021/04/rust-in-linux-kernel.html ↩
-
https://security.googleblog.com/2021/04/rust-in-android-platform.html ↩
-
https://www.abetterinternet.org/post/preparing-rustls-for-wider-adoption/ ↩
-
https://learn.microsoft.com/en-us/windows/dev-environment/rust/rust-for-windows ↩
-
https://engineering.fb.com/2021/04/29/developer-tools/rust/ ↩
-
https://aws.amazon.com/blogs/opensource/why-aws-loves-rust-and-how-wed-like-to-help/ ↩
-
https://aws.amazon.com/blogs/opensource/sustainability-with-rust/ ↩
-
https://en.wikipedia.org/wiki/Principle_of_least_privilege ↩
Supported Assets
21 Travel Rule is the industry leader for asset support. Leveraging the ISO 24165 DTI standard, 21 Travel Rule provides the largest asset coverage on the market.
General Asset Support
In general (transactions, Satoshi test proofs, etc.) 21 Travel Rule supports the full set of DTI digital assets.
Click to view the full list of supported digital assets (right click to download).
Asset Support for Digital Signature Proofs (AOPP)
Popular digital assets are supported for digital signature proofs (AOPP).
Click to view the full list of supported digital assets for digital signature proofs (right click to download).
For one-click automated signature proofs (AOPP), the support varies by wallet. For example, MetaMask does not support Solana. But once MetaMask adds support for Solana, it will work with 21 Travel Rule out of the box.
Note: Solana addresses can be proven only using Ledger and software wallets that support off-chain message signing.
Note:
solana-clifrom Solana labs produces signatures in base58 format. Please note that the AOPP Portal accepts only base64-encoded signatures, thus output fromsolana-clishould be re-encoded.
Release Communication & Lifecycle Plan
This section outlines the release cadence, versioning strategy, and communication protocols for 21 Travel Rule. Because 21 Travel Rule is licensed for use on Licensee-Controlled Infrastructure, this plan is designed to provide DevOps and Security teams with the predictability required for their internal Change Management processes.
Versioning Strategy
21 Travel Rule strictly adheres to Semantic Versioning (SemVer)
(MAJOR.MINOR.PATCH).
- MAJOR (
X.0.0): Introduces breaking changes, architectural overhauls, or significant changes to the data schema requiring database migrations. - MINOR (
0.X.0): Introduces new, backward-compatible features and enhancements. - PATCH (
0.0.X): Contains backward-compatible bug fixes, security patches, and performance improvements.
Release Cadence
To ensure stability and predictability for enterprise deployments, the 21 Travel Rule release schedule is bifurcated into Planned Releases and Out-of-Band (Ad-hoc) Releases.
Planned Releases (Major & Minor)
Major and significant Minor releases follow a bi-annual cadence. New versions are pushed to the container registry on:
- The beginning of Q2 (April)
- The beginning of Q4 (October)
Out-of-Band Releases (Ad-hoc Patches & Minor Updates)
To maintain compliance with DORA, NIS2, and general security best practices, Patch releases and urgent Minor updates are pushed out-of-band on an ad-hoc basis.
- Security Triggers: In cases where emergency patches are required to address vulnerabilities, they will be applied immediately.
- Non-Critical Triggers: Standard bug fixes and non-breaking feature enhancements are bundled and released continuously as available.
Because 21 Travel Rule adheres to strict SemVer and updates are never
forced, customers can safely configure their orchestration systems to
automatically pull the latest PATCH version within their current MAJOR.MINOR
track without risking unplanned disruption to their service availability.
Communication & Notification Plan
Because 21 Analytics does not push code directly to customer environments, proactive communication is critical. All updates are communicated to the Licensee's designated technical contacts.
| Release Type | Notice Period / SLA | Communication Channel | Included Artefacts |
|---|---|---|---|
| Planned Major/Minor (Q2/Q4) | 7 Days (approx. 5 Business Days) | Email to Technical Contacts | Release Notes, Changelog, Migration Guides |
| Out-of-Band Minor | At time of release | Email to Technical Contacts | Release Notes, Changelog |
| Out-of-Band Security Patch (Standard) | Within 3 Business Days | Email to Technical Contacts | Release Notes, Changelog |
| Out-of-Band Security Patch (Critical) | Within 24 hours of discovery | Urgent Security Advisory Email to Technical Contacts | CVE Mitigation Details |
Support Lifecycle and End-of-Life (EOL)
To allow customers ample time for internal testing, 21 Analytics supports multiple concurrent versions of 21 Travel Rule.
- Active Support: The current
MAJOR.MINORrelease receives all new features, bug fixes, and security patches. - Maintenance Support: The previous
MAJORrelease will receive backported critical security patches for a period of 6 months after the release of a newMAJORversion. - End of Life (EOL): Versions older than the defined Maintenance Support window will no longer receive updates.
Getting Started
Use the Compliance Dashboard to exchange Travel Rule messages, verify self-hosted wallet ownership, and review your compliance records. You can work directly in the dashboard or use it alongside an API integration to review automated activity.
First-time Setup
You need access to a deployed instance or the evaluation sandbox. For a new deployment, an administrator first creates a user account for you. Then,
- Log in and set your password.
- Configure your VASP for the workflows you will use: TRUST, TRP, email, and address ownership.
- For VASP-to-VASP transfers, review your counterparty VASPs and register your customers in the Travel Address Book.
Find Your Task
| I want to… | Start here |
|---|---|
| Send Travel Rule data to another VASP | Outgoing transaction |
| Review a received TRP message | Inbox |
| Import an incoming transfer | Incoming transaction |
| Check a pending TRP transaction | Waiting |
| Request or view a wallet ownership proof | Self-hosted wallet proofs |
| Manage customer account details | Travel Address Book |
| Export compliance records | Transactions or proofs |
| Review audit and activity trail | Transaction and proof event history or user audit logs |
Work with Your Records
Use filtering, sorting, and column visibility to find the records and fields you need. The transaction overview introduces Inbox, Waiting, and Archived tabs.
For the underlying workflows, see the Travel Rule overview and address ownership.
Login & User Account
Once 21 Travel Rule is installed and used for the first time, an admin needs to set up the compliance users on Keycloak. The admin should give you a temporary password and assign a username to the compliance user.
Initial Compliance User Setup
User Name and Password
Once the username and password are set up by the admin you can add them to the following form.
Login Password Update
Since the password provided by the admin is temporary you will be required to choose a new password for future use. This password can be modified later.
After this you will be automatically logged in and can log in with your new password after logging out. The documentation uses another user named 'Bitcoin Exchange AG' throughout.
Changing your Password
To change your password later, open the account menu in the upper-right corner
and select User Account. This opens your account-management dashboard in
Keycloak.
Navigate to "Signing in" under "Account security" in the left-hand menu.
Then click on the "Update" button, which will bring you to a form where you can change your password.
Configure Your VASP
Once logged in, you need to configure your own VASP. You can configure four different sets of attributes:
- TRUST
- TRP
- Address Ownership
Fill out those you feel are relevant to your VASP.
Open the account menu in the upper-right corner and select Configure VASP to
access these settings.
Saving the TRUST configuration also creates a TRP configuration if none exists yet, reusing the VASP name and LEI.
Once you have saved a configuration, you are encouraged to configure counterparty VASPs.
TRUST
You can view and edit your TRUST configuration under the 'TRUST' tab.
For initial setup, follow the TRUST Onboarding guide before saving these settings. It covers registration with TRUST, selecting the pre-production environment, and preparing the certificates and keys required below.
VASP Configuration Settings
VASP LEI
The LEI (Legal Entity Identifier) field is a unique identifier for your VASP, you can register for this on the Global Legal Entity Identifier Foundation (GLEIF) website or, for testing purposes, use the 21 Analytics LEI Generator. The owner of the VASP or a representative should present you with their LEI; however, the LEI registry is also public.
Note that this needs to match the value that you provided to TRUST during your onboarding. Your VASP's legal name is then taken from the bulletin board entry registered for this LEI, which is the name counterparties match against. Saving the settings fails if the bulletin board holds no such entry.
Default Counterparty Status
When VASPs are fetched from the TRUST network for the first time, they will receive this counterparty status. "Trusted" means you will be able to transact with them without manual vetting. "Blocked" means you will have to approve them on an individual basis after having performed counterparty due diligence.
TLS Server Identity (optional)
The TLS Server Identity is the PEM-encoded identity used by your TRUST PII server for incoming mTLS connections. It must include a certificate chain and exactly one private key, and the certificate must be valid for server authentication. During initial setup you must provide it; on later updates you can leave it empty to keep the existing server identity. See Obtaining Certificates for a basic certificate ordering guide.
mTLS Client Identity (optional)
The mTLS Client Identity is the PEM-encoded identity used for outgoing TRUST connections (for example to the TRUST bulletin board). It must include a certificate chain and exactly one private key, and the certificate must be valid for client authentication. During initial setup you must provide it; on later updates you can leave it empty to keep the existing client identity. If the certificate signals suitable combined client and server authentication, this may be identical to the Server Identity above. See Obtaining Certificates for a basic certificate ordering guide.
Decryption Key (optional)
The PII payloads other VASPs send to you are encrypted with the public key that you submitted to the TRUST bulletin board. Upload the corresponding private key here. This key is separate from the private keys in your TLS identities.
If you don't supply one in the initial configuration, a keypair will be
generated for you. Its public key must then be registered with TRUST before
counterparties can send payloads you can decrypt. If you already submitted a
public key during onboarding, supply its matching private key instead. On later
updates, leaving this field empty keeps the existing decryption key. Use
Copy Encryption Public Key to retrieve the public key after saving.
Beneficiary Name Matching
Choose how strict or lenient you want to be regarding beneficiary name matching. The options work as described for TRP and hold their own values here, independent of the TRP tab.
TRP
You can view and edit your TRP configuration under the 'TRP' tab.
VASP Configuration Settings
VASP Legal Name
The VASP Legal Name field is used to identify the VASP. For example, 'Tangany'.
VASP LEI
The LEI (Legal Entity Identifier) field is a unique identifier for your VASP, you can register for this on the Global Legal Entity Identifier Foundation (GLEIF) website or, for testing purposes, use the 21 Analytics LEI Generator. The owner of the VASP or a representative should present you with their LEI; however, the LEI registry is also public.
Note that you will not be able to change this value later. This is in order to not invalidate the due diligence performed by the counterparty, and to avoid service interruptions. If you wish to use TRP for a different entity, set up a separate 21 Travel Rule instance.
Signing Public Key
This key is generated once the TRP configuration data has been submitted. It is part of a public/private key that is randomly generated. The purpose of this is to add an additional layer of security by using digital signatures to authenticate TRP messages.
Chainalysis API Key (optional)
When a Chainalysis API Key is added then all the transaction ID's and cryptocurrency addresses are submitted to Chainalysis for risk analysis. You can contact your technical team to request the Chainalysis API Key.
mTLS Identity (optional)
The mTLS Identity is your VASP identity in PEM format used for mTLS
authentication with other TRP services. It must contain a certificate chain and
one private key. If you leave this empty, trpd keeps the existing identity, or
automatically generates a self-signed identity during the first configuration.
Synchronise Address Book to Address Directory
If active, this will send the new combinations of Wallet Address and Travel Address you add in the Address Book to the Address Directory so that other VASPs using TRP can easily find your customer's Travel Address.
Beneficiary Name Matching
Next, choose how strict or lenient you want to be regarding beneficiary name matching. Opt to ignore the letter case altogether or allow up to 2 mistakes in the spelling or case size. This flexibility will work on the counterparty VASP sending a transaction.
Enabling this option allows you to be lenient with names submitted to you. It has no effect on names you submit to others.
Ignore Case
The ignore case will allow the counterparty VASP sending the transaction to do this even if the beneficiary name matching the Travel Address cases doesn't match.
Name Mismatches Allowed
Name mismatch allows your counterparty to be more lenient with the names associated to one of your users' Travel Address. You can choose between one or two mistakes. Mistakes are counted using Levenshtein distance.
For example:
'cat' and 'cot' has distance 1 'cat' and 'calm' has distance 2
You can test it using the Levenshtein Distance Calculator.
If a counterparty VASP does not support any Travel Rule protocol, 21 Travel Rule can send an email with the relevant information instead. This makes you compliant with the Travel Rule nonetheless.
21 Analytics recommends configuring email. You can do that on the 'Email' tab. If you are unsure of this information, consult your IT team to complete the fields.
Setup guides for Google (Gmail) and Microsoft 365 Exchange Online are provided below.
Email Configuration Settings
SMTP Host
An SMTP server is used to send and receive emails. Your SMTP server is either managed by your IT department or an external company. Gmail is an example of a host. If you are unsure of this information, it is best to check with your IT team.
"From" Email Address
This is the email address you will use to send information from.
SMTP Port Number (optional)
This is the port number of your SMTP. The standard secure SMTP port is 587. As a common alternative, port 2525 is usually used. With this said, this field is optional and defaults to 587; if you are unsure, leave this empty.
SMTP Username (optional)
This is the name of the user on the SMTP server you want to use. This will usually be configured on the SMTP server by your IT team. It is required when using Microsoft OAuth 2.0.
SMTP Password (optional)
Once your IT team configures the SMTP username in the SMTP server configuration, a password will also be required unless you use Microsoft OAuth 2.0.
Use Microsoft OAuth 2.0 (optional)
Select this option to authenticate to Microsoft 365 Exchange Online without a mailbox password. This replaces the SMTP Password field with the Microsoft Entra Tenant ID, Client ID and Client Secret fields. See the Microsoft 365 setup guide for instructions on obtaining these values.
This option supports organisational Microsoft Entra accounts. It does not support personal Outlook.com accounts.
Select Connection Security (optional)
These can be one of three options:
- STARTTLS
- TLS
- OPTIONAL STARTTLS
The default value in 21 Travel Rule is usually STARTTLS, although 21 Travel Rule will automatically choose the option more appropriate for you. If issues do appear you can consult your IT team. Microsoft OAuth 2.0 requires STARTTLS.
Gmail and Google Workspace SMTP Setup
Objective
In this guide you will learn how to set up the SMTP settings for Gmail and
Google Workspace email accounts. Note, that Gmail and Google Workspace email
addresses don't necessarily end in @gmail.com. Hence, your company's email
accounts might be managed by Google even if the email address doesn't reveal it.
Instructions
Gmail SMTP Host
smtp.gmail.com
Gmail "From" email address
For the "From" email address, use the email address of your Gmail account.
Gmail SMTP Port Number
587
Gmail SMTP Username
The same full email used in the "From" email address must be used as the SMTP Username.
Gmail SMTP Password
To generate the SMTP Password, go to https://myaccount.google.com/apppasswords.
When creating the app password you will need to add a App Name. This name can be
anything you want; the following example uses 21 Travel Rule.
After you click create, a pop-up will appear with the app password. At the time of the writing the password is displayed with spaces. Copy the password and remove the white spaces from the password.
Note: Remember to remove the white spaces from the password when you copy it to the SMTP Password.
Gmail Connection Security
STARTTLS
Putting all of this together, the final Google configuration should look like this:
Microsoft 365 Exchange Online SMTP OAuth Setup
Microsoft OAuth Prerequisites
This guide configures 21 Travel Rule to send email from a Microsoft 365 Exchange Online mailbox using OAuth 2.0 client credentials. You need administrator access to Microsoft Entra and Exchange Online.
Register The Application
- Sign in to the Microsoft Entra admin center.
- Go to Entra ID → App registrations, select New registration and register a single-tenant application.
- On the application's Overview page, record the Directory (tenant) ID and Application (client) ID.
- Go to Certificates & secrets → Client secrets, create a client secret and immediately record its Value. The value is shown only once and is different from the secret ID.
- Go to API permissions and select Add a permission.
- Select APIs my organization uses and then Office 365 Exchange Online.
- Select Application permissions, add
SMTP.SendAsAppand grant admin consent for the tenant. Do not select a delegated or Microsoft Graph permission with a similar name.
Client secrets expire. Record their expiry and replace the value in 21 Travel Rule before it expires.
Configure Exchange Online
Microsoft security defaults block SMTP AUTH, including OAuth authentication. If security defaults are enabled, follow Microsoft's security defaults instructions to disable them and review the security implications with your administrator.
Enable Authenticated SMTP for the sender mailbox in the Microsoft 365 admin center:
- Go to Users → Active users and select the sender.
- Select Mail → Manage email apps.
- Select Authenticated SMTP and save the change.
Next, register the application in Exchange Online and grant access to the sender mailbox. Install PowerShell and run the following commands as an Exchange Online administrator:
Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization "<tenant-id>"
New-ServicePrincipal -AppId "<client-id>" -ObjectId "<enterprise-application-object-id>"
$servicePrincipal = Get-ServicePrincipal | Where-Object AppId -eq "<client-id>"
Add-MailboxPermission -Identity "<sender-email>" -User $servicePrincipal.Identity -AccessRights FullAccess
Add-RecipientPermission -Identity "<sender-email>" -Trustee $servicePrincipal.Identity -AccessRights SendAs -Confirm:$false
Use the Object ID from Entra ID → Enterprise applications → your
application → Overview for <enterprise-application-object-id>. Do not use
the Object ID from App registrations, which is a different identifier.
For more details, see Microsoft's OAuth instructions for SMTP.
Configure 21 Travel Rule
Enter the following values in the Email tab:
- SMTP Host:
smtp.office365.com - "From" Email Address: the sender email address granted above
- SMTP Port Number:
587 - SMTP Username: the same sender email address
- Use Microsoft OAuth 2.0: selected
- Microsoft Entra Tenant ID: the Directory (tenant) ID
- Microsoft Entra Client ID: the Application (client) ID
- Microsoft Entra Client Secret: the client secret Value
- Select Connection Security:
STARTTLS
Save the settings. 21 Travel Rule validates both token acquisition and the SMTP connection before applying the configuration.
Address Ownership
On the Address Ownership tab, you can configure Chainalysis risk analysis,
Satoshi Test settings, and AOPP portal customisation.
Chainalysis Key (optional)
When a Chainalysis API Key is added then all the cryptocurrency addresses from the proofs are submitted to Chainalysis for risk analysis. The risk results are shown in the Proofs Overview Table. You can contact your technical team to request the Chainalysis API Key. The risk scores can be found in the Self-hosted Wallet Proof Overview page.
Satoshi Test Time Limit
Set how much time the customer has to submit a transaction ID for a Satoshi test. Requests that reach the deadline without a submission expire and display as Failed. Submitted proofs still require verification via API or Compliance Dashboard.
Satoshi Test Base Amounts
Randomised amounts will be generated for each Satoshi Test based on the amounts input below. It is a best practice to set them to a fiat equivalent of about $1. It is possible to define base amounts for specific digital assets, all other assets will use default base value specified with "Other assets".
Use "Add Base Amount for Digital Asset" button to add new base amount entry.
NOTE: Default value of 1.0 coins is not always suitable for Satoshi test as it may be too large/small amount. So it is better to have sensible setup for all used digital assets.
Portal Customisation
The AOPP portal's appearance and text can be customised directly from the dashboard.
Language
To change the text displayed in the AOPP portal, download the current
lang.json file using the download button, edit the values to customise wording
or translate the portal into a different language, and upload the modified file.
The upload replaces the entire language configuration. Retain the complete set
of string keys for every language you offer; missing keys do not fall back to
English.
For more details, see Customising Portal Texts and Adding Additional Languages.
Theme
To change the visual appearance of the AOPP portal, download the current
theme.json file using the download button, adjust the values according to the
Ant Design theme API, and
upload the modified file. This allows you to customise colours, typography, and
other design tokens to match your branding.
For more details, see Customising the Portal Appearance.
Logo
To change the logo displayed in the AOPP portal, prepare your logo as an SVG file and upload it using the Logo field. The new logo will be displayed throughout the portal interface immediately after saving.
Counterparty VASPs
21 Travel Rule helps you to conduct and manage proper counterparty VASP due diligence as mandated by the Travel Rule. Once counterparty VASP due diligence is finalised, you should add the VASP to the list of trusted VASPs you want to maintain a business relationship with.
21 Travel Rule allows you to check and manage the list of trusted VASPs, sorted by the means of communication, which are TRUST, TRP and Email.
Add VASP
On the Counterparty VASPs page, click Add VASP in the upper-right corner to
open a dialog where you can select the protocol used to communicate with the
counterparty VASP.
Perform Counterparty Due Diligence
A thorough check of the counterparty VASP needs to be performed before adding it to the list of trusted counterparty VASPs. This is to ensure that counterparty due diligence is performed as per the Travel Rule's requirements, bearing in mind that the Travel Rule requires that a VASP has assessed the counterparty's anti-money laundering and counter-terrorism financing policies and regulatory status before initiating transactions.
Upon successful completion of counterparty due diligence, that VASP can be manually added to the list of trusted counterparty VASPs in case of email. In case of TRP and TRUST, the entry has automatically appeared and the VASP can be marked as trusted.
Add TRUST VASP
TRUST VASPs are automatically fetched from the TRUST counterparty discovery service. There is no manual action required.
Add TRP VASP
TRP VASPs auto-populate through Travel Address use. There is no manual action required.
Add Email VASP
As a fallback method, you can use Email; this is very simple to set up but comes with numerous drawbacks. Under the Email tab, you can see the following input data fields:
The required data for those fields is usually obtained during counterparty due diligence.
Name
Enter the counterparty's company name as incorporated in the commercial register.
Enter the email address of the counterparty.
TRUST
On the "TRUST" tab, you will find a table with a list of VASPs fetched from the TRUST network.
Click a row to open the counterparty's detail view. Click the History icon in
the title bar to view its events or export its event history. See
Event History.
This table displays the following information.
Table Columns Overview
Name / LEI
The legal name and Legal Entity Identifier (LEI) of the VASP.
Domain
The URL associated with the VASP.
Due Diligence Status
The due diligence status indicates whether this VASP has undergone the counterparty due diligence process and approved for transactions, or whether this is still pending. See Counterparty Due Diligence and Blocked VASPs for more information.
Created At
The time and date when the VASP was added to the Counterparty VASPs.
Actions: Block
For a currently trusted VASP, click Block in the Actions column. Its due
diligence status then changes to Blocked.
Blocked VASPs
After you have completed the counterparty due diligence process, the VASP can be marked as trusted on the TRUST counterparty VASPs detail view:
You can also block TRUST VASPs if you would like to cease all communication with them (this can be undone):
Removed VASPs
If a VASP is removed from the TRUST network, it will be marked as "Removed" in the Due Diligence column. Until it is included again, it will not be possible to exchange Travel Rule message with such a VASP.
TRP
On the "TRP" tab, you will find a table with a list of VASPs using the TRP protocol.
Click a row to open the counterparty's detail view. Click the History icon in
the title bar to view its events or export its event history. See
Event History.
This table displays the following information.
Table Columns Overview
Name / LEI
The legal name and Legal Entity Identifier (LEI) of the VASP.
Due Diligence Status
The due diligence status indicates whether this VASP has undergone the counterparty due diligence process and approved for transactions, or whether this is still pending. See Counterparty Due Diligence and Untrusted VASPs for more information.
API URL
The URL associated with the VASP. This is required to establish a connection through TRP (Travel Rule Protocol).
Signing Key
The signing key of the counterparty VASP. TRP will automatically receive this with auto-discovery.
Created At
The time and date when the VASP was added to the Counterparty VASPs.
Auto Approve
This switch indicates if the auto-approve feature is enabled. By clicking it you can disable or enable the auto-approval for the particular VASP.
When enabled, all transactions that come from the associated counterparty VASP will be automatically approved.
When disabled, transactions will need to be approved or declined either via API or by you manually in the GUI.
Actions: Block
For a currently trusted VASP, click Block in the Actions column. Its due
diligence status then changes to Untrusted and auto-approval is disabled.
Untrusted VASPs
When you receive a transaction from an unknown VASP, the 21 Travel Rule software automatically adds it to the counterparty VASP table with an Untrusted due diligence status.
The red badge on the Counterparty VASPs tab shows the number of new untrusted VASPs.
The corresponding transaction in your inbox remains blocked until the counterparty has undergone your due diligence process. Its Actions column shows an untrusted-counterparty warning instead of the normal transaction actions. The transaction detail view shows the same warning and links to the counterparty's trust action:
After you have completed the counterparty due diligence process, the VASP can be marked as trusted on the TRP counterparty VASPs detail view:
To stop all communication with a TRP VASP, open its detail view and click
Block this VASP. You can later reverse this action.
On the "Email" tab, you will find a table with a list of VASPs your team added choosing the Email protocol.
Click a row to open the counterparty's detail view. Click the History icon in
the title bar to view its events or export its event history. See
Event History.
This table supports customised filtering and sorting. See the filtering and sorting pages for more information.
This table contains the data introduced by you or someone with access to the account. To add additional VASPs you should use the Add VASP button stated previously and choose the Email tab. This table has the following columns:
Table Columns Overview
Name
List of the chosen VASP names.
Email Address
The email associated with the VASP name. This must be correct to establish communication between the counterparty VASP.
Actions
For currently trusted VASPs, there are two actions available under the Email tab:
Edit
In the row's Actions column, click Edit to change the VASP's email address.
Distrust
In the row's Actions column, click Distrust to block further email
communication with the counterparty VASP. Its status then changes to Revoked.
Mark Untrusted VASP as Trusted
For an untrusted VASP, click Mark Trusted in the Actions column to allow
communication with it again.
Travel Address Book
Under the Travel Address Book tab, you can view all your customers, as well as create Travel Addresses for them. It is recommended that this process be automated through the API or by preparing a script to integrate with your custodial system if you have one. The GUI is intended for low-volume customers. There are two main parts on this page:
Register A Customer
Note: 21 Analytics recommends automating this manual process using the API.
On the Address Book page, click Register a Customer above the customer table
to open the registration form.
Note that when TRUST is configured, the entries in the Address Book will be automatically synchronised to the TRUST Bulletin Board (also retroactively). 21 Travel users wishing to register their addresses alongside an ownership proof are required to use the
autod.registerCustodialUserGraphQL mutation. More details can be found on the TRUST flow documentation.
Here you can find the following input fields:
Natural or Legal Person
You can choose if your customer is a natural person (requiring a first and last name), or a legal person (requiring just a legal name).
Customer Account ID (optional)
If your VASP already has a custodial system in place, you can use this field to keep the IDs the same. If left empty, 21 Travel Rule will automatically generate an ID for your customer.
Wallet Address
The digital asset wallet address of the customer you want to register. An
example of this could be bc1q76lt4wgz4kr30mq3e9gayzgnmd0hy74v8ekrla for
Bitcoin or 0xcBfa884044546d5569E2abFf3fB429301b61562A for Ethereum.
If you wish to avoid address reuse, you can change the address for a particular customer and asset at any later time through the 21 Travel Rule GraphQL API.
Digital Asset
Here you can find a dropdown with all the digital assets supported by 21 Travel Rule. You should choose the asset associated with the customer's wallet address. If 21 Travel Rule does not yet support a digital asset you need, you can always contact the 21 Analytics team and request it.
Customers Overview
The customer table shows all the listed customers that were registered through the Register a Customer button.
Customer Details
The overview has one row per asset account, so a customer with accounts for multiple assets can appear more than once. Click any row for a customer to open their detail view and inspect all their asset accounts together.
The title shows the customer's name and ID. Below the shared Travel Address, the
account table shows each account's Asset, Wallet Address and Created At.
Use the copy buttons to copy the customer ID or Travel Address.
Click the History icon in the title bar to view this customer's events or
export their event history. See Event History.
Table Columns Overview
Name And ID
A list of the first and last name of your customers.
This is followed by the IDs associated with the registered customers. 21 Travel Rule might have created these if the field had been left empty. If you or your team added it, it is most likely an ID associated with your current custodial system.
Digital Asset
A list of the digital assets associated with the customers’ wallet addresses.
Wallet Address
This column shows a list of the wallet addresses used by your customers to generate the Travel Address.
Travel Address
A list of Travel Addresses automatically generated for your customers. This allows you to easily use the TRP protocol. You can use this when sending an Outgoing Transaction.
Created At
The time and date the asset account was registered. This column is hidden by default; use the table's column settings button to show it. The column can be sorted and filtered by date.
VASP-to-VASP Transactions
Select this screen to send Travel Rule data, review messages from counterparty VASPs, and import incoming transfers. Your customer's role determines the transaction type: Sent when your customer is the originator, or Received when your customer is the beneficiary.
21 Travel Rule exchanges and stores compliance data. Your wallet or custody system executes the blockchain transfer and credits the beneficiary. Approving a Travel Rule request does not move funds; confirming a TRP transaction reports a transfer that you have already executed.
Start with Your Task
Exchange Data with Counterparty VASPs
- Send funds to another VASP's customer: use Outgoing Transaction to send the Travel Rule data. Follow the TRP or TRUST or email walkthrough for your counterparty.
- Review a received message: TRP requests appear automatically in Inbox; received TRUST data appears in Archived. Open the existing record to review it.
- Import an incoming transfer: use Incoming Transaction when you need to enter the details yourself, for example when your customer supplies the originator information. You can request confirmation from the originator VASP by email, or save the record without sending a message. This form is not needed for transactions already received through TRP or TRUST.
Obtain Self-Hosted Wallet Ownership Proofs
For a transfer involving a self-hosted wallet, follow the wallet ownership proof workflow.
Follow a TRP Transaction
The tabs tell you who acts next:
- Inbox: your VASP needs to act.
- Waiting: the counterparty VASP needs to act.
- Archived: the TRP exchange has ended.
Inbox and Waiting contain only TRP transactions. Archived also contains TRUST, email, and imported transactions.
If a TRP transaction is blocked because the counterparty is unknown or untrusted, complete counterparty due diligence before proceeding.
Outgoing Transactions
Your customer is the originator, and the transaction type is Sent. After you send the request, it follows these steps in your dashboard:
| Tab | Status | What happens next |
|---|---|---|
| Waiting | Pending | The beneficiary VASP reviews your request. Approval moves it to Inbox. |
| Inbox | Approved | Your VASP executes the blockchain transfer, then uses Confirm to submit its transaction ID. This moves it to Archived. |
| Archived | Executed | The TRP exchange is complete. |
An approved outgoing transaction appears in Inbox because your VASP must
confirm or cancel it. If you will not execute the transfer, use
Cancel Transaction; it moves to Archived as Cancelled. If the beneficiary
VASP declines the request, it moves directly from Waiting to Archived as
Declined.
Incoming Transactions
Your customer is the beneficiary, and the transaction type is Received. A request from the originator VASP appears automatically in your dashboard:
| Tab | Status | What happens next |
|---|---|---|
| Inbox | Pending | Your VASP reviews the data, then uses Approve to move the request to Waiting. |
| Waiting | Approved | The originator VASP executes the blockchain transfer and confirms its transaction ID. This moves it to Archived. |
| Archived | Executed | The TRP exchange is complete. Check receipt of funds in your wallet or custody system. |
To reject an incoming request, use Decline; it moves from Inbox to Archived as
Declined. If the originator VASP cancels after your approval, it moves from
Waiting to Archived as Cancelled.
See the Inbox actions guide for the action forms, or the TRP flow for the exchange between both VASPs.
Protocols and the Blockchain Transfer
- TRP: send the request before executing the blockchain transfer. Once the beneficiary VASP approves it, the originator VASP transfers the funds and confirms the blockchain transaction ID. The confirmation completes the TRP exchange.
- TRUST: the outgoing form requires the transaction ID of an executed blockchain transfer. Successfully sent and received TRUST messages appear directly in Archived, without the TRP approval and confirmation steps. See the TRUST flow.
- Email: send data for an executed transfer, or request confirmation of the beneficiary details before executing it. For an incoming transfer, you can request confirmation of the originator details before crediting your customer. Email records appear directly in Archived; follow up on replies in email. See the email flow.
An archived record does not by itself establish that funds arrived or that your compliance checks are complete. Email records are labelled Executed even when you requested confirmation before transferring funds. Incoming transfers saved without email are labelled Registered. Check your custody records and the counterparty's response before proceeding with your customer.
Available Actions on Tabs
Each transaction tab provides the following controls:
- Search finds transactions matching text
across multiple transaction properties. Enter a term in
Search for any transaction propertyand clickSearch. Click the cross in the search field to clear it. - Outgoing Transaction starts a transaction for which your customer is the originator.
- Incoming Transaction records a transaction for which your customer is the beneficiary.
- Export Transactions downloads the rows matching the current filters.
- Pagination moves between pages when a table contains more than 15 rows.
Use filtering and sorting to find records. Open a transaction's details to review its data or event history.
Outgoing Transaction
Note: 21 Analytics recommends automating this manual process using the API.
On any transaction tab, click Outgoing Transaction when your customer is the
originator of the transaction. 21 Travel Rule then notifies your counterparty
VASP about the transaction, including all required Travel Rule data.
Enter a Travel Address or wallet address in the same form. 21 Travel Rule uses TRP for a Travel Address or a wallet address found in the TRP directory. For other wallet addresses, it looks for an owner on TRUST. If neither protocol finds a counterparty VASP, you can send the notification by encrypted email.
Choose a Workflow
Follow the walkthrough for the counterparty selection in your form:
- TRP or TRUST: keep
Auto-detect VASPselected to discover the counterparty from the Travel Address or wallet address. - Email: select a specific counterparty VASP to send an encrypted email, either directly or after automatic discovery fails.
Each walkthrough follows all three form stages in order: Beneficiary Information, Digital Asset, and Originator Information. It also explains what happens after submission.
Outgoing via TRP or TRUST
Use this walkthrough to send Travel Rule data with Auto-detect VASP. The same
form handles TRP and TRUST. For a manually selected email counterparty, use the
email walkthrough.
On any transaction tab, click Outgoing Transaction.
1. Beneficiary Information
Select Natural person and enter the beneficiary's first and last name, or
select Legal person and enter its legal name.
In Travel Address / Wallet Address, enter the
Travel Address supplied by
the beneficiary VASP, or the beneficiary's wallet address. When using a Travel
Address, the beneficiary's name must match the associated address book entry.
Leave Counterparty VASP set to Auto-detect VASP. 21 Travel Rule looks up the
counterparty through TRP or TRUST when you submit the completed form.
Click Next to continue to Digital Asset.
2. Digital Asset
Select the Digital Asset and enter the Amount to be transferred.
The Transaction ID (TxID) identifies the transaction on the blockchain:
- For a TRP request before execution, leave it empty. You submit the ID when confirming the transfer after the counterparty approves it.
- For a TRUST notification, enter the ID of the executed transaction. If TRUST is selected during discovery and the ID is missing, the form returns to this step and asks you to provide it.
Click Next to continue to Originator Information.
3. Originator Information
Select your customer in Originator Name. The options come from the
address book; the customer must have an account for
the selected digital asset.
Enter Customer Identification, such as a passport number, phone number, date
of birth or account number. If the customer is a legal person, also enter
Originator Legal ID.
Fill in the customer's postal address as recorded in their identity documents:
Street NameandBuilding Number, orAddress Line. TRP requires either the street and building number together or an address line.Postal Code,CityandCountry.
Click Submit to discover the counterparty and send the Travel Rule data.
After Submission
For a TRP request, follow its progress in Waiting. If the counterparty VASP is unknown, you are first directed to its details to complete counterparty due diligence.
After the counterparty approves the request, it appears in your Inbox. Execute
the blockchain transfer, then use
Confirm to submit the transaction
ID. If you decide not to execute it, use Cancel Transaction instead.
A successfully submitted TRUST notification appears in Archived.
Counterparty Not Found
If neither protocol finds a counterparty VASP, the form returns to Beneficiary
Information. If email is configured, Auto-detect VASP is removed and the
counterparty selection is cleared. Select the beneficiary's VASP and continue
with the email walkthrough.
If email is not configured, first configure email and add the counterparty VASP.
Outgoing via Email
Use this walkthrough to send Travel Rule data by encrypted email to a selected counterparty VASP. You can choose email directly or use it when automatic TRP and TRUST discovery cannot find the counterparty.
Before starting, configure email and
add the counterparty VASP.
On any transaction tab, click Outgoing Transaction.
1. Beneficiary Information
Select the beneficiary's VASP in Counterparty VASP to use encrypted email. The
dropdown lists your trusted
email counterparties.
Select Natural person and enter the beneficiary's first and last name, or
select Legal person and enter its legal name and legal ID. Enter the
beneficiary's wallet address in Travel Address / Wallet Address.
If automatic discovery returned you to this step, select the counterparty and review the beneficiary details before continuing.
Click Next to continue to Digital Asset.
2. Digital Asset
Select the Digital Asset and enter the Amount.
Has the Transaction Been Executed?
Choose the option that matches the transaction's current state:
- Yes: enter the blockchain
Transaction ID (TxID). The email shares the Travel Rule data with the beneficiary VASP. - No: the transaction ID field is hidden. The email asks the beneficiary VASP to confirm the Travel Rule data before you execute the transaction.
You can also add an optional Comment. Click Next to continue to Originator
Information.
3. Originator Information
Enter your customer's details:
- For a
Natural person, enterFirst NameandLast Name. - For a
Legal person, enterLegal NameandOriginator Legal ID. - Enter
Customer Identification, such as a passport number, phone number, date of birth or account number. - Enter the customer's
Postal Code,CityandCountryas recorded in their identity documents.Street Name,Building NumberandAddress Lineare optional for email.
Click Submit to send the encrypted email. The transaction appears in
Archived.
If you requested confirmation before execution, wait for the counterparty's email confirming the beneficiary details before proceeding with the blockchain transfer. See the Email Flow for the full exchange between VASPs.
Incoming Transaction
Note: 21 Analytics recommends automating this manual process using the API.
On any transaction tab, click Incoming Transaction to import a transfer for
which your customer is the beneficiary. Use this when you need to enter the
details yourself, for example when your customer supplies the originator
information. Messages received through TRP or TRUST already create transaction
records; review those records instead of entering them again.
You can ask the originator VASP to confirm the details by email before crediting your customer, or save the record without sending an email. See Ask For Confirmation Email.
The form contains three stages:
1. Beneficiary Information
As in the Outgoing Transaction form, the first step collects the beneficiary information:
Fields Overview (Beneficiary Information)
First Name (Natural Person)
The first name of the person receiving the digital asset. This name should match the one found in the person's passport or legal identity document.
Last Name (Natural Person)
The last name of the person receiving the digital asset. This name should match the one found in the person's passport or legal identity document.
Legal Name (Legal Person)
The legal name of the person receiving the digital asset.
Legal ID (Legal Person)
The legal ID associated with the legal name of the person receiving the digital asset.
Wallet Address
The wallet address of the person receiving the digital asset. An example of this
could be bc1phdhfqtjwwweu3xdsw40mje5g48cgnnks6u00ajaf7xh3jn8vtk3srps2sp for
Bitcoin or 0xcBfa884044546d5569E2abFf3fB429301b61562A for Ethereum.
Ask For Confirmation Email
When this checkbox is ticked this sends an email that asks the originator to confirm the correctness of all submitted travel rule and transaction details. After receiving the confirmation from the originator you can credit the transaction's beneficiary. The transaction is archived in 21 Travel Rule and available for future reference in the Compliance Dashboard's archive transactions overview.
When this checkbox is left unticked no emails are sent but the transaction details are immediately archived.
2. Digital Asset
Fields Overview (Digital Asset)
Digital Asset
Here you can find a dropdown with all the digital assets supported by 21 Travel Rule. You should choose the asset used in the transaction. 21 Travel Rule supports the complete list of ISO24165 DTIs (Digital Token Identifiers). If 21 Travel Rule does not yet support a digital asset you need, you can always contact the 21 Analytics team and request it.
Amount
The amount of the digital asset selected for the transaction.
Transaction ID (TxID)
A digital asset transaction will create a Transaction ID for this particular transaction in the blockchain. You can usually find these either on your wallet or on a blockchain explorer.
Comment (optional)
An optional comment about the transaction.
3. Originator Information
Fields Overview (Originator Information)
First Name (Natural Person, Originator)
The first name of the person sending the digital asset. This name should match the one found in the person's passport or national identity document.
Last Name (Natural Person, Originator)
The last name of the person sending the digital asset. This name should match the one found in the person's passport or national identity document.
Legal Name (Legal Person, Originator)
The legal name of the person sending the digital asset.
Originator Legal ID (Legal Person)
The legal ID associated with the legal name of the person sending the digital asset.
Customer Identification
This is a data point that allows to uniquely identify your customer. Typically a Passport Number, Phone Number, Date of Birth or Bank Account Number.
Originator VASP LEI (optional) (Without Email)
The VASP LEI (Legal Entity Identifier) of the VASP sending the digital asset, this will most likely be your VASP LEI. These are public and can be found in the Global Legal Entity Identifier Foundation (GLEIF) website. This field is optional.
Originator VASP Name (Without Email)
The name of the VASP sending the transaction. A dropdown will appear with all the VASPs added to using the email protocol in Counterparty VASPs. You can also add a different one if that one doesn't appear.
Upload Visual Proof (optional) (Without Email)
Allows you to add additional proof by uploading a screenshot or screen recording of the transaction. This field is optional. The Upload Visual Proof button is only displayed if the Ask For Email Confirmation checkbox has not been ticked.
Counterparty VASP
A dropdown with a list of available Beneficiary VASPs reachable via email. You
can add additional beneficiary VASPs on the
Counterparty VASPs page. The
Beneficiary VASP dropdown is only displayed if the
Ask For Email Confirmation checkbox has been
ticked.
Under address you can find the following fields:
Street Name (optional)
The name of the street as found on the passport or national identity document of the person sending the transaction. This field is optional.
Building Number (optional)
If an address line or street name was added this will be the number of the building found on the passport or national identity document.
Address Line (optional)
The address line as found on the passport or national identity document of the person sending the transaction. This field is optional.
Postal Code
The postal code of where the originator customer resides, as found on their passport or national identity document.
City
The city of where the originator customer resides, as found on their passport or national identity document.
Country
The country of where the originator customer resides, as found on their passport or national identity document.
Export Transactions
Click Export Transactions to download the transactions matching the current
filters as an .xlsx (Excel) file. You can open the file in spreadsheet
software to search, sort and further process the data.
The 21 Analytics team prioritised the export functionality because it enables compliance officers to use software they are familiar with and provides an additional storage method. Please contact the 21 Analytics team if you have any extra functionality requirements.
Pagination
Each transaction table displays up to 15 rows. Pagination controls appear below the table on the left. Select a page number or use the arrow buttons to move to the previous or next page.
The selected page number is highlighted. An arrow is disabled when there is no additional page in that direction, such as the previous-page arrow while you are viewing the first page.
Next to the controls, a result count such as 1-15 of 42 shows the rows on the
current page and the total number of rows matching the current filters.
Inbox
Inbox contains TRP transactions awaiting action from your VASP: received requests to approve or decline, and approved outgoing requests to confirm or cancel. See the transaction lifecycle to understand how these actions move a transaction between tabs.
Open a row to inspect the details, or use its action icons to proceed.
Transactions Inbox Overview
Detailed Transaction
Inbox Transactions Overview
The Inbox Transactions overview in 21 Travel Rule lets you easily navigate through all transactions that require an action from your side.
Inbox Transactions Table Overview
Each row contains the following fields:
Type
Status
Beneficiary
Originator
Originator VASP
Digital Asset
Amount
Date Created
Actions
Type
The inbox-tray icon represents Received, while the paper-plane icon represents Sent. Hover over either icon to display the transaction type.
When the Type has the Received value, a counterparty VASP has sent you, the compliance officer, a transaction. This transaction is then waiting for you to Approve it or Decline it.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP through the Outgoing Transaction button, and the counterparty VASP has then approved the transaction. This is then waiting for the last step, which is for you to Confirm or Cancel the transaction.
Status
Can be either Pending or Approved.
Once a counterparty VASP has sent a transaction to you, the transaction in your inbox will go into a Pending status until you Approve or Decline the transaction. The status of Pending is of Type Received when it is in the inbox.
If, on the other hand, you have sent a transaction to a counterparty VASP through the Outgoing Transaction button and the counterparty VASP has clicked Approve, the Status of Approved will appear in your inbox for that particular transaction. The Status of Approved is of Type Sent when it's in the inbox.
Beneficiary
The name and surname, as registered in a legal identity document of the person receiving the transaction.
Originator
The name and surname, as registered in a legal identity document of the person sending the transaction.
Originator VASP
The VASP of the customer who sent the transaction.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the Originator to the Beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum.
Date Created
The time and date the transaction was Sent or Received. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Actions
The Actions column contains a check mark and a cross. For a received
transaction, these represent Approve and Decline. For a sent transaction
that the counterparty VASP approved, they represent Confirm and
Cancel Transaction. Hover over an icon to display its action name.
Approving or declining a received transaction opens a form where you can optionally add a comment. Approval records the receiver's decision and moves the transaction to the waiting table until the sender confirms the blockchain transfer. It does not require a blockchain transaction ID. Declining moves the transaction to the archived table.
For an approved sent transaction, Confirm opens a form where the sender
submits the blockchain transaction ID after executing the transfer. Submitting
the ID confirms the transfer to the receiver and moves the transaction to the
archived table. Cancelling opens a form where you can optionally add a comment
and then moves the transaction to the archived table.
Detailed Transaction
When you click on one of the rows in the Transactions Overview table, a pop-up will display.
Click the History icon in the title bar to view this transaction's events or
export its event history. See Event History.
Transaction Details
Travel Transaction ID
At the top left of the pop-up, you can find a title. This title shows the ID of the transaction in 21 Travel Rule. This should not be confused with the blockchain transaction ID. This is used to find specific transactions from all your list of transactions.
Transaction Status
Can be either Pending or Approved.
Once a counterparty VASP has sent a transaction to you, the transaction in your inbox will go into a Pending status until you Approve or Decline the transaction. The status of Pending is of Type Received when it is in the inbox.
If, on the other hand, a counterparty VASP has sent you a transaction and you have approved it, the Status of Approved will appear in your waiting table for that particular transaction. The Status of Approved is of Type Received when it's in the waiting table.
Transaction Type
Can be either Sent or Received.
When the Type has the Received value, it means a counterparty VASP has sent you, the compliance officer, a transaction. This transaction is then waiting for you to Approve it or Decline it.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP through the Outgoing Transaction button, and the counterparty VASP has then approved the transaction. This is then waiting for the last step, which is for you to Confirm or Cancel the transaction.
For a better understanding of the whole workflow, see: TRP.
Protocol
The protocol used for the transaction to be compliant.
Date Created
The time and date the transaction was Sent or Received. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the originator to the beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum. When fiat values have been supplied for the transaction, they are shown alongside the digital asset amount with their currency codes. Multiple providers and currencies can be displayed. Hover over a fiat value to see its provider and the date and time it was recorded.
Beneficiary Name
The first and last name of the customer who is receiving the digital asset. If you have configured the beneficiary name matching, the beneficiary name displays a matching indicator when a received name falls within the configured typo tolerance. Hover over the indicator to confirm that the name was matched according to your settings.
Beneficiary VASP Name
The name of the VASP of the customer receiving the digital asset. This name is associated with a LEI.
Beneficiary VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is receiving the digital asset.
Beneficiary Wallet Address
The Wallet Address of the customer receiving the digital asset of the transaction. Clicking on it opens an external explorer in a new tab. The destination depends on the digital asset.
Originator Name
The first and last name of the customer sending the digital asset.
Originator VASP Name
The name of the VASP of the customer sending the digital asset. This name is associated with a LEI.
Originator VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is sending the digital asset.
Originator Internal Account Number
An account number to identify the customer sending the transaction. Each customer should have their own Account Number.
Originator Address
The Address where the customer resides. This can be found on their passport or country ID.
Actions
For a transaction received from a counterparty VASP, the available actions are
Approve and Decline.
Approve
Click Approve to notify the counterparty VASP and continue the transaction
verification.
Decline
Click Decline to stop the transaction.
For a transaction that you sent and the counterparty VASP approved, the
available actions are Confirm and Cancel Transaction.
Confirm
Click Confirm to finish the verification process.
Cancel Transaction
Click Cancel Transaction to stop the transaction.
Export
Click the download-arrow icon labelled Export to Excel to download an .xlsx
(Excel) file containing the data for this transaction.
Download Report
Click the document icon labelled Download Report to download a .docx report
template for the transaction.
Waiting
The Waiting section provides an overview of transactions that are currently pending some action by the counterparty VASP. Here, you can review those transactions, access detailed information, and monitor their progress until further action is taken by the other VASP. Currently, only TRP transactions appear here.
Transactions Waiting Overview
Detailed Transaction
Waiting Transactions Overview
The Waiting Transactions overview in 21 Travel Rule lets you easily navigate through all transactions requiring an action from the counterparty VASP you are communicating with.
Waiting Transactions Table Overview
Each row contains the following fields:
Type
Status
Beneficiary
Originator
Originator VASP
Digital Asset
Amount
Date Created
Counterparty Action
Type
The inbox-tray icon represents Received, while the paper-plane icon represents Sent. Hover over either icon to display the transaction type.
When the Type has the Received value, a counterparty VASP has sent you, the compliance officer, a transaction. You then approved this transaction and are now waiting for the counterparty VASP to either Confirm or Cancel.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP through the Outgoing Transaction button and are waiting for the counterparty VASP to either Approve or Decline the transaction.
Status
Can be either Pending or Approved.
Once you have sent a transaction to a counterparty VASP, the waiting transaction will go into a Pending status until the counterparty VASP Approves or Declines the transaction. The status of Pending is of Type Sent when it's waiting.
If you have received a transaction from a counterparty VASP and then Approved, the Status of Approved will appear, and the transaction will be in a waiting state until the counterparty VASP either Confirms or Cancels the transaction. The Status of Approved is of Type Received when it's waiting.
Beneficiary
The name and surname, as registered in a legal identity document of the person receiving the transaction.
Originator
The name and surname, as registered in a legal identity document of the person sending the transaction.
Originator VASP
The VASP of the customer who sent the transaction.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the Originator to the Beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum.
Date Created
The time and date the transaction was Sent or Received. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Counterparty Action
Can be either Requires Approval or Requires Confirmation.
If Requires Approval shows, that means you sent a transaction and the transaction is waiting for the counterparty VASP to either Approve or Decline the transaction.
If, on the other hand, Requires Confirmation appears on this field that means that the counterparty VASP sent you a transaction and you then approved it. Now the transaction is waiting for the last step which is for the counterparty VASP to either Confirm or Cancel the transaction.
Detailed Transaction
A pop-up will display when you click on one of the rows in the Transactions Overview table.
Click the History icon in the title bar to view this transaction's events or
export its event history. See Event History.
Transaction Details
Travel Transaction ID
At the top left of the pop-up, you can find a title. This title shows the ID of the transaction in 21 Travel Rule. This should not be confused with the blockchain transaction ID. This is used to find specific transactions from all your list of transactions.
Transaction Status
Can be either Pending or Approved.
Once you have sent a transaction to a counterparty VASP, the transaction will go into a Pending status on your waiting table until it gets Approved or Declined by the counterparty VASP. The status of Pending is of Type Sent when it's waiting.
If you have sent a transaction to a counterparty VASP through the Outgoing Transaction button and the counterparty VASP has clicked Approve, the Status of Approved will appear in your inbox for that particular transaction. The Status of Approved is of Type Sent when it's in the inbox.
Transaction Type
Can be either Sent or Received.
When the Type has the Received value, it means a counterparty VASP has sent you, the compliance officer, a transaction, you have then approved this and its waiting for the last step which is for the counterparty VASP to either Confirm or Cancel the transaction.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP, and the counterparty VASP has to now either Approve or Decline the transaction. Until then the transaction will be on the waiting table.
For a better understanding of the whole workflow, see: TRP.
Protocol
The protocol used for the transaction to be compliant.
Date Created
The time and date the transaction was Sent or Received. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the Originator to the Beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum. When fiat values have been supplied for the transaction, they are shown alongside the digital asset amount with their currency codes. Multiple providers and currencies can be displayed. Hover over a fiat value to see its provider and the date and time it was recorded.
Beneficiary Name
The first and last name of the customer who is receiving the digital asset. If you have configured the beneficiary name matching, the beneficiary name displays a matching indicator when a name received from the Originator falls within the configured typo tolerance. Hover over the indicator to confirm that the name was matched according to your settings.
Beneficiary VASP Name
The name of the VASP of the customer receiving the digital asset. This name is associated with a LEI.
Beneficiary VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is receiving the digital asset.
Beneficiary Wallet Address
The Wallet Address of the customer receiving the digital asset of the transaction. Clicking on it opens an external explorer in a new tab. The destination depends on the digital asset.
Originator Name
The first and last name of the customer sending the digital asset.
Originator VASP Name
The name of the VASP of the customer sending the digital asset. This name is associated with a LEI.
Originator VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is sending the digital asset.
Originator Internal Account Number
An account number to identify the customer sending the transaction. Each customer should have their own Account Number.
Originator Address
The Address where the customer sending the transaction resides. This can be found on their passport or country ID.
Export
Click the download-arrow icon labelled Export to Excel to download an .xlsx
(Excel) file containing the data for this transaction.
Download Report
Click the document icon labelled Download Report to download a .docx report
template for the transaction.
Archived
The Archived section provides access to transactions that are no longer active, such as those that have been completed or cancelled. Use this section as a historical audit trail to quickly revisit prior decisions, export evidence, and verify why specific transactions reached their final state.
Archived Transactions Overview
Detailed Transaction
Archived Transactions Overview
The Archived Transactions overview in 21 Travel Rule lets you easily navigate through all transactions that have gone through one of the protocols supported by 21 Travel Rule.
Archived Transactions Table Overview
Each row contains the following fields:
Type
Status
Beneficiary
Originator
Originator VASP
Digital Asset
Amount
Finalized At
Type
The inbox-tray icon represents Received, while the paper-plane icon represents Sent. Hover over either icon to display the transaction type.
When the Type has the Received value, a counterparty VASP has sent you, the compliance officer, a transaction. This transaction was either Executed, Declined, Cancelled or Registered.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP through the Outgoing Transaction button. This transaction was either Executed, Declined or Cancelled.
Status
On the archived tab there are a few possible statuses:
For TRP, Executed means the originator VASP has confirmed the blockchain transaction ID. TRUST and email records also show Executed, even for emails requesting confirmation before a transfer. This status alone does not confirm receipt of funds or completion of your compliance checks. See the transaction lifecycle.
If the transaction has the status of Declined this means the beneficiary VASP has decided to not allow the transaction to go through. This could be due to KYC checks not meeting the requirements expected by the beneficiary VASP.
If the transaction has the status of Cancelled this means the beneficiary VASP approved it, but then the originator decided to cancel the transaction from going through at the last stage of the handshake. This could be due to KYC checks ran on the beneficiary VASP not being validated.
Last of all, as a fallback to the viable protocols, transactions can be manually archived. This might not be fully compliant in some cases but it's useful to keep for future references or for countries that request less information. This will go into a status of Registered.
Beneficiary
The name and surname, as registered in the passport or national identity document of the person receiving the transaction.
Originator
The name and surname, as registered in the passport or national identity document of the person sending the transaction.
Originator VASP
The VASP of the customer who sent the transaction.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the Originator to the Beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum.
Finalized At
The time and date the transaction was either Executed, Declined, Cancelled or Registered. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Detailed Transaction
When you click on one of the rows in the Transactions Overview table, a pop-up will display.
Click the History icon in the title bar to view this transaction's events or
export its event history. See Event History.
Transaction Details
Travel Transaction ID
At the top left of the pop-up, you can find a title. This title shows the ID of the transaction in 21 Travel Rule. This should not be confused with the blockchain transaction ID. This is used to find specific transactions from all your list of transactions.
Transaction ID
This field is only visible if the transaction is of type Received and was Executed or Registered. This is the transaction ID generated on blockchain for this particular transaction. This can be found on the wallets of the originator or beneficiary as well as in a blockchain explorer. Clicking on it will redirect to the Blockbook Block Explorer where you will be able to see the details of this particular transaction.
Transaction Status
Can be either Executed, Declined, Cancelled or Registered.
For TRP, Executed means the originator VASP has confirmed the blockchain transaction ID. TRUST and email records are also labelled Executed, including emails requesting confirmation before a transfer. Check your custody records and complete your compliance checks; this status alone does not establish that funds arrived or that the transaction is compliant.
If the transaction has the status of Declined this means the beneficiary VASP has decided to not allow the transaction to go trough. This could be due to KYC checks not meeting the requirements expected by the beneficiary VASP.
If the transaction has the status of Cancelled this means the beneficiary VASP approved but then the originator decided to cancel the transaction from going through at the last stage of the handshake. This could be due to KYC checks ran on the beneficiary VASP not being validated.
Last of all, as a fallback to the viable protocols, transactions can be manually archived, this might not be fully compliant in some cases but it's useful to keep for future references or for countries that request less information. This will go into a status of Registered.
Transaction Type
Can be either Received or Sent.
When the Type has the Received value, it means a counterparty VASP has sent you a transaction or you have manually archived a transaction.
When the Type has the Sent value, it means you have sent a transaction to a counterparty VASP through the Outgoing Transaction button, and then the transaction was either approved, declined or cancelled.
For a better understanding of the whole workflow, see: TRP.
Protocol
The protocol used to check if the transaction was compliant.
Date Created
The time and date the transaction was Sent or Received. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Finalized At
The time and date the transaction was either Executed, Declined, Cancelled or Registered. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Digital Asset
Shows the symbol, name and currency code of the Digital Asset Sent or Received in the transaction.
Amount
The amount of a particular Digital Asset sent from the Originator to the Beneficiary. 21 Travel Rule supports the entire 18 decimals for Ethereum. When fiat values have been supplied for the transaction, they are shown alongside the digital asset amount with their currency codes. Multiple providers and currencies can be displayed. Hover over a fiat value to see its provider and the date and time it was recorded.
Comment
For a received transaction, the GUI allows you to add a comment when approving or declining it. Approval comments are internal. For TRP transactions, a decline comment is included in the rejection sent to the originator VASP.
Risk Score
This field will appear if you setup a risk analysis tool such as Chainalysis, and the transaction is of type Received and was Executed using TRP. For this you need to add the Chainalysis API key in the configure your VASP page.
Beneficiary Name
The first and last name of the customer who is receiving the digital asset. If you have configured the beneficiary name matching, the beneficiary name displays a matching indicator when a received name falls within the configured typo tolerance. Hover over the indicator to confirm that the name was matched according to your settings.
Beneficiary VASP Name
The name of the VASP of the customer receiving the digital asset. This name is associated with a LEI.
Beneficiary VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is receiving the digital asset.
Beneficiary Wallet Address
The Wallet Address of the customer receiving the digital asset of the transaction. This field will only show up if the transaction is of type Received and was Executed or Registered. Clicking on it opens an external explorer in a new tab. The destination depends on the digital asset.
Originator Name
The first and last name of the customer sending the digital asset.
Originator VASP Name
The name of the VASP of the customer sending the digital asset. This name is associated with a LEI.
Originator VASP LEI
The LEI (Legal Entity Identifier) of the VASP who is sending the digital asset.
Originator Internal Account Number
An account number to identify the customer sending the transaction. Each customer should have their own Account Number.
Originator Address
The Address where the customer resides. This can be found on their passport or country ID.
Export
Click the download-arrow icon labelled Export to Excel to download an .xlsx
(Excel) file containing the data for this transaction.
Download Report
Click the document icon labelled Download Report to download a .docx report
template for the transaction. This action is not available for transactions that
used the email protocol.
View Visual Proof
For a manually archived transaction, click View Visual Proof to open the
uploaded file.
Self-hosted Wallet Proofs
Use Self-hosted Wallet Proofs to request evidence for a customer's control over a wallet address, track their response, and review the result. Choose a method that works with the customer's wallet and your verification process. For the underlying concept, see address ownership.
Choose a Proof Method
| Method | Compatibility | Customer effort | Staff/API involvement and completion |
|---|---|---|---|
| Digital signature (AOPP) | A supported asset and a wallet that can sign the required message | Open the portal link and sign a message; no transfer of funds | Request and share the link. 21 Travel Rule checks the signature automatically and marks a valid proof Verified. |
| Satoshi test | Any supported digital asset with a wallet that can send from the address being verified | Send the requested amount, pay network fees, and submit the transaction ID before the deadline | A compliance officer or custody integration checks the transfer and approves it to mark the proof Verified. |
| Visual proof | Any supported digital asset; the wallet must let the customer show evidence of address ownership | Provide screenshots or a screen recording | Review the evidence and upload it alongside the address. The record displays as Verified after upload. |
Use AOPP when the asset and wallet support message signing. A Satoshi test is an alternative when signing is unavailable and the customer can send a transfer. Use visual proof when your process calls for a staff review of screenshots or recordings. Check supported assets, including the separate list for digital signatures, before requesting evidence.
Request and Verify Evidence
- Prepare the request. Have the customer ID, digital asset, and wallet address ready. AOPP can also collect the wallet address from the customer. For Satoshi tests, review the time limit and base amounts and provide a deposit address for the test transfer.
- Collect evidence. Click
AOPP Portal LinkorSatoshi Test Link, fill in the form, and send the generated link to your customer. Follow the AOPP Portal or Satoshi Proof Portal walkthrough. For visual evidence collected outside the portals, use Visual Proof. - Check the result. Open the request in the Proofs Overview. A valid AOPP signature is verified automatically. For a submitted Satoshi test, check that the transaction sent the requested amount from the customer's address to your deposit address, then approve or decline the proof.
The Satoshi portal collects a transaction ID; it does not verify the blockchain transfer. Completing the test requires manual verification or a custody integration that checks the transfer and records the assessment through the API. See the portal integration workflow to automate requests and track status changes.
Follow Up on a Proof
| Status | Meaning | Next step |
|---|---|---|
| Pending | An AOPP signature or Satoshi transaction ID is still outstanding | Open the proof details to copy the portal link and follow up with the customer. |
| Submitted | A Satoshi transaction ID is available, but the transfer has not been verified | Check the transfer and approve or decline the proof. |
| Verified | A signature passed verification, a Satoshi test was approved, or visual evidence was uploaded | Review the proof details and retain the evidence for your compliance records. |
| Failed | A Satoshi test expired or was declined | Review the reason. For expired requests, follow the retry guidance below. |
Only Satoshi tests use Submitted. A pending signature proof requested without
a wallet address shows Awaiting address until the customer submits a valid
signature. See proof details for the information
available at each stage.
For expired Satoshi tests,
open the proof's detail view and click Request another proof to start a new
time window. Send the new portal link to the customer.
Find and Keep Your Records
Use the Proofs Overview to find requests with filtering and sorting. Open a proof to review its evidence and event history, or export proofs for your records.
Proofs Overview
The Proofs overview in 21 Travel Rule allows you to easily navigate through all the self-hosted address ownership proofs.
Table Columns Overview
Wallet Address / ID
Status / Risk Score
Digital Asset
Proof Type
Proof
Customer ID
Created At
Actions
Wallet Address / ID
The wallet address that is being checked for proof of ownership. These refer to an external self-hosted address of one of the customers of your VASP. Clicking on it opens an external explorer in a new tab. The destination depends on the digital asset.
Each proof has a unique ID which can be found under the wallet address.
For a pending signature proof requested without a wallet address, this column
shows Awaiting address. The address appears when the customer submits a valid
proof.
Status / Risk Score
Can be either Verified, Pending, Submitted or Failed.
Proofs that were successfully confirmed will go into a Verified status.
Pending applies to both Signature Proofs and Satoshi Tests. A pending signature proof means an AOPP Portal Link has been requested, but the customer has not yet submitted a valid signature. Wallet ownership is not yet confirmed.
For a pending Satoshi Test, the customer has not yet submitted a transaction ID, and wallet ownership is not yet confirmed.
Submitted and Failed are specific to the Satoshi Test proof type.
If it’s Submitted, it means the user has submitted a transaction ID, but the involved addresses and amounts need yet to be verified.
If the user does not submit a transaction ID within the configured Satoshi Test time limit from the time created, the proof will fail, and there will be no proof of ownership for this particular address.
For the risk score, a blockchain analytics tool needs to be set up and you will see a score of either Severe, High, Medium or Low. Risk scoring is unavailable for pending signature proofs.
Digital Asset
The Digital Asset that the external self-hosted wallet holds.
Proof
The method type used to show proof of ownership of the customer's self-hosted wallet. 21 Travel Rule currently supports three options:
- Signature Proof
- Satoshi Test
- Visual Proof
The method type selected will be displayed above the proof data on each row.
Signature Proof
If you used the signature proof method, this field would show the message used to create the digital signature.
Pending signature proofs also show the message to be signed. Hover over the message to display the AOPP Portal Link, then use the adjacent copy button to copy it. Send this link to your customer to complete the proof. Click the row to open the proof details, where the link is also available.
Satoshi Test
If successfully verified, this will show a message like the following:
Received 0.00005175 BTC in 232025407cae6b158c67af3d4c590012f...
if pending, it will show the following message:
14UAZPRVtNb5T5nbRLoGJmj5U6n9CmeY2Q must be verified within {HOURS_SET_ON_CONFIG}h
Hover over this message to display the link you can send to your customer, then use the adjacent copy button to copy it.
In the case the transaction fails, the field will show something like this:
Expired without proof on 21/02/2023, 13:46:18
Visual Proof
For a Visual Proof, click View Visual Proof in this column to open the
uploaded file in a new tab.
Customer ID
The customer ID allows you to identify your customer. Sometimes, this is also referred to as "Account ID" or "Account Number".
Created At
The time and date the proof method was created. The format shown is day/month/year and hour/minutes/seconds. The time will be shown in the time zone configured in your browser and can be seen by hovering over the transaction date. This will reveal a tooltip with the timezone: continent/city format.
Actions
The Actions column provides controls to save a proof as a file or verify a submitted Satoshi Test. Hover over an icon to see its action name.
Save As File
Click the download icon labelled Save As File to download an .xlsx (Excel)
file containing the proof data.
Verify
This action is specific to the Satoshi Test. After checking
the transaction against a VASP wallet or blockchain explorer, click the
check-mark icon labelled Verify to verify it.
Detailed Proof
Can be any of the three proof types:
When you click on one of the rows in the Proofs Overview table, a pop-up will open.
Click the History icon in the title bar to view events for this proof or
export its event history. See Event History.
You can find the descriptions to these fields on the Proofs Overview page. All the proofs have the following fields:
- Proof ID
- Export Proof
- Proof Type (Signature Proof, Satoshi Test, Visual Proof)
- Status (Verified, Pending, Submitted, Failed)
- Risk Score (Severe, High, Medium, Low)
- Wallet Address
- Asset
- Created At
- Customer ID
Signature Proof
Pending signature proofs show the message to be signed and a prompt to send the
AOPP Portal link to the customer. Copy the URL using
the button next to it. If no wallet address was specified when requesting the
proof, the Wallet Address field shows Awaiting address. Risk scoring is
unavailable until the proof is verified.
When the customer submits a valid signature, the open modal updates to Verified and shows the submitted wallet address.
Has the additional Proof field which shows the message used to create the
digital signature. To add a signature proof you can follow the instructions on
the Signature Proof page.
Satoshi Test
If pending it will show a prompt to send the Satoshi Test Portal link to the customer:
If submitted it will show the form to verify the proof:
If verified it will show information about the proof:
You can find more information about the Satoshi Test on the Proofs Overview page. To add a Satoshi Test you can follow the instructions on the Satoshi Test page.
Visual Proof
Has the additional Proof field which shows the file uploaded. You can click on
this to download the file. To add a visual proof you can follow the instructions
on the Visual Proof page.
Signature Proof
Signature Proof allows you to verify address ownership through a digital signature. This digital signature should be created on a self-hosted wallet.
Obtaining Signature Proofs from your users
The process of obtaining signature proofs can be fully automated using the AOPP Portal.
Asset Support
For a list of supported assets, see the corresponding section on the Supported Assets page.
Satoshi Test
The Satoshi proof method involves the customer sending a minimal amount of a digital asset to verify they own the self-hosted wallet account.
Obtaining Satoshi Test Proofs from your users
Use the Satoshi Proof Portal to request a micro transfer and collect its transaction ID from your customer. After submission, the proof has a Submitted status and still needs verification.
A compliance officer or custody integration must check that the requested amount arrived from the correct address and approve or decline the proof. Follow the verification steps to complete the test.
Asset Support
For a list of supported assets, see the corresponding section on the Supported Assets page.
Visual Proof
Note: 21 Analytics recommends automating this manual process using the API.
This verification ownership method allows you to upload multiple images or
videos of a screen session to prove the ownership of a customer's self-hosted
wallet. To add a new visual proof, click Visual Proof under Address Ownership
Proof Methods.
In the form that opens, add the customer's self-hosted wallet address and upload the screenshots or videos that prove ownership.
Export Proofs
Click Export Proofs to download the proofs matching the current filters as an
.xlsx (Excel) file. You can open the file in spreadsheet software to search,
sort and further process the data, or to retain it in another storage system.
Pending signature proofs are included. Their Verified field is PENDING, and
their Signature field is n/a until the customer submits a valid proof.
Please contact the 21 Analytics team if you have any extra functionality
requirements.
Event History
Use Event History to review the actions recorded for an individual customer, transaction, self-hosted wallet proof or counterparty VASP, including who performed them and when.
View Event History
Open the detail view of a customer, transaction, self-hosted wallet proof or
counterparty VASP (Email, TRP or TRUST). Click the History icon in the title
bar, labelled Action History when you hover over it, to view events for that
object.
The history shows the most recent 100 events, newest first, with Date, Name
and Event columns.
Export Event History
Click Export Event History to download all events for that object as an
.xlsx (Excel) file, including events beyond the 100 shown. The export button
is disabled when no entries are available.
Audit Logs
Use Audit Logs to review recorded actions in 21 Travel Rule, including who performed them and when. Audit logs are available for Enterprise customers.
Open the account menu in the upper-right corner and select Audit Log.
Audit Log Overview
This is the table where the audit log data is represented.
The table consists of:
Name
This is the name of the account that took a specific action/event on the 21 Travel Rule.
Event
These are the actions taken on 21 Travel Rule. These are some examples of events that can be found:
- Outgoing transaction initiated
- TRP transaction confirmed
- AOPP address proof requested
- Satoshi address proof finalised
- Email configuration updated
- Email counterparty VASP registered
- Custodial user registered
- Risk rating of a TRP transaction updated
Target
Describes the object that was modified, represented with a unique ID. Most of the entities will be a clickable link which will take you to directly to the corresponding detail view.
Created At
The date and time the event took place.
Export Audit Logs
Click Export Audit Logs to download the audit-log entries matching the current
filters as an .xlsx (Excel) file. You can open the file in spreadsheet
software to search, sort and further process the data, or to retain it in
another storage system. Please contact the 21 Analytics team if you have any
extra functionality requirements.
Filtering
Multiple views in the GUI, such as VASP-to-VASP Transactions or Self-hosted Wallet Proofs allow you to filter for specific items matching a given set of filtering criteria. This section explains how the different filters work and interact, using the Self-hosted Wallet Proofs view as an example.
For explanations on how to use the filtering in the GraphQL API, see the corresponding API section.
Filtering on Individual Columns
If a table column can have its values filtered for, there will be a small filter icon appearing in the title row. These come in three flavours, explained next. In all variants, the colour of the icon will change to blue if this column has an active filter on it.
Fulltext filter
Columns decorated with a magnifying-glass icon allow you to provide a filtering
term that must appear anywhere in the corresponding value. Click the icon, enter
the term and click Search. Click Clear to remove the filter.
Filtering Among a Set of Options
Columns decorated with a filter symbol allow you to select matching values from
a list of options. Click the icon, select the values to include and click
Search. Click Clear to remove the filter.
Date range filter
Columns holding a date are decorated with a calendar icon and allow you to filter for a period by picking a start date, an end date or both.
Both dates are inclusive and are interpreted in the time zone configured in your browser. Leaving one side empty keeps the range open-ended.
Search for Anything
Some views, such as the Self-hosted Wallet Proofs have a "Search for anything" field where a given search term will be attempted to be matched against various attributes of an object, in this case a proof. Note that it may not be immediately obvious why a given search result has resulted in a match, and you may need to open the detailed view to understand why.
Exporting Objects
The Export buttons, for example the Export Proofs button, will respect the currently active filter, and only export items resulting in a match. If you want to reset the filter, it is easiest to just reload the page.
Sorting
Multiple views in the GUI, such as VASP-to-VASP Transactions or Self-hosted Wallet Proofs allow you to apply a custom sort order to items in the table. This section explains how this sorting works, using the Self-hosted Wallet Proofs view as an example.
For explanations on how to use the sorting in the GraphQL API, see the corresponding API section.
Default Sorting
With the exception of Archived Transactions (which are sorted by descending finalisation date), all tables in the GUI are sorted by descending creation date by default. This also holds if you modify the sorting as described below and then reload the page.
Sorting on Individual Columns
If a table column can have its values sorted, there will be two small triangle icons appearing in the title row. Clicking anywhere in the title row of the column will cycle through the sorting states from 'No sorting' to 'Ascending' to 'Descending'. A currently active sorting is always indicated by one of the two triangles being highlighted in blue:
Clicking on any other sortable column title row will remove the previous sorting. In other words, it is not possible to specify multiple sorting conditions from the GUI.
Column Visibility
Tables in the GUI let you choose which of their columns are shown, so you can reduce a table to the information relevant for your workflow.
The gear icon at the right end of the title row opens a menu listing the columns. Tick a column to show it and untick it to hide it. Columns holding row actions are not listed and remain visible, and the last remaining column cannot be unticked.
Your selection is stored in your browser for each table individually, so it survives a page reload. It is not part of your user account, which means that another browser or device starts from the default columns again.
Getting Started
Automate Travel Rule messaging and self-hosted wallet proofs using the same GraphQL API that powers the Compliance Dashboard. Connect it to your custody system, customer workflows, and compliance processes.
Start Here
- Get access. Use your deployed instance or request sandbox access to evaluate the API.
- Explore the schema. Open
/graphiqlon your instance and follow the GraphiQL walkthrough to browse the schema and run a query. If GraphQL is new to you, read the introduction to GraphQL first. - Authenticate your client. Follow the authentication guide to obtain an access token for HTTP requests. Authenticate WebSocket subscriptions as well. For Enterprise deployments, assign the required client roles.
- Implement your workflow. Choose an integration workflow below. For self-hosted wallets, follow the proof portal integration workflow.
Integration Workflows
Your integration can support several workflows. For VASP-to-VASP messaging, configure your VASP before implementing the relevant workflow.
| I want to… | Guide |
|---|---|
| Send Travel Rule data for a withdrawal | Outgoing transactions |
| Receive Travel Rule data for a deposit | Incoming transactions |
| Collect self-hosted wallet ownership proofs | Ownership proof portals |
| Enable risk scores for compliance workflows | Risk score providers |
VASP-to-VASP messaging exchanges originator and beneficiary data with another VASP. Self-hosted wallet verification collects evidence from your customer. For each transfer, use the workflow that matches who controls the other wallet. Your custody system remains responsible for executing transfers and crediting deposits. See the transaction lifecycle for the decisions and states your integration needs to handle.
To help identify who controls the other wallet, ask your customer to declare
whether it is self-hosted or held with a VASP, or use a blockchain analytics
provider to identify the entity associated with the wallet address. You can also
use the trustd.lookupBulletinBoard query to look up the address and asset on
TRUST. A successful lookup implies that the counterparty is not a self-hosted
wallet but a VASP. See the GraphQL schema for arguments and
return types.
Configure Your VASP
Set up the protocols you will use before sending or receiving VASP-to-VASP messages:
- TRP: configure your VASP and complete counterparty due diligence.
- TRUST: complete TRUST onboarding, including membership, certificates, bulletin board registration, and instance configuration.
- Email: configure email and add email counterparties for transfers where TRP or TRUST cannot be used. The email flow explains when to request confirmation and how to follow up.
Find Your Task
| I want to… | Start here |
|---|---|
| Understand queries, mutations, and subscriptions | GraphQL basics |
| Browse the schema and try a query | GraphiQL walkthrough |
| Build a client or adapt an example | Integration client SDK |
| Generate client types from the schema | Schema Definition Language |
| Query collections | Filtering and sorting |
| Set up TRP, TRUST, or email | Configure your VASP |
Interactive Exploration with GraphiQL
The API is self-documenting: GraphiQL lets you browse available operations,
their arguments, and return types. Use the /graphiql endpoint on your own
instance for the schema that matches your deployed version.
Integration Client SDK
Use the integration client SDK to handle authentication for HTTP requests and WebSocket subscriptions in your application. It implements a subset of the GraphQL API; use the schema to find operations beyond that subset.
Writing Your Integrated Application
The rules engine example shows an application built with the SDK.
Writing Your Own GraphQL Integration Client
For another language or stack, use the SDK's client implementation as a reference for authentication and subscription handling.
Accessing the Schema Definition Language
Download the GraphQL schema for client tooling and type generation. Use GraphiQL to check it against the schema served by your deployed version of 21 Travel Rule.
Authentication
The GraphQL API expects Bearer Authorisation header containing a valid OIDC
access token, usually issued by a Keycloak service which is
integrated into the 21travel
reference deployment.
For Enterprise customers, the service account that obtains the token also needs needs the relevant client roles for each GraphQL operation.
By default, Keycloak is configured for usage via the web frontend using the
account Keycloak client on the 21travel realm. The following steps describe
how to create an additional Keycloak client on the realm such that API clients
can request access tokens that can subsequently be used to authenticate against
the GraphQL API. Following this recipe, both the web frontend and API clients
can be used at the same time.
Creating a Confidential Keycloak Client for API integration
Within the Keycloak Administration Console:
Create A New Client
Navigate to the 21travel realm
Then go to the "Clients" tab. Click "Create client".
Leave the Client type as "OpenID Connect", and choose an appropriate Client ID, for example "21travel-api". Click "Next".
Switch on Client authentication and Authorization, and make sure only the
Direct access grants and Service accounts roles authentication flows are
selected. Click Next.
You can leave the final fields blank and click "Save".
Create A New Client Scope
Staying with the newly created client, under "Client scopes" click "Add client scope".
Select the "21travel-audience" scope and "Add" it as "Default".
Obtain The Client Secret
Subsequently, you can go to the "Credentials" tab and copy the client secret, which you will need below.
Access Token Scopes
You can now obtain an access token via an HTTP call using the popular curl
command line utility:
curl -L -X POST '<your-host>/auth/realms/21travel/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=21travel-api' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=<client-secret>' \
--data-urlencode 'scope=openid'
In the above command, make sure to:
- Use the correct client ID under
client_id=.... - Replace
<your-host>with the host used in the Caddyfile. - Replace the
<client-secret>with the value you obtained above.
This will return a JSON response of the form:
{
...
"access_token": "<access-token>",
...
}
You can now use this token to authenticate against the GraphQL API, for example querying the names of all TRP VASPs:
curl '<your-host>/graphql' --compressed -X POST -H 'Authorization: Bearer <access-token>' --data-raw '{"query":"{ trpd { vasps { name } } }"}'
Make sure to replace <your-host> with the host where the autod GraphQL API
is reachable, as well as to insert the <access-token> obtained above.
The provided integration client SDK will transparently manage that for you.
Authentication for GraphQL Subscriptions
GraphQL subscriptions are run over a WebSocket protocol. Authentication happens
as part of the initial handshake on an established WebSocket connection. To this
end, clients must include the very same Bearer token obtained from Keycloak
mentioned above as the optional payload in the
initial
GQL_CONNECTION_INIT message
as follows:
{
"bearer_token": "<access-token>"
}
Usually, WebSocket GraphQL clients come with built-in support for setting this payload, for example the JS Apollo client.
The provided integration client SDK will transparently manage that for you.
TRUST Onboarding
This guide takes you from applying for TRUST membership to exchanging test transactions with 21 Travel Rule. It covers the legal onboarding, registration on the pre-production bulletin board, and configuration of your instance. 21 Travel Rule implements the TRUST protocol; your team supplies the registration details, certificates, and encryption key.
1. Start Legal and Pre-Production Onboarding
Apply through the TRUST network access form. This is also linked on the TRUST settings page of the Compliance Dashboard in case TRUST is not configured yet. Work with the TRUST organisation to complete its legal and membership requirements.
Pre-production is a separate environment for integration testing. For expedited onboarding to this test environment, contact 21 Analytics support. We can help coordinate your registration with TRUST and access to the TRUST Technical Integration Handbook. Production access requires its own approval after validation.
Use a dedicated test instance and artificial customer data for pre-production.
2. Prepare Your Domain, Certificates, and Encryption Key
TRUST Domain and Network Access
Choose the public DNS name for your TRUST endpoint. In the Helm deployment, this
is travelServices.trustd.domain, for example trust-preprod.example.com. Use
this name consistently in your certificates and bulletin board registration. The
PII payload endpoint provided by 21 Travel Rule is then
https://trust-preprod.example.com/pii.
Arrange a static public IPv4 address for outbound connections and collect the
outbound IP ranges in CIDR notation for TRUST's allowlist. Ensure that
counterparties can reach your TRUST endpoint on port 443 and that your instance
can connect to the bulletin board and counterparties. Incoming TRUST TLS must
reach trustd without being terminated by an intermediate proxy. See the
deployment network requirements.
TLS Identities
TRUST uses mutual TLS (mTLS) to authenticate connections. Pre-production has the same authentication requirements as production: you need certificates from a TRUST-accepted Certificate Authority (CA).
Follow Obtaining Certificates for TRUST to prepare your identities. The client certificate's Subject Alternative Name (SAN) must include the domain registered on the bulletin board; the server certificate must cover your TRUST endpoint's hostname. Each PEM identity must contain the full certificate chain and exactly one corresponding private key.
You can use the same PEM identity for both the server and client if its Extended
Key Usage (EKU) includes both serverAuth and clientAuth. Separate identities
are also supported.
Payload Encryption Key
Generate a separate RSA key pair for encrypting Travel Rule payloads. This key pair is independent of your TLS certificates and does not require a CA-issued certificate. Run the following in a secure environment:
umask 077
openssl genpkey -algorithm RSA \
-pkeyopt rsa_keygen_bits:4096 \
-pkeyopt rsa_keygen_pubexp:65537 \
-out trust-private.pem
openssl pkey -in trust-private.pem -pubout -out trust-public.pem
trust-public.pem: Send this public key to TRUST for the bulletin board (see below). Other VASPs use it to encrypt payloads sent to you.trust-private.pem: Keep this private key confidential. Upload it to theDecryption Keyfield in your 21 Travel Rule Compliance Dashboard in step 5.
Keep the private keys for both TLS and payload decryption in your secrets store. Do not include them or a PEM identity containing them in your onboarding email.
3. Submit Your Pre-Production Registration to TRUST
Send the following details to the TRUST contact coordinating your onboarding, or to travel-rule@TRUST.com, using the format from the TRUST Technical Integration Handbook. Replace the example domain and all placeholders with your pre-production details:
Subject: [Onboarding] [Pre-Prod] [<YOUR_VASP_NAME>]
VASP Configuration
name: <official legal VASP name>
payload_endpoint: https://trust-preprod.example.com/pii
domain: trust-preprod.example.com
public_key: <complete PEM contents of trust-public.pem>
LEI: <your VASP's Legal Entity Identifier>
IP_allow_list: <outbound public IPv4 ranges in CIDR notation>
Contact Information
Primary Engineering DRI Name: <full name>
Primary Engineering DRI Email: <email>
Primary Engineering Github Account ID: <GitHub ID>
Secondary Engineering DRI Name: <full name>
Secondary Engineering DRI Email: <email>
Secondary Engineering Github Account ID: <GitHub ID>
The engineering DRIs are the people responsible for your integration. The
domain is the hostname only, while payload_endpoint includes https:// and
/pii. The public_key is the payload encryption public key generated above.
Your TLS identities are installed in 21 Travel Rule in step 5.
Wait for confirmation that your configuration has been deployed to the
pre-production bulletin board. TRUST may return a vaspId; the Compliance
Dashboard asks for your LEI, which must match the submitted LEI, rather than
this bulletin board ID.
4. Point Your Instance at Pre-Production
Set --bulletin-board-url on the autod service to
https://api-preprod.trust.global. For the reference Helm deployment, merge
this into your values.yaml, using the domain registered in step 3:
travelServices:
trustd:
domain: trust-preprod.example.com
autod:
extraArgs:
- --bulletin-board-url
- https://api-preprod.trust.global
Apply the updated values and restart the affected services. For the
reference deployment,
regenerate the deployment YAML, reinstall the updated Quadlet files, and restart
travel.service. For Kubernetes, apply the values through your Helm upgrade
process.
5. Configure 21 Travel Rule
Once TRUST confirms registration and your instance uses the pre-production bulletin board, follow Configure your VASP: TRUST in the user manual.
Use the LEI submitted in step 3 and both TLS identities prepared in step 2.
Upload trust-private.pem as the Decryption Key, even though this field is
optional. Leaving it empty on initial setup generates a different key pair,
which will not match the public key you submitted to TRUST.
After saving, use Copy Encryption Public Key to verify that the public key
matches trust-public.pem.
6. Validate and Move to Production
Coordinate testing with a pre-production TRUST participant through your
onboarding contact or the TRUST #trust-technical-onboarding Slack channel.
You can also send test Travel Rule data to the 21 Analytics pre-production
instance using the Bitcoin address bc1q9t6qa0ukl9zwzdlttuvdtunqhd6y9yfdy5jnhu
(for beneficiary John Doe). Contact the 21 Analytics team to coordinate testing
and confirm receipt.
If you chose Blocked as the default counterparty status, complete the relevant
due diligence and
mark your test counterparty as trusted
before exchanging messages.
Complete the pre-production integration checklist supplied by TRUST, including both directions of exchange:
- Register a test customer and a supported custodial wallet address in the Travel Address Book. Confirm with your test counterparty that they can discover the address on the bulletin board and send artificial PII that appears in your incoming transactions.
- Send a TRUST transaction to an address registered by your test counterparty. Have them confirm receipt of the artificial PII.
- Obtain receiving-flow sign-off from at least one VASP and confirm successful sending with each VASP you test with, as required by the TRUST checklist.
After validation, submit your production details to TRUST with the subject
[Onboarding] [Production] [<YOUR_VASP_NAME>]. Wait for production approval and
registration. On your production instance, use the registered production domain,
TLS identities, and decryption key, and remove the pre-production Bulletin Board
URL override to use the default. Apply the deployment changes and save the
matching TRUST configuration before exchanging real customer data.
Troubleshooting Initial Setup
- Saving reports that no entity with your LEI is registered: Confirm that
TRUST has deployed the registration, the entered LEI matches it, and the
running
autodservice uses the intended bulletin board URL. Check that you entered the LEI rather than thevaspId. - The connection fails during authentication: Check the certificate's validity, accepted CA chain, client authentication EKU, registered domain in the SAN, and outbound IP allowlist. Pre-production requires valid mTLS too. Run the automated certificate validation script described in the TRUST docs to diagnose certificate issues.
- Saving succeeds, but incoming payloads cannot be decrypted: Check that
Decryption Keymatches the public key registered with TRUST. A successful save does not verify that those keys match.
If setup still fails, contact 21 Analytics support with the environment and error message. Keep private keys out of support messages.
Obtaining Certificates for TRUST
This page gives a basic introduction to the certificates typically needed for TRUST and a simple ordering flow using DigiCert and X9.
For the complete registration and configuration sequence, follow TRUST Onboarding.
mTLS, Server Certificates, and Client Certificates
TRUST connections use mutual TLS (mTLS). In a normal TLS connection, only the server proves its identity with a certificate. In mTLS, both sides present a certificate:
- The server certificate identifies your TRUST PII endpoint to counterparties.
- The client certificate identifies your system when it connects outbound, for example to the TRUST bulletin board or another TRUST participant.
In 21 Travel Rule, the TLS Server Identity must be valid for server
authentication and the mTLS Client Identity must be valid for client
authentication. If you order one certificate that supports both usages, you can
use the same PEM identity in both fields.
When preparing the certificate request, use the DNS name of your TRUST endpoint and keep it aligned with the domain you use during TRUST onboarding and bulletin board registration.
What X9 Is
X9 is a PKI framework specifically intended for the financial-industry. It is the recommended PKI to use in the TRUST ecosystem for certificate-based identity. But note that TRUST admits a set of different root Certificate Authorities beyond DigiCert (as of March 2026 e.g. GlobalSign or GoDaddy).
Step-by-Step: Order a Combined Certificate
The following explanations reference the DigiCert user interface as of March 2026. Expect small deviations to possibly occur.
1. Prepare the Required Information
Before you start, collect the following:
- Your legal entity name and address
- The DNS name of your TRUST PII endpoint
- The person who will administer your DigiCert account
If you want to use a single identity for both inbound and outbound TRUST
connections, plan to order one certificate that supports both serverAuth and
clientAuth.
2. Create a DigiCert Account
- Go to DigiCert and create a company account.
- Verify the email address of the administrator account.
- Complete the organisation profile with your legal entity details.
- If DigiCert requests business validation documents, provide them and wait until the account is approved.
At this point, you should be able to access your DigiCert certificate management portal.
3. Request Access to X9
Not every DigiCert account shows X9 products by default. If you do not see X9 certificate products in the portal, ask DigiCert support or your DigiCert sales contact to enable X9 certificate ordering for your account.
Once that access is granted, X9-backed certificate products should become available in the ordering flow.
4. Create a Certificate Signing Request (CSR)
During the ordering process, you will need to provide a Certificate Signing Request. For this, you need to obtain your TRUST domain that was provided during TRUST onboarding.
Using this, the CSR can be generated as follows by your tech team, assuming
mydomain is the aforementioned domain:
$ openssl req -new \
-newkey rsa:2048 \
-nodes \
-keyout mydomain.key \
-out mydomain.csr \
-subj "/CN=mydomain" \
-addext "subjectAltName=DNS:mydomain" \
-addext "extendedKeyUsage=clientAuth,serverAuth"
This will generate two files:
mydomain.key: The private key to be used for the identity. Keep this secure.mydomain.csr: The signing request. You will need this in the next step.
5. Order a Combined Server and Client Authentication Certificate
- Start a new certificate order in DigiCert.
- Choose the X9 certificate product made available for your account.
- Paste the CSR you generated in step 4.
- Ensure that the "Common name" and "SANs" are automatically pre-filled.
- Under "Additional certificate options", make sure the requested certificate profile includes both server authentication and client authentication.
- Submit the order and complete any validation steps requested by DigiCert.
The resulting certificate will be usable both:
- as your server identity for incoming TRUST mTLS connections
- as your client identity for outgoing TRUST mTLS connections
6. Export the Final PEM Identity
After issuance, export the certificate chain and private key in PEM format. 21 Travel Rule expects each identity as PEM data containing:
- exactly one private key
- the end-entity certificate
- the required certificate chain
If you ordered one combined certificate, you can upload the same PEM identity to
both the TLS Server Identity and mTLS Client Identity fields in
Configure Your VASP > TRUST.
Practical Notes
- Keep a copy of the issued certificate chain and private key in a secure secrets store.
- Renew the certificate before expiry and update both TRUST identity fields if you use the same combined certificate for both.
Outgoing Transactions
This page walks you through each step of sending funds to a beneficiary at another VASP, including address discovery and responding to TRP approvals or rejections using the 21 Travel Rule API.
Setting the Scene
In this scenario, your customer is the originator. The customer wants to withdraw funds to a beneficiary who is a customer of a third party VASP, a.k.a. a counterparty VASP.
In this guide, the necessary steps are listed to integrate the described scenario using the 21 Travel Rule GraphQL API.
Accept Travel and Wallet Addresses in UI
The customer facing UI needs to accept Travel Addresses and wallet addresses in the same field.
Your customer can paste either address received from the beneficiary.
Discover the Counterparty and Send Travel Rule Data
Use the { autod { sendTxToAddrOwner } } mutation with the destination address
and IVMS101 data, including the asset, amount, originator, and beneficiary name:
mutation Send($address: String!, $ivms101: TrustdTxDetailsInput!) {
autod {
sendTxToAddrOwner(address: $address, ivms101: $ivms101) {
__typename
... on TrpdTx {
trpd {
id
}
}
... on TrustdTx {
trustd {
id
}
}
}
}
}
The mutation uses TRP for a Travel Address or a wallet address found in the TRP
directory. Otherwise, it checks TRUST for the wallet address owner. Provide
ivms101.txId when the transaction has already been executed; it is required if
TRUST handles the notification. For TRP, submit the TxID after approval using
trpd.confirmTx. If neither protocol finds an owner, use
encrypted email with a selected counterparty
VASP.
The returned __typename identifies the protocol. A TrustdTx means the Travel
Rule data has been sent through TRUST. For a TrpdTx, continue with the TRP
approval or rejection flow below.
Note that if the VASP corresponding to the Travel Address is unknown, it will be automatically added to the counterparty VASP table as untrusted and the TRP message is only sent after it has been marked as trusted.
React to TRUST Events
The { trustdTransactions } subscription will emit events whenever a TRUST
transaction is received, returning a complete TrustdTxDetails object. You can
listen to the subscription using the
integration client SDK.
React to TRP Events
The trpdTransactions subscription emits events whenever a TRP transaction is
received or its status changes. It returns the TrpdTxNotification union:
TrpdSentTxDetails or TrpdTxDetails. Use inline fragments on these types to
select the fields you need. You can listen to the subscription using the
integration client SDK.
At some point, you will receive TRP approval or rejection messages from your
counterparty VASP about your inquiries through TRP. You can identify them using
the status and type fields on the object returned from the subscription.
In case of an approval, you can proceed by executing the transaction on the
blockchain using the beneficiary.walletAddress field on the returned object as
a recipient address. Then, the resulting transaction ID needs to be submitted to
the { trpd { confirmTx } } mutation to finalise the TRP protocol flow.
In case of a rejection, there's no further steps required for TRP. However, you
should notify your user about the declined transaction. Maybe the counterparty
VASP has provided a reason in the comment field.
Incoming Transactions
Connect your deposit workflow to incoming Travel Rule messages. For TRP, make Travel Addresses available to your customers and approve or decline incoming requests. For TRUST, review received Travel Rule data and correlate it with deposits in your custody system.
Setting the Scene
In this scenario, your customer is the beneficiary. The customer wants to receive funds from an originator who is a customer of a third party VASP, a.k.a. a counterparty VASP.
In this guide, the necessary steps are listed to integrate the described scenario using the 21 Travel Rule GraphQL API.
Add Support for Travel Address in UI
Register your customer and their wallet address in the Travel Address Book to obtain a Travel Address. Make it available in your deposit interface so the customer can share it with the payer.
React to TRP Events
The trpdTransactions subscription emits events whenever a TRP transaction is
received or its status changes. It returns the TrpdTxNotification union:
TrpdSentTxDetails or TrpdTxDetails. Use inline fragments on these types to
select the fields you need. You can listen to the subscription using the
integration client SDK.
At some point, you will receive inquiries from your counterparty VASPs through
TRP. You can identify them using the status and type fields on the object
returned from the subscription.
Note that inquires from unknown VASPs that try to inquire to your VASP for the
first time will also emit events but with status of BLOCKED. It is only
possible to proceed after the corresponding
VASP has been marked as trusted.
Depending on the details found in the returned object you can choose to approve
or decline the transaction using the { trpd { assessTx } } mutation. Note that
in case of an approval the wallet address in your customer's Address Book entry
will be shared with the counterparty VASP which it will use for the transaction.
Optionally, you can listen for your counterparty VASP's confirmation which
contains the blockchain transaction ID which might be useful to correlate with
your custody system. Again, you can identify them using the status and type
fields on the object returned from the subscription. Alternatively, you can
identify on the presence of the txId field as only confirmed TRP transactions
have a non-null txId value.
React to TRUST Events
Register your customer's wallet address in the Travel Address Book and make it available in your deposit interface. After TRUST setup, 21 Travel Rule handles address discovery and receives Travel Rule data from the originator VASP.
Subscribe to trustdTransactions to receive TrustdTxDetails for both sent and
received transactions. Include type in your selection and process only events
where type is RECEIVED in your deposit workflow.
Review the data and use the blockchain transaction ID to correlate it with your custody records before crediting your customer. TRUST does not use the TRP approval and confirmation mutations.
Introduction to GraphQL
21 Travel Rule exposes its business logic through a single GraphQL schema. The same API powers the Compliance Dashboard and your own integrations.
Endpoints and Transports
- HTTP requests are sent to
/graphqlusingPOSTwith a JSON body containing aquerystring and optionalvariables. - Subscriptions use the WebSocket endpoint
/graphql-ws, following the graphql-ws protocol. Both use the same schema and authentication model. - Authentication is required for all operations; use a Keycloak-issued bearer token as described in Authentication.
Example HTTP call:
curl -X POST https://yourvasp.intranet/graphql \
-H "Authorization: Bearer <access-token>" \
-H "Content-Type: application/json" \
--data '{"query":"query { trpd { vasps { name } } }"}'
How the Schema is Structured
- Root fields – The schema is namespaced by domain:
trpdcovers Travel Rule Protocol operations,aopdcovers address-ownership proofs, andautodexposes administrative data used by the Compliance Dashboard. - Queries fetch data (for example
trpd { vasps { name } }). - Mutations perform actions (for example
autod { sendTxToAddrOwner(...) }to discover a counterparty and send Travel Rule data, ortrpd { confirmTx(...) }to submit a TRP transaction hash). - Subscriptions stream updates (
trpdTransactionsandaopdProofsare the primary channels).
GraphQL validates every request against the schema, so you only receive fields that exist and match the declared types.
Arguments, Variables and Selection Sets
-
Arguments are passed directly to fields:
trpd { validateTravelAddress(travelAddress: "...") { name } }. -
Use
variablesto keep queries reusable:{ "query": "query Check($address: TrpdTravelAddress!) { trpd { validateTravelAddress(travelAddress: $address) { name } } }", "variables": { "address": "taEJKtAQyrS5x6i59GBS2fcbbZDB9VM9r4yKeWR" } } -
Selection sets let you choose only the fields you need, which keeps responses small and stable even as the schema grows.
Discoverability and Errors
- The API is fully introspectable. You can use GraphiQL to interactively explore the full API.
- GraphQL responses always return an
errorsarray alongsidedata. When a mutation fails validation or business rules, expecterrors[0].messageto contain the reason, whiledatais set tonullfor the failing field.
Browsing API Docs in GraphiQL
Use GraphiQL to interactively explore the API, view documentation, and test queries for a better understanding of available endpoints and data structures.
Objective
This section demonstrates how to use GraphiQL to explore the 21 Travel Rule API and its documentation. The goal is to understand how GraphQL queries can be derived from the API documentation and a JSON result obtained by executing those queries.
1. Open the In-Browser GraphQL IDE
To start, open the interactive in-browser GraphQL IDE by clicking here (login using the username and password you have been provided with).
NOTE: The GraphiQL application served by above link serves a development
version of the API. If you are integrating against a release version of 21
Travel then you should use GraphiQL served via the /graphiql endpoint of your
instance.
2. Reveal the Docs
Click the book icon in the upper-left corner of GraphiQL to open the Documentation Explorer, which lists the available fields, types and their definitions.
You might see an introductory set of comments when visiting for the first time.
Comments start with # followed by the comment text. You can delete all the
introduction comments.
3. Root Types
These types are specific to GraphQL. The most common root type is the Query
type. To query data, write query followed by some curly braces.
Copy the following code snippet into GraphiQL:
query {
# query fields go here
}
Click on the orange Query Type link on the docs. This will unveil the query
Schema Types available to explore in the next section.
As you can see the field names are shown in blue and camel-cased and the types returned by that field are shown in orange and capitalised.
4. Schema Types
These types are specific to the 21 Travel Rule API. These can be found inside
the Root Types. Click the Query Type link to find the available Schema Types.
Choose one of these and add it within the brackets. There is an auto-complete
list of options available to guide you. Select the autod field.
To do this, copy the following code:
{
autod {
# nested query
}
}
Run the query by clicking the pink triangular play button above the query
editor. Because autod is a nested type and the query does not select any of
its fields, GraphiQL returns a schema type error.
Click the orange Autod type link, as you previously did with Query, to see
its available fields and description.
Another important thing to remember is the ! bang symbol. This means the Data
Type is not optional.
5. Nested Types
You will often find a field with other Schema Types available within it. This can have multiple levels of nesting until you reach the returned value. Start by retrieving a field value only two levels deep. The next step explores deeper nesting and explains arguments.
Copy the following code into GraphiQL:
{
autod {
auditLogsCount
}
}
Click on the pink play button to run the GraphQL query and return its result. Such queries can be copy-pasted into client applications and used to for automation, integration or user interfaces.
With the basics of nesting in GraphQL covered, the next step looks at arguments.
6. Query Arguments
The previous definition of an argument can now be applied in GraphQL.
Some types require arguments. You can find these between parentheses. They
usually serve as a kind of filter for the data you want to retrieve. Look at the
auditLogs field:
Here you can see that limit and offset have default values, so they may be
omitted. Their Int! type means a supplied value cannot be null. Int stands
for Integer, and you can read its full definition by clicking the orange link.
This introduces a new level of nesting. Since it is wrapped with square brackets
it will return an array. This array is also required and has to be of type
AutodAuditLog. Click on the AutodAuditLog orange link to see the available
fields.
Choose username and event within auditLogs and set limit and offset to
select two results.
Copy the following code snippet to see the results:
{
autod {
auditLogsCount
auditLogs(limit: 2, offset: 0) {
username
event
}
}
}
You might have noticed that the event field is not a Primitive Type, yet it
returned a value. This is because it does not nest another type but defines an
enum. This can easily be seen by clicking on the orange AutodAuditLog link.
Filterable API Collections
Numerous GraphQL queries that return collections of objects (such as self-hosted wallet proofs or VASP-to-VASP transactions) accept identically structured filtering parameters that can be used to select a sub-set of items. This section explains how those filter parameters are structured, and walks through some examples.
It may also be instructive to see how the 21 Compliance Dashboard leverages these filter APIs to present numerous filtering options to the user. This is explained in the corresponding GUI section.
Recursive filter Structure
In general, any query for filtering results can be expressed as a nested
combination of AND, OR and NOT formulas. The root filter parameter
accepted by filterable APIs allows you to specify a filter condition that can
represent such an arbitrarily nested formula. Taking the AopdProofFilterInput
input as an example, it is defined as:
input AopdProofFilterInput @oneOf {
and: [AopdProofFilterInput!]
or: [AopdProofFilterInput!]
not: AopdProofFilterInput
is: AopdProofConditionInput
}
The union type has three recursive and, or and not variants that start a
new boolean formula, and one terminating variant is, where an actual condition
can be specified. Abbreviating the terminating objects of the
AopdProofConditionInput type as C1, C2, etc., a valid filter object
could thus look like:
filter: {
and: [
{ is: C1 },
{ not: { is: C2 } },
{ or: [ { is: C3 }, { and: [ { is: C4 }, { not: { is: C5 } } ] } ] }
]
}
The next section explains how those Cx filter conditions can be constructed.
Filtering Heterogeneous vs. Homogeneous Collections
Again taking the filter for self-hosted wallet proofs as an example, let's look
at the AopdProofConditionInput type, which terminates the recursive filter
formulas for AopdProofFilterInput, as an example. Since self-hosted wallet
proofs can be of three different types, this is again a union with variants
corresponding to the different proof types:
input AopdProofConditionInput @oneOf {
signature: AopdSignatureProofConditionInput
media: AopdMediaProofConditionInput
satoshi: AopdSatoshiProofConditionInput
any: AopdAnyProofConditionInput
}
Choosing one of the first three variants will automatically restrict filter
results for this condition to the chosen proof type. In addition, there is an
any variant which collects filtering criteria applicable to all proof types,
and which doesn't restrict the type of returned proofs.
Some filter APIs only return objects of one particular type, such as the filter for counterparty VASPs. In this case, this intermediate union is skipped, and the recursive filter is terminated by an object type where conditions can be specified.
The next section covers the actual filtering condition types, e.g. the kinds of
types pointed at by the AopdProofConditionInput variants above.
Specifying Filter Conditions
Again taking the filter for self-hosted wallet proofs as an example, let's look
at the abbreviated definition of AopdSatoshiProofConditionInput:
input AopdSatoshiProofConditionInput {
asset: TravelStringConditionInput
amount: TravelAmountConditionInput
status: [AopdProofStatus!]
createdAt: TravelTimestampConditionInput
...
}
The first thing to notice is that all fields are optional, representing optional restrictions on some attribute of a Satoshi proof. In fact, using the empty object as:
filter: { is: { satoshi: {} } }
has the meaningful effect of restricting the results to Satoshi proofs.
More likely though, you will want to use a subset of the fields to specify some conditions on a Satoshi proof. The types used for this fall into two categories, detailed next.
Condition Types
For numerous types, there exist union Condition types which are shared across
the whole schema and whose variants express a constraint. For the above example:
-
For strings:
TravelStringConditionInput, whoseIlikevariant allows you to filter for sub-strings (see the type's GraphQL documentation for more information). -
For amounts:
TravelAmountConditionInput, which has variants to express 'less than X', 'equal to X' and 'larger than X'. -
For timestamps:
TravelTimestampConditionInput, where a 'before X' or 'after X' constraint can be expressed.
Filter for Enumerable Fields
In the above example, every Satoshi proof has a status of union type
AopdProofStatus. The available filter for this property allows you to specify
a list of statuses, where the Satoshi proof status must match one of them.
A Complete Example
As a concluding example, the following query will return all proof IDs for proofs that are:
-
Of any type and verified, or
-
Signature proofs created after 2024 whose address start with "0x", or
-
Media proofs whose comment contains "OK" and whose customer ID does not contain "LEGACY".
query {
aopd {
proofs(
filter: {
or: [
{ is: { any: { status: VERIFIED } } }
{
is: {
signature: {
address: { ilike: "0x%" }
createdAt: { after: "2025-01-01T00:00:00" }
}
}
}
{
and: [
{ is: { media: { comment: { ilike: "%OK%" } } } }
{ not: { is: { media: { customerId: { ilike: "%LEGACY%" } } } } }
]
}
]
}
) {
__typename
... on AopdMediaProof {
id
}
... on AopdSatoshiProof {
id
}
... on AopdSignatureProof {
id
}
}
}
}
Sortable API Collections
Numerous GraphQL queries that return collections of objects (such as self-hosted wallet proofs or VASP-to-VASP transactions) accept identically structured sorting parameters that can be used to impose a custom order on the returned items. This section explains how those sorting parameters are structured, and walks through an example.
It may also be instructive to see how the 21 Compliance Dashboard leverages these sorting APIs to present numerous sorting options to the user. This is explained in the corresponding GUI section.
The sortOrder Parameter
If a collection supports custom sorting, the corresponding query will accept a
sortOrder parameter, where a list of sorting conditions can be specified.
Taking the aopd { proofs } query as an example, the corresponding parameter is
sortOrder: [AopdProofSortInput!]. The definition of AopdProofSortInput is:
input AopdProofSortInput {
property: AopdProofSortColumn!
order: TravelSortOrder!
}
where AopdProofSortColumn is an enumeration of possible columns to sort on,
and TravelSortOrder specifies the sort order as either ascending or
descending.
When multiple sort criteria are supplied, earlier ones take precedence over later ones. Thus, the following example:
aopd {
proofs(..., sortOrder: [
{ property: ADDRESS, order: ASCENDING },
{ property: CREATED_AT, order: DESCENDING }
])
}
will sort proofs by ascending address, and sort proofs over the same address as most recent ones first.
Ownership Proof Portals
Let customers prove ownership of a self-hosted wallet through a unique link. Create the link in the Compliance Dashboard or through the GraphQL API, then send it to the customer or embed the portal in your own application. Track the result in Self-hosted Wallet Proofs.
Choose a Proof Method
| Portal | What the customer does | How the proof is verified |
|---|---|---|
| AOPP Portal | Signs a message with their wallet. | 21 Travel Rule automatically verifies the digital signature. |
| Satoshi Proof Portal | Sends a small amount and submits the transaction ID. | A compliance officer or custody integration checks the transfer and approves or declines the proof. |
Check supported assets when choosing a method; digital signature support also depends on the customer's wallet. For evidence collected outside these portals, see visual proofs.
To try a portal, follow the AOPP or Satoshi guide. To connect a portal to your own customer journey, follow the workflow below and the API setup guide.
Workflow
- A VASP's customer is required to submit proof of ownership for an address.
- The VASP requests a proof link and obtains a proof ID, using
requestAoppProoforrequestSatoshiProofthrough the API, or the corresponding action in the Compliance Dashboard. - The VASP loads the proof link in an
iframeor redirects the customer to it. - The customer submits a signature or Satoshi transaction ID and, if a redirect was configured, returns to the VASP's application.
- The VASP receives proof status updates via the GraphQL subscription API, e.g. using the integration client SDK.
- The VASP correlates the proof ID with the request from step 2 and checks the status before proceeding. A submitted Satoshi proof requires a verification step.
Obtaining Ownership Proofs
For the actual workflows of obtaining ownership proofs, please consult the pages for the signature proofs portal and for the Satoshi proof portal.
Changing the AOPP Portal's Logo
Detailed steps for replacing the AOPP Portal’s logo are provided in the Changing the AOPP Portal Logo documentation.
Customising the Portal Texts
Guidance on modifying the Portal texts can be found in the Customising Portal Texts and Adding Additional Languages section.
Adding Additional Languages to the Portal
For details on enabling more languages in the Portal, refer to the Adding Support for Additional Languages documentation.
AOPP Portal
The AOPP Portal verifies ownership of self-hosted wallets using digital signatures. Request a proof link, forward it to your customer, and track the proof in the Self-Hosted Wallets table.
Obtaining an AOPP Portal Link
Open AOPP Portal Link Modal
In the 21 Travel dashboard, navigate to Self-Hosted Wallets and click
AOPP Portal Link.
Fill Out AOPP Portal Link Form
Customer ID
Your customer's ID from your user database.
Customer's Wallet Address (Optional)
You can optionally specify the customer's wallet address. If specified, the proof submitted by your customer will only be accepted if it cryptographically proves wallet ownership by your customer of that specific wallet address.
Signed Message (Optional)
You can pick the message your customer is expected to sign. If omitted, a message based on a UUID and a timestamp is generated for you.
Comment (Optional)
An optional comment.
Digital Asset
The digital asset the proof should be submitted for.
Submit to Receive the AOPP Portal Link
Click Get AOPP Portal Link to create a pending signature proof and open its
detail modal. The modal shows the proof details and a prompt to forward the link
to your customer. Use the copy button next to the URL to copy it.
The request appears immediately in the Self-Hosted Wallets table with a
Pending status. If you did not specify a wallet address, it shows
Awaiting address until your customer submits the proof. You can reopen the
detail modal from the table to copy the link again. When your customer submits a
valid signature, the same proof updates to Verified in both the table and the
open detail modal.
If you are integrating with the 21 Travel Rule API, obtain an AOPP Portal Link
with the requestAoppProof mutation.
Optional Redirect Query Argument
The AOPP Portal supports the usage of a redirect query argument, which can be optionally added after you have obtained the AOPP Portal Link from the API:
https://aopp-portal.vasp.com/someid?redirect=www.vasp.com
By using the redirect query argument, a VASP can redirect a customer back to its main site upon successful proof submission. A valid URL must be entered, or the query argument will be ignored.
Satoshi Proof Portal
The Satoshi proof method involves the customer sending a minimal amount of a digital asset to verify they own the self-hosted wallet account. As opposed to the digital signature proofs automated by the AOPP Portal, this method requires a final verification step by the compliance officer, or integration into your custody system, after the user has submitted the Satoshi proof.
Obtaining a Satoshi Proof Link
In the 21 Travel dashboard, navigate to Self-Hosted Wallets and click
Satoshi Test Link.
Fill in the corresponding values in the form. You will have another chance to add a comment at the final stage of the workflow.
The Satoshi Proof Link appears after you click Get Satoshi Test Link.
If you are integrating with the 21 Travel Rule API, a Satoshi Proof Link can be
obtained with the requestSatoshiProof mutation.
Optional Redirect Query Argument
The Satoshi Portal supports an optional redirect query argument, which you can add after obtaining the Satoshi Proof Link from the API:
https://aopp-portal.vasp.com/satoshi/someid?redirect=www.vasp.com
By using the redirect query argument /someid?redirect=www.vasp.com, a VASP can
redirect a customer back to its main site upon successful proof submission. A
valid URL must be entered, or the query argument will be ignored.
User Submits a Transaction ID
When the user navigates to the Satoshi Proof Link, he will be able to submit a transaction ID for a transaction that fulfils the Satoshi Proof criteria:
If you wish to change the amount that should be transferred, you can always modify this in the Configure Your VASP settings.
Verifying the Satoshi Proof
As a final step, you need to verify that the transaction sent the correct number of coins from the correct address. To do so, click on the Proofs Overview entry, or on the verify button represented by a tick (✔). On the form, you can optionally add a comment and documents, and either approve or decline the proof:
You can also use the aopdProofs subscription with an AopdSatoshiProof
fragment, e.g. using the
integration client SDK:
subscription {
aopdProofs {
__typename
... on AopdSatoshiProof {
id
status
txId
}
}
}
This subscription emits updates for all proof types. Process Satoshi proofs with
status SUBMITTED to identify those awaiting verification.
To automate verification, your custody integration must check the transfer's
sender address, deposit address, and amount, then record the assessment with
aopd.finalizeSatoshiProof. An approved proof becomes Verified; a declined
proof becomes Failed. Receiving a submission event or redirecting the customer
back from the portal does not complete this verification.
Expired Satoshi Proofs
Satoshi Proofs that are not submitted by the customer within the time window configured in the settings will automatically expire. The table shows them with a Failed status and an expiry note in the Proof column.
Clicking on such a proof will open the detail view where the proof can be
reattempted for a new time window by clicking the Request another proof
button.
To change the comment, click the pencil icon next to Comment in the proof's
detail view.
Customising Portal Texts and Adding Additional Languages
This guide explains how to tailor the Portal’s interface by customising its text and adding support for additional languages. By changing which texts are shown to users, you can ensure the Portal matches your organisation’s language requirements and provides a localised experience for users worldwide.
Background Information
The portal language configuration can be managed directly from the dashboard. Under Configure Your VASP, navigate to Address Ownership → Portal Customisation in the settings.
Obtaining the Default lang.json
Download the current lang.json using the download button next to the
Language field. This file contains all translatable strings used throughout
the portal interface.
Customising Existing Text
Open lang.json and modify the existing text strings at will. Uploads replace
the entire language configuration. Retain all languages you want to offer and
the complete set of string keys for each language. Missing keys do not fall back
to English and can prevent the portal from rendering correctly.
Adding Support for Additional Languages
Open lang.json and add new top-level object keys for the desired languages and
translations for all the existing text strings. The new top-level keys need to
follow the
BCP 47 language tag
format, e.g. "de-CH" for Swiss-German. Only then the Portal will automatically
switch to the user's preferred language.
This task can be automated using one of the popular AI tools but the translations likely still need manual adjustments.
Uploading the Modified lang.json
Once the file is ready, upload it using the Language field in Address Ownership → Portal Customisation and save the settings.
Customising the Portal Appearance
This guide explains how to tailor the Portal's visual appearance to match your organisation's branding. By adjusting colours, typography, and other design tokens, you can ensure the Portal looks and feels consistent with your brand.
Background Information
The portal theme configuration can be managed directly from the dashboard. Under Configure Your VASP, navigate to Address Ownership → Portal Customisation in the settings.
Obtaining the Default theme.json
Download the current theme.json using the download button next to the
Theme field. This file contains a selection of the design tokens supported
by the portal.
Customising the Appearance
Open theme.json and adjust the values according to the
Ant Design theme API. This
allows you to customise colours, typography, and other design tokens. Only the
keys present in the uploaded file will be overridden — any keys not included
will fall back to the default theme.
Uploading the Modified theme.json
Once the file is ready, upload it using the Theme field in Address Ownership → Portal Customisation and save the settings.
Reference Deployment
21 Travel Rule is a software solution for FATF’s Travel Rule by 21 Analytics.
Important
These instructions only work if you have a valid 21 Travel Rule license, which comes with a username and password for OCI registry access.
If you get stuck with the deployment instructions then please refer to the Troubleshooting section where common usage errors are clarified.
Required Tools
To run 21 Travel Rule the following tools needs to be installed:
- Podman (version 5.8.6 or higher)
- helm (version 3.8.0 or higher)
- yq (The Golang version is preferred over the Python one)
- git
- systemd (installed by default on all popular Linux distributions)
Any operating system which can run Linux OCI containers will work.
Best-Practise Deployment Strategy
- Follow the reference deployment closely!
- Avoid changes to the architecture.
- Avoid pre-mature optimisations. E.g. splitting the service tables into multiple databases instead of multiple schemas won't work.
Deployment Checklist
The deployment checklist is a guideline for DevOps teams to keep track of their deployment and configuration progress:
- Successfully logged in into the 21 Analytics OCI registry
- Successfully deployed the container services as described below
- Verified that the container services don't crash but run without restarts
- Successfully logged in as admin into Keycloak
- Successfully created first user in Keycloak
- Successfully logged in with created user into Compliance Dashboard
- Successfully verified that the REST interfaces of
trpdandtrustdare publicly accessible (required for VASP to VASP messaging) - Successfully verified that the GraphQL interface of
aopdis publicly accessible (required for AOPP Portal) - Successfully verified that the static files served by the
aopp-portalcontainer are publicly accessible (required for AOPP Portal) - Successfully configured all required modules (TRUST, TRP, EMAIL) using the Compliance Dashboard user interface
- Successfully opened the AOPP Portal user interface and observed the "Invalid AOPP Portal Link" error message. Only links created using the Compliance Dashboard are valid.
After the steps above have been fully completed, continue with the checklist for functional testing:
- Successfully created a test customer with a Bitcoin account in the Travel Address Book
- Successfully sent an outgoing TRP notification to Henry Foster using
Bitcoin to Travel Address
ta24asGLrECMNQPtNt6SoMsgBHkg6zD7pFkkMHp9TRFYEuTs9GXTn1xDDZ65hQXbk3hoMQm6HKK7UozDvTkeWZeT1NtzoXTb42mS7PB4CyNYRsAg - Successfully requested an AOPP Proof and opened the returned Portal link displaying different Wallets
- Successfully sent an outgoing Encrypted Email notification to a "Test VASP" configured with an email address whose inbox can be accessed by you
- Successfully received the Encrypted Email
- Successfully replied to the Encrypted Email (i.e. the "FROM" email address was configured without typos)
Deployment with Podman Quadlet
Clone Git Repository
First, clone the deployment git repository with
git clone https://gitlab.com/21analytics/21-travel-deployment.git
Log into Container Registry
Second, log in to the container registry using the username / password that you have obtained from 21 Analytics by executing the following two commands:
podman login registry.21analytics.ch -u YourUsername
helm registry login registry.21analytics.ch -u YourUsername
Edit Minimum Configuration
Then edit values.yaml which is the minimum configuration required for
deployment.
You probably want to commit your changes to values.yaml to simplify upgrades
later:
git add values.yaml
git commit -m "values.yaml: save configuration"
Generate Deployment YAML Files
The YAML files declaring the entire deployment can be generated with the following command.
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule -f values.yaml > quadlet/travel.yaml
Extract Secrets
Run the interactive extract_secrets.sh script to obtain and backup
auto-generated secrets. NOTE: losing the secrets will cut-off your access to
all productive data.
./extract_secrets.sh
After that, you can spin up the services as shown in the next subsection.
Start 21 Travel Platform
The following commands will register the 21 Travel platform to be managed by
systemd and instruct it to start the platform.
podman quadlet install ./quadlet
systemctl daemon-reload
systemctl start travel.service
Allow approximately three minutes for all services to start up.
Useful Systemd Commands
Stopping Services
systemctl stop travel.service
Checking the Status
systemctl status travel.service
Reading the Logs
journalctl -xeu travel.service
User Management
The reference deployment uses a Keycloak service to manage user accounts. Please refer to the Keycloak page for more information.
Logging
All 21 Travel Rule services emit log messages. The log level can be adjusted by
setting the corresponding settings in values.yaml. Starting with the least
verbose level the available log levels are:
errorwarninfodebugtrace
where info is the default log level.
Furthermore, it is possible to selectively adjust the logging level for certain
modules only (the module names can be obtained from existing logging output),
e.g. to increase the logging level for HTTP traffic tower_http::trace=debug
should be set.
Compliance Dashboard and AOPP Portal
The Compliance Dashboard and AOPP Portal can be accessed on the domains
configured in values.yaml. Both need to be served from the root path /.
Upgrade
For an upgrade from version 8.3.0 to version 8.4.0 please refer to the upgrade guide.
APIs Exposed by Reverse Proxy
This section documents the API endpoints that require to be publicly accessible. This is meant as a reference for firewall and WAF (Web Application Firewall) configuration.
TRUST:
443 (HTTPS) unterminated TLS Incoming as well as TCP Outgoing.
This has to be accessible for your counterparty VASPs.
Travel Rule Protocol (TRP):
443 (HTTPS) at /transfers and
/transfers/
TCP Incoming and Outgoing. This has to be accessible for your
counterparty VASPs.
AOPP
443 (HTTPS) at /proofs/ TCP, incoming only. This has to be
accessible by your customers.
Working with OpenShift/Kubernetes
The helm charts found at
oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule offer a good
starting point for various Kubernetes deployments. Consult the next sections to
get hints on customisation.
Configuring Your Ingress Proxy
You very likely have an ingress proxy running in your cluster already.
HAProxy, which is used as an ingress proxy in the reference deployment, can be
disabled in values.yaml. You can extract its configuration from the
ConfigMap and easily port it to any ingress proxy, e.g. by using AI tools.
Using an Existing Postgres Database
Set postgres.host in your values.yaml file to prevent deploying an
in-cluster database. The provided value will be used by helm to assemble the
database connection string passed to all relevant services.
Using an Existing S3-Compatible Storage
Media is stored in the bundled SeaweedFS by default. To use an external
S3-compatible storage (e.g. AWS S3, Azure Blob Storage, Google Cloud Storage)
instead, set s3.endpoint, s3.bucket, s3.region, secrets.s3AccessKey and
secrets.s3SecretKey in your values.yaml file.
Additionally, set travelServices.autod.extraArgs to [] to remove the default
--seaweedfs argument, which would otherwise make autod try to migrate data
from the no-longer-deployed SeaweedFS.
TLS Certificates
TLS certificates are automatically set up using the
ACME
protocol. The only pre-requisite is to configure your domains in the
values.yaml after you have registered them with your
domain name registrar.
Configuring Postgres with TLS
This document describes the steps required to configure a TLS connection for Postgres.
Set sslmode
sslmode needs to be set in the Postgres connection string as explained in the
official Postgres documentation.
Configure CA for Self-Signed Certificates
This only needs to be done in case you have signed the certificates with your own private CA.
Mount CA PEM File into Container
Your CA PEM file needs to be mounted into the container running the services that should establish a TLS connection with Postgres. You can choose an arbitrary path inside the container.
Set SSL_CERT_FILE or SSL_CERT_DIR
Set either the container environment variable SSL_CERT_FILE or SSL_CERT_DIR
to point to the file or directory, respectively, you have mounted your CA PEM
file to.
Keycloak
The reference 21travel deployment uses a Keycloak
service to manage users. This allows transparent delegation to IAM solutions
already in place, for example via Keycloak's
LDAP integrations.
Keycloak can also broker identities from external IAM systems using standard
protocols such as OpenID Connect and SAML.
Guides
New users can be added using this guide.
Enterprise customers can control access to the Compliance Dashboard and GraphQL API with user permissions.
Manually Adding Users
To add users manually via Keycloak's web interface, follow these steps to create and configure new compliance officer accounts for your organisation:
Obtain Keycloak Admin URL
Locate your Keycloak instance at compliance-dashboard.yourDomain.com/auth,
where compliance-dashboard.yourDomain.com should be replaced with the URL
where your Compliance Dashboard is accessed from (compare with
.Values.complianceDashboard.domain).
Login Into Keycloak As Admin
Login with the admin credentials you provisioned when spawning the reference
deployment (.Values.keycloak.adminUser and
.Values.secrets.keycloakAdminPassword).
Select Realm
In the menu at the top left you will see that the master Keycloak realm is
selected by default.
Click on Manage Realms and click on 21travel.
You should now see that 21travel (displayed as "21 Analytics") is now the
current realm.
Navigate To Users Tab
Go to "Users". The screenshot below shows an existing user. On a fresh installation, the user list may be empty.
Create New User
Click "Create new user" if the user list is empty, or "Add user" if users already exist, and add the Username for the compliance officer user.
Click on "Create". You will then be redirected to the Details tab where you can see the information you provided.
Set Temporary Password For New User
Next, navigate to the Credentials tab to set a temporary password.
Now click on "Set Password" and add a temporary password. Make sure the temporary toggle is active. Once the password is set click on "Save" and then confirm by clicking on "Save Password".
Assign Permissions (Enterprise)
On a new Enterprise instance, the user has no 21 Travel Rule permissions until
you assign roles. Follow the
authorisation guide before asking
them to sign in. If you do not need restricted access, assign the travel.admin
role to give the user full access.
Inform Compliance Officer about Created Username and Password
You can now give the username and password to the compliance officer user so they can log in. They will be requested to update their password.
Afterwards, you can log in with your created users into the 21travel
compliance dashboard. The documentation uses another user name 'Bitcoin Exchange
AG' throughout.
Authorisation
Role-based permissions for the Compliance Dashboard and GraphQL API are
available only to Enterprise customers. On a new instance, the 21travel
Keycloak realm contains the permission roles, but new users receive none of them
automatically. Assign roles before users sign in. A user without the required
roles can authenticate but cannot perform the protected actions.
Give a User Full Access
If you do not need to restrict a user's access, assign travel.admin. This
composite role grants all the read and write permissions listed below. Do this
for each new user who should have full access; the Keycloak admin
account used to manage users is separate from a Compliance Dashboard user.
Assign Roles to a User
- Sign in to the
Keycloak Administration Console
and select the
21travelrealm. - Open Users, select the user, and open Role mapping.
- Click Assign role and choose Client roles.
- Find
travel.adminunder theaccountclient, or select the specific roles the user needs, and click Assign. - Ask the user to sign out and sign in again so their access token includes the new roles.
The roles belong to the account client, not the realm. The reference
deployment uses account as its compliance client. If you configure a different
compliance client, create the corresponding roles there and ensure they are
included in the user's access token.
Choose a Role Set
| Client role | Access granted |
|---|---|
travel.read | All read permissions in the table below. |
travel.write | All write permissions in the table below. |
travel.admin | Both travel.read and travel.write. |
travel.write does not include travel.read. Assign both for users who need to
view and change all data, or use travel.admin. You can assign individual roles
for narrower access.
| Client role | Access granted |
|---|---|
travel.configuration.read | View your VASP configuration and ownership portal settings. |
travel.configuration.write | Change your VASP configuration and ownership portal settings. |
travel.transactions.read | View and export transactions, generate transaction reports, and receive transaction updates. |
travel.transactions.write | Register, send, approve, decline, confirm, or cancel transactions. |
travel.fiat_prices.write | Set the fiat price for a transaction. |
trpd.customers.read | View and search customers in the Travel Address Book. |
autod.customers.write | Register customers and update their wallet addresses. |
trpd.vasps.read | View TRP counterparty VASPs. |
trpd.vasps.write | Manage TRP counterparty VASPs. |
trustd.vasps.read | View TRUST counterparty VASPs. |
trustd.vasps.write | Manage TRUST counterparty VASPs. |
email.vasps.read | View email counterparty VASPs. |
email.vasps.write | Manage email counterparty VASPs. |
aopd.proofs.read | View and export self-hosted wallet proofs and receive proof updates. |
aopd.proofs.write | Request, register, review, and update self-hosted wallet proofs. |
aopd.risk_scores.write | Set or refresh risk scores for self-hosted wallet proofs. |
trpd.risk_scores.write | Set or refresh transaction risk scores. |
autod.audit_logs.read | View and export the audit log. |
Create Your Own Role Bundles
You can create a Keycloak composite client role to give a team a chosen subset of the individual roles above. Assign the bundle to users instead of assigning each permission separately. For example:
| Bundle example | Associated client roles | Result |
|---|---|---|
travel.audit_reviewer | travel.transactions.read, autod.audit_logs.read | Can inspect transactions and audit logs, but cannot change transactions or open the Travel Address Book and proofs. |
travel.trp_vasp_manager | trpd.vasps.read, trpd.vasps.write | Can view and manage TRP counterparty VASPs without access to TRUST or email VASPs. |
To create either bundle in the 21travel realm:
- Open Clients → account → Roles and click Create role. Give it the example name, or a name that describes your team's duties, and save it.
- Open the new role and choose Action → Add associated roles. Select
Client roles from the
accountclient and add the individual roles in the table. This makes the new role a composite. - Assign the new role to users through Users → the user → Role mapping → Assign role → Client roles. Users inherit its associated permissions.
For more on Keycloak composite roles, see the Keycloak Server Administration Guide.
User Interface Behaviour
The dashboard hides configuration navigation when the user has neither
configuration role, and hides the audit log entry without
autod.audit_logs.read. Controls for actions without a required write role are
disabled and show the missing permission when hovered over. GraphQL checks roles
independently of the dashboard: a request for a protected field without its role
returns an error such as
Forbidden: missing required role 'travel.transactions.read'. GraphQL
subscriptions require the matching read role as well.
API Integrations
For API integrations, assign roles to the user or service account that obtains
the access token. The token must contain the
roles for the configured compliance client. For a client credentials
integration, open that API client in Keycloak and assign its service account the
required account client roles under Service account roles.
Risk Score Providers
21 Travel Rule offers a flexible risk score integration interface.
The obtained risk scores can then be consumed via the GraphQL API or inspected in the Compliance Dashboard.
There is built-in support for Chainalysis, Beosin, Crystal, Global Ledger, and Merkle Science. Other risk providers can be integrated quickly using the integration client SDK.
Chainalysis
Follow the steps below to enable support for Chainalysis risk scores.
Get Chainalysis API Key
Obtain a Chainalysis API key.
Configure API Key for TRP
Add the Chainalysis API Key in the TRP configuration section to enable risk scores for TRP.
Configure API Key for Self-Hosted Wallet Proofs
Add the Chainalysis API Key in the Address Ownership configuration section to enable risk scores for self-hosted wallet proofs.
Beosin
Follow the steps below to enable support for Beosin risk scores.
Get Beosin API Keys
Obtain the appId and appSecret as described in the
Beosin API Access Key documentation.
Get 21 Travel Rule Secrets
Obtain the clientId and clientSecret as described in the
API Authentication Guide.
Configure Secrets on Deployment Machine
Add the new secrets to your values.yaml file.
integrations:
beosin:
enabled: true
clientId: "🤫🤫🤫🤫🤫🤫"
clientSecret: "🤐🤐🤐🤐🤐🤐"
appId: "🤫🤫🤫🤐🤐🤐"
appSecret: "🤐🤐🤐🤫🤫🤫"
Then, proceed with the following commands.
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule -f values.yaml -f secrets.yaml > quadlet/travel.yaml
systemctl stop travel.service
podman quadlet rm ./quadlet
podman quadlet install ./quadlet
systemctl daemon-reload
systemctl start travel.service
Crystal
Follow the steps below to enable support for Crystal risk scores.
Get Crystal API Key
Obtain the API Key, later referred to as apiKey, from the
Crystal Intelligence User Portal.
Get 21 Travel Rule Secrets
Obtain the clientId and clientSecret as described in the
API Authentication Guide.
Configure Secrets on Deployment Machine
Add the new secrets to your values.yaml file.
integrations:
crystal:
enabled: true
clientId: "🤫🤫🤫🤫🤫🤫"
clientSecret: "🤐🤐🤐🤐🤐🤐"
apiKey: "🤫🤫🤫🤐🤐🤐"
Then, proceed with the following commands.
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule -f values.yaml -f secrets.yaml > quadlet/travel.yaml
systemctl stop travel.service
podman quadlet rm ./quadlet
podman quadlet install ./quadlet
systemctl daemon-reload
systemctl start travel.service
Global Ledger
Follow the steps below to enable support for Global Ledger risk scores.
Get Global Ledger API Key
Obtain the API KEY, later referred to as apiKey, from the
Global Ledger Profile page.
Get 21 Travel Rule Secrets
Obtain the clientId and clientSecret as described in the
API Authentication Guide.
Configure Secrets on Deployment Machine
Add the new secrets to your values.yaml file.
integrations:
globalledger:
enabled: true
clientId: "🤫🤫🤫🤫🤫🤫"
clientSecret: "🤐🤐🤐🤐🤐🤐"
apiKey: "🤫🤫🤫🤐🤐🤐"
Then, proceed with the following commands.
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule -f values.yaml -f secrets.yaml > quadlet/travel.yaml
systemctl stop travel.service
podman quadlet rm ./quadlet
podman quadlet install ./quadlet
systemctl daemon-reload
systemctl start travel.service
Merkle Science
Follow the steps below to enable support for Merkle Science risk scores.
Get Merkle Science API Key
Obtain the API KEY , later referred to as apiKey,
as described here.
Get 21 Travel Rule Secrets
Obtain the clientId and clientSecret as described in the
API Authentication Guide.
Configure Secrets on Deployment Machine
Add the new secrets to your values.yaml file.
integrations:
merklescience:
enabled: true
clientId: "🤫🤫🤫🤫🤫🤫"
clientSecret: "🤐🤐🤐🤐🤐🤐"
apiKey: "🤫🤫🤫🤐🤐🤐"
Then, proceed with the following commands.
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule -f values.yaml -f secrets.yaml > quadlet/travel.yaml
systemctl stop travel.service
podman quadlet rm ./quadlet
podman quadlet install ./quadlet
systemctl daemon-reload
systemctl start travel.service
Upgrade Guide 8.3.0 to 8.4.0
Important
If you are upgrading from version 8.2.x you must upgrade to version 8.3.0 first!
Important Note
Warning
Acceptance Testing
Before upgrading your production instance, 21 Analytics encourages you to exercise the upgrade scenario on your acceptance testing instance.
Update Deployment YAML Files
Just enter the following to update the deployment configuration:
helm template prod oci://registry.21analytics.ch/21analytics/twenty-one-travel-rule --version 0.4.x -f values.yaml -f secrets.yaml > quadlet/travel.yaml
podman quadlet install --replace ./quadlet
Restart 21 Travel Rule
A restart is required to apply the new deployment.
systemctl restart travel.service
Consolidate SeaweedFS Volumes (Optional)
NOTE: this applies to SeaweedFS users only!
Use this procedure to consolidate partially used volumes in the default (unnamed) collection and free volume slots for other collections.
Important: Only merge volumes from the same collection. Verify that the destination has enough free capacity for all data on the source volume.
1. Start a SeaweedFS shell
podman exec -it <seaweedfs-container> weed shell
2. Identify the source and destination volumes
List the current volumes:
volume.list
Volumes in the default collection have an empty Collection: field:
DataNode <data-node> ...
...
volume Id:1, Size:..., Collection:, ...
volume Id:2, Size:..., Collection:, ...
volume Id:3, Size:..., Collection:, ...
volume Id:4, Size:..., Collection:, ...
Choose:
- a source volume to remove
- a destination volume with enough free capacity
- the
DataNodehosting the source volume
The example below merges volume 4 into volume 1. The source volume is hosted
on <data-node>.
3. Lock administration and mark the source read-only
lock
volume.mark -node=<data-node> -volumeId=4 -readonlyCanDelete
Mark only the source volume read-only.
The administrative lock does not block application or filer writes.
-readonlyCanDelete prevents new data from being assigned to the source while
still allowing cleanup.
4. Run the first merge
fs.mergeVolumes -fromVolumeId=4 -toVolumeId=1 -apply
Writes already in progress when the source became read-only may not yet have committed their filer metadata and can therefore be missed by this pass.
5. Wait for the safety window and merge again
Wait until the source volume has been read-only for at least 10 minutes. If the first merge took 10 minutes or longer, no additional wait is needed.
Then run the merge again:
fs.mergeVolumes -fromVolumeId=4 -toVolumeId=1 -apply
6. Check the remaining files
volume.fsck -volumeId=4 -cutoffTimeAgo=10m
Continue only if all remaining files are reported as orphaned:
dataNode:... volume:4 entries:4 orphan:4 100.00%
Total entries:4 orphan:4 100.00%
The 10m cutoff is the safety window for in-flight writes to finish committing
filer metadata. If you use a different cutoff, wait at least that long after
marking the source read-only before performing the final merge and fsck.
If any referenced files remain:
- Do not delete anything.
- Run
fs.mergeVolumesagain. - Repeat
volume.fsck. - Investigate if referenced files continue to remain.
7. Delete orphaned files
Once all remaining files are confirmed orphaned:
volume.fsck -volumeId=4 -cutoffTimeAgo=10m -reallyDeleteFromVolume
8. Compact the source volume
volume.vacuum -volumeId=4 -garbageThreshold=0
9. Verify that the source is empty
volume.list -volumeId=4
An empty volume should contain only the volume header:
Size:8
FileCount:0
DeleteCount:0
If the volume is not empty, do not delete it. Repeat the merge and fsck
steps and investigate the remaining files.
10. Delete the empty volume and unlock
Delete the source volume from the same DataNode identified earlier:
volume.delete -node=<data-node> -volumeId=4
unlock
11. Verify the freed slot
volume.list
The topology should show an additional free volume slot, for example:
hdd(volume:3/5 active:3 free:2 remote:0)
Repeat the procedure for other partially used volumes where consolidation is appropriate.
GraphQL API Changes
The GraphQL API has been improved and extended in numerous ways. This section mainly highlights the changes that could potentially be breaking for existing API integrations.
Version 8.4.0 changes email configuration, introduces new fiat price support and new asset variants, removes previously deprecated items and introduces new deprecations.
Changes to Configuration
- The
smtpPasswordfield was removed fromEmailConfigurationandEmailConfigurationInput. Configuration queries now exposesmtpAuth, and configuration inputs acceptsmtpAuthSecret. For password authentication, passsmtpAuthSecret: { password: { password: "..." } }instead. The same input also supports Microsoft OAuth 2.0 through theoauth2variant.
New Fiat Price Support
Transaction detail objects for Email, Offline, TRP (including transactions
within your VASP) and TRUST now expose fiatPrices. The
AutodMutation.setProviderFiatPrice mutation accepts a transaction ID, a
provider name and a TravelFiatPriceInput containing a price and currency. It
returns the updated transaction as TravelTx!. Prices from other providers are
preserved.
The AutodAuditEvent enum has gained the AUTOD_SET_FIAT_PRICE value for this
mutation.
New Asset and Ledger Support
New values were added to Asset, AopdAsset and AopdLedger. The new ledger
values are ARBITRUM, AVALANCHE, BASE, BTC_TESTNET3, BTC_TESTNET4,
GNOSIS and OPTIMISM.
Removal of deprecated items
- The previously deprecated
proof,proofForAddress,proofForXpubandproofsForCustomerqueries onAopdwere removed. Please use theproofsquery with a suitablefilterargument instead. - The previously deprecated
proofAsXlsxquery onAopdwas removed. Please useproofsAsXlsxwith a suitablefilterinstead. The XLSX file format remains the same. - The previously deprecated
txDetailandtxsWithTxIdqueries onAutodwere removed. Please usetxDetailswith a suitablefilterinstead. - The previously deprecated
txAsXlsxquery onAutodwas removed. Please usetxsAsXlsxwith a suitablefilterinstead. The XLSX file format remains the same. - The previously deprecated
vaspquery onEmailwas removed. Please usevaspswith a suitablefilterinstead. - The previously deprecated
statusargument to thetxDetails,txDetailsCountandtxsAsXlsxqueries onAutodwas removed. Please use thefilterargument to select transactions by status instead. - The previously deprecated
msginput field onAopdExpectedAoppProofInputwas removed. Please usemessageinstead. - The previously deprecated
xpubRequiredinput field onAopdExpectedAoppProofInputwas removed. Please specify the expectedaddressinstead. For assets such as Bitcoin, this implicitly requires an xpub and verifies the expected address against it. - The previously deprecated
ANYandSTANDARDvalues onAopdAddressFormatwere removed. Please usenullinstead. - The previously deprecated
custodialUserquery onTrpdwas removed. Please usecustodialUserswith a suitablefilterinstead. - The previously deprecated
registerCustodialUserandsetWalletAddressmutations onTrpdMutationwere removed. Please use the mutations with the same names underAutodMutationinstead.
New Deprecations
The following items have been deprecated and will be removed in a future release. Please consult the deprecation field for instructions on how to upgrade.
- The
timestampedPricefield onEmailTxDetails,OfflineTxDetails,TrpdIntravaspTxDetails,TrpdSentTxDetails,TrpdTxDetailsandTrustdTxDetails. This only supports USD prices from BitMEX. Please usefiatPriceson the transaction instead. - The
inquiremutation onTrpdMutation. Please usesendTxToAddrOwnerunderAutodMutationinstead. - The
lookupAddressDirectoryquery onTrpd. This will be removed without replacement.
Troubleshooting
Find quick answers and practical solutions to common deployment and runtime issues, helping you keep your environment running smoothly.
I'm seeing error messages in the SeaweedFS Container
At the start, the SeaweedFS container repeatedly shows two error messages in the log (RPC error and missing pemfile). Both can safely be ignored when using the reference deployment as they are triggered by its internal service being started while polling on each other.
'Unknown User' in transactions
This error originates from the migration to new db structure, which requires exact match of the name and surname in transaction originator and custodial data. Having 'Unknown User' as originator in transactions means that some of the old sent transactions does not match the entry in the customers list.
I'm seeing 'Could not apply database migration' errors in the travel-autod container
Any errors relating to the add_transactions_view migration will be transitory
and disappear once the other services have successfully run their migrations.
The travel-autod container will automatically restart until this is resolved.
I'm seeing warnings regarding OCSP in the travel-trustd container
If you are seeing warnings that contain OCSP (Online Certificate Status Protocol), it means that the status of the server certificate that you provided for TRUST could not be automatically obtained. This could prevent counterparty VASPs from sending TRUST Travel Rule messages to your VASP. To fix this, ensure that your Certificate Authority provides an OCSP endpoint and that its URL is correctly encoded in the certificate.
Travel Rule
To understand the purpose of 21 Travel Rule, it helps to clarify what the Travel Rule is. The Travel Rule is a recommendation issued by the Financial Action Task Force (FATF) to address money laundering and terrorist financing. It requires specific personal data to be exchanged with digital asset transactions.
Because the Travel Rule is a recommendation, countries are not required to implement it by a specific date or at all. As a result, adoption and scope vary globally. Implementing jurisdictions may also deviate from the recommendation in the type of information exchanged or when it must be exchanged. Once adopted in a jurisdiction, the Travel Rule becomes law, and failing to exchange this information is illegal. In practice, virtual asset service providers (VASPs), such as exchanges and banks, must collect and store the required customer information.
Collecting, tracking, and storing this information can be complex and error-prone without the right tooling. 21 Travel Rule enables VASP compliance teams to manage and retain the required data for each processed transaction in a consistent, auditable way.
Address Ownership
Address ownership tackles a specific problem within the Travel Rule: self-hosted wallet transactions. Unlike virtual asset service providers (VASPs), which hold digital assets on behalf of the owner, self-hosted wallets allow the owner to hold digital assets and control the private key used to transact themselves.
Self-hosted wallets are a greater challenge when it comes to requesting and storing personal data since there is no organisation behind it, and expecting every individual who owns a wallet to store the personal information of their counterparts and the transaction is unfeasible. Moreover, it would pose a big risk regarding data security.
The closest solution so far is requesting to prove ownership of a self-hosted wallet when depositing or withdrawing from a VASP. This means VASPs have the responsibility to validate that their customer owns a given self-hosted wallet and store this proof.
AOPP (Digital Signature Proofs)
For every wallet address there's a unique corresponding private key. Such a private key is used to authorise the spending of coins belonging to said wallet address by digitally signing a transaction. The transaction is validated by the miners by verifying the correctness of the digital signature. Only when the digital signature is correct, the transaction is deemed valid and added to the next mined block.
With AOPP, the unique relationship between the wallet address and private key is utilised to prove address ownership. Instead of signing a transaction, a predetermined message (usually a human-readable text) is signed and the resulting digital signature is submitted to 21 Travel Rule. By asserting the correctness of the digital signature 21 Travel Rule can deduce that the submitter of the message's digital signature owns the private key that can also be utilised to craft a valid transaction for the corresponding wallet address.
TRUST Flow
TRUST (Travel Rule Universal Solution Technology) is a Travel Rule messaging framework used by participating VASPs to exchange required originator and beneficiary information directly with each other through encrypted channels.
Participating in TRUST requires onboarding with the TRUST organisation and configuration of your instance. Follow the TRUST Onboarding guide for membership, bulletin board registration, and setup of 21 Travel Rule. Afterwards, 21 Travel Rule will take care of all the protocol steps, interacting with the TRUST Bulletin Board, as well as TRUST counterparty VASPs.
The following sections describe the protocol at a high level. For an in-depth protocol and network overview, see the TRUST documentation. For certificate onboarding guidance, see Obtaining Certificates.
Counterparty Discovery and the Bulletin Board
The TRUST organisation maintains and runs a bulletin board where the counterparty of a particular transaction can be discovered based on the digital asset wallet address alone. This will become apparent in the two transaction flows detailed below.
The Outgoing Transaction Flow
21 Travel Rule handles counterparty discovery and Travel Rule messaging. Your custody system executes the blockchain transfer. The Outgoing Transaction form and API require its transaction ID when sending a TRUST notification.
-
Your customer wants to send funds to a digital wallet address belonging to another TRUST VASP.
-
You collect the beneficiary name from your user. Once your custody system has executed the transfer, submit that name, the destination wallet address, and the blockchain transaction ID to 21 Travel Rule.
-
21 Travel Rule will query the bulletin board for the beneficiary VASP information and learn where Travel Rule data can be submitted. 21 Travel Rule will then send the Travel Rule payload to the beneficiary VASP. The record appears in Archived; there is no TRP approval and confirmation exchange.
The Incoming Transaction Flow
The below protocol steps are all handled by 21 Travel Rule. You only need to make your customer's wallet address available to the sender and review the received Travel Rule data before crediting your customer.
-
Your customer wants to receive funds to a digital wallet address that is hosted by your TRUST VASP. You register the user together with the digital wallet address with 21 Travel Rule.
-
The originator VASP queries the bulletin board with that wallet address to discover your VASP information and learn where Travel Rule data can be submitted.
-
The originator VASP sends the Travel Rule payload to 21 Travel Rule via TRUST. 21 Travel Rule receives and validates the data, after which you can review it in your compliance workflow before crediting your customer.
Travel Rule Protocol (TRP) Flow
To solve the Travel Rule requirements, numerous protocols have been created. The Travel Rule Protocol (TRP) is one of these solutions, distinguished by the fact that it is an open standard, and participation in the protocol is completely permissionless. The 21 Analytics team contributes to its development and evolution.
21 Analytics develops 21 Travel Rule to make TRP straightforward to use while protecting the personal and financial information exchanged between VASPs.
The following steps describe the TRP flow in 21 Travel Rule:
-
A beneficiary VASP creates a Travel Address for one of its users.
-
An originator VASP sends a transaction request to a beneficiary VASP using this Travel Address.
-
The beneficiary VASP runs chosen regulatory and security checks on the originator User. If it gets declined, this is then archived.
-
If the beneficiary VASP approves, the originator VASP performs the on chain transaction and notifies the beneficiary of the transaction by clicking on Confirm. The originator can also opt to not perform the on chain transaction and notify the beneficiary by clicking on Cancel.
Bear in mind this is an explanation of the user flow in 21 Travel Rule; for a more in-depth explanation of the protocol, check TRP.
Email Flow
Use encrypted email to exchange Travel Rule data with a counterparty VASP when TRP or TRUST cannot be used. Choose the flow that matches your customer's role:
- If your customer receives funds from a counterparty VASP's customer, follow the Incoming Transaction Email Flow.
- If your customer sends funds to a counterparty VASP's customer, follow the Outgoing Transaction Email Flow.
Incoming Transaction Email Flow
Use this flow when your customer receives funds from a counterparty VASP's customer. Open Incoming Transaction on the Transactions page and choose to request confirmation by email:
-
Before your customer can receive funds from a counterparty VASP's customer, you must first fill out the Incoming Transaction form, where you must provide the beneficiary information as well as the originator information provided by your customer. Once you have submitted the form, 21 Travel Rule will send an email to your counterparty VASP asking for confirmation and archive the record.
-
Your counterparty VASP should confirm that the originator of the transaction is indeed one of their customers and send you an email stating this.
-
You can then proceed to credit your beneficiary customer with the funds.
You can see the email flow for incoming transactions in the following image:
Outgoing Transaction Email Flow
Use this flow when your customer sends funds to a counterparty VASP's customer. Open Outgoing Transaction on the Transactions page and select the counterparty VASP to use encrypted email. You can share the Travel Rule data after executing the transaction, or ask the counterparty to confirm the beneficiary details before you execute it.
Without Confirmation
To share Travel Rule data for an executed transaction:
-
Collect the counterparty customer's information from your customer.
-
Execute the transaction on the blockchain.
-
Complete and submit the Outgoing Transaction form, including the transaction ID. 21 Travel Rule sends the Travel Rule data to the counterparty VASP by encrypted email.
With Confirmation
To request confirmation before executing the transaction:
-
Collect the beneficiary's information from your customer. Complete and submit the Outgoing Transaction form, selecting the option to request confirmation before execution. 21 Travel Rule sends the Travel Rule data to the counterparty VASP by encrypted email and asks for confirmation. The record appears immediately in Archived, even though the transfer has not been executed.
-
The counterparty will then check if the beneficiary is indeed one of their customers. If they are, they will send you an email with the confirmation.
-
You can then proceed to execute the transaction on the blockchain.
You can see this flow with the two options in the following image:
Terminology
Familiarise yourself with the key terms used in this documentation to better understand processes and features described throughout the product.
Travel Address
The beneficiary VASP generates a Travel Address. It is a string of alphanumeric digits that, when decoded, provide information on the linked account, such as:
- To which VASP the coins are to be sent,
- Where the FATF Travel Rule information needs to go.
Whereas with a plain digital asset address the VASP needs to ask all known counterparty VASP if they own this particular address, the Travel Address immediately makes this clear. Thus saving the user and the VASP time and effort. It also does not leak competitively sensitive information to counterparties.
Wallet Address
A wallet address is, in a way, like a bank account number in that it can be shared publicly without compromising the assets inside the wallet. Wallet addresses are what blockchains use to keep track of the allocation of assets and transaction chains.
Public/Private Key
- Private Key
- For every digital asset account created, a private key is generated. The private key should never be shared since it acts similarly to a pin code in traditional banking.
- Public Key
- The private key generates a public key which finally generates a Wallet Address.
- Wallet Address
- The wallet address generated from the public key can be shared without compromising your funds.