Nested VASPs

What is nested VASPs

Multi-entity support or nested VASPs is crucial for Travel Rule compliance, as many Originating and Beneficiary VASPs have entities in multiple locations. When end customers want to send funds to these, it might be difficult for them to identify the exact subsidiary that should receive the transaction.

For example, when Alice sends a transaction to Bob's BitNice account, she likely doesn't know if his account is with BitNice Singapore or BitNice Malaysia.

How does it work

Notabene supports subsidiary VASP profiles that can be connected to a parent VASP:

  • Each subsidiary will have its own profile
  • All subsidiaries of a VASP are connected to a parent VASP
  • Originator VASP and customer only see (and only need to identify) the parent VASP
  • The parent VASP forwards Travel Rule data transfers to the right subsidiaries

With this nesting enabled, the Originator Customer (Alice) will only have to identify the Parent Beneficiary VASP (BitNice), where the Travel Rule data transfer will be directed. BitNice will then route the transaction to the correct subsidiary.

How to nest

Currently, it is not possible to do this yourself and needs to be done by Notabene. Please send an email to [email protected] or contact your Notabene solution engineer.


  • As described here, you can use only the gatewayVASP credentials to control all of the VASPs;
  • the customerToken has to be specific for each subsidiary VASP

Withdrawals - outgoing TR transfers


Do not send travel rule messages from the parent VASP

The parent VASP is only there to receive messages.

When validating or creating withdrawals or outgoing TR transfers in a multi-entity setup, the originatorVASPdid will have to be one of the nested entities, as it will be relevant to consider the originator VASP jurisdictional requirements.

Deposits - Incoming Travel Rule messages

If your VASPs are nested, the first time you receive a TR transfer for a given address, it will most likely directly hit your gatewayVASP. To process it, you will have to redirect it to the correct subsidiary VASP.

There are three ways to redirect a travel rule message from a gateway to a subsidiary:

  1. Populate the address books of the subsidiaries and Notabene will take care of redirecting to the correct one;
  2. Set up an address webhook on each of the subsidiary VASPs;
  3. Set up a notification webhook on the gateway VASP, lookup the address internally and call txRedirect.àà##

Notabene handles the redirect

In this scenario, as a beneficiaryVASP, you will register all the addresses that you currently have and the one that you will create in the correct subsidiary VASP address book using bulk csv upload and the register address API.

Set up the address webhook on each subsidiary

Here you will set up a address webhook for each subsidiary VASP:

When the gateway receives an incoming travel rule message, Notabene will call each address webhook that has been configured for the subsidiaries. Each subsidiary VASP can then internally lookup whether or not the destination address belongs to them and respond with the boolean property "owns" in the json body. Ex. body: {"owns":true}. If one of the subsidiaries returns owns:true, the travel rule message will automatically get redirected there.

Set up notification webhook on the gateway

Here you will set up a notification webhook for the gateway VASP:

When your gatewayVASP receives an incoming travel rule message, Notabene will push the details to your notification webhook. Your system then needs to look-up the destination address in a central database to see if it is one that belongs to you and which subsidiary it belongs to.

If it is yours, your system should first call txRedirect with the VASP DID of that subsidiary, then call txConfirm to register that destination address to the subsidiary. Doing this will automatically redirect it there the next time someone sends a message with that destination address.

For example:

BitNice has received a travel rule message from VASP A, which looks like this:

  "id": "f3473feb-a283-4525-b414-ece7774230ce",
  "status": "SENT",
  "transactionType": "TRAVELRULE",
  "transactionAsset": "BTC",
  "transactionAmount": "336209107",
  "chargedQuantity": 109.62,
  "amountInLocalCurrency": null,
  "originatorDid": "did:ethr:0xbacbd49275e6c5e818bf735a112e4ed7a6c9882e",
  "beneficiaryDid": "did:ethr:0x5385b966b7cbc19cfce40703cb20c895b1c32827",
  "isTest": null,
  "originatorVASPdid": "did:ethr:0x049fc13a4f1e79d4d03f082ca96758179a91da29",
  "beneficiaryVASPdid": "did:ethr:0xd4bd902ec78578f33a20ff601504d2ab324cfab9",
  "transactionBlockchainInfo": {
    "txHash": "",
    "origin": "3qR7cZYmhJvKc75P6UEqPVseQF8z",
    "destination": "1CX6qbQd9yucgckJyCY9Mv86R"
  "ivms101": {
    "originator": {
      "originatorPersons": [

They lookup the destination address, 1CX6qbQd9yucgckJyCY9Mv86R, and see that this belongs to BitNice UK ,did:ethr:0x54768b1da0c6f1bd0fda15dc6c55cbba40f85744, so they redirect it to there using txRedirect:

Disabling automatic redirection and automatic confirmation

By default, Notabene will redirect and confirm TR transfers if a destination address is included in the internal address book of a subsidiary VASP. It is possible to disable these automations so that TR transfers will be redirected only if txRedirect is and confirmed only if txConfirm is explicitly called. It is also possible to disable one of the two options only.

It is sufficient to set it by calling Update a VASP's settings and posting "autoconfirm": falseand/or "autoredirect": false ensuring that the settings are set on the gatewayVASP.

curl --location --request PUT '{{gatewayVASPdid}}/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_Token}}' \
--data '{
    "autoredirect": false,
    "autoconfirm": false