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.