Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

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 the Decryption Key field 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 autod service uses the intended bulletin board URL. Check that you entered the LEI rather than the vaspId.
  • 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 Key matches 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.