Common API 3 - VASP Detail

Where should I integrate?

Before submitting the Travel Rule request, the user should have already selected a vaspCode from the dropdown list or another source (or from your blockchain tools). Then invoke this API to get the details and latest public key information.

To Use

To get detailed information about a specific VASP on the GTR network, use the following API:

GET /api/common/v3/vasp/detail?vaspCode=[vaspCode]

Sample response

{
    "verifyStatus": 100000,
    "verifyMessage": "Success",
    "data": {
        "vaspCode": "lDPwXEIe6r1jZp5TdTfyI",
        "vaspEntitySlug": "axchange-us",
        "vaspEntityName": "axchange USA",
        "allianceName": "Smile Travel Rule",
        "country": "US",
        "availability": 0,
        "supportedFeatures": ["UNHOSTED_WALLET_VERIFY"],
        "capability": {
          "couldPending": true
        },
        "supportedVerifyFields": [
            {
                "id": 110026,
                "name": "Beneficiary Legal Person Name"
            }
        ],
        "requiredPiiFieldsAsBeneficiary": [
            {
                "id": 110026,
                "name": "Beneficiary Legal Person Name",
                "direction": "BENEFICIARY"
            }
        ],
        "standardInfo": {
            "publicKeyInfo": {
                "receiverKeyInfo": {
                    "publicKey": "-----BEGIN CERTIFICATE-----\nMIICpzCC...."
                },
                "secretAlgorithm": "rsa_ecb_oaep_with_sha1_and_mgf1padding"
            },
            "supportedPiiSpecInfo": {
                "piiSpecVersion": "ivms101-2020"
            },
            "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT"
        }
    }
}

Use the response from this API to determine the following variables from the VASP Detail:

[TARGET_VASP_CODE]
[TARGET_ALGORITHM]
[TARGET_PII_SPEC_VERSION]
[TARGET_PII_SECRET_FORMAT_TYPE]
[MY_PRIVATE_KEY]
[MY_PUBLIC_KEY]
[THEIR_PUBLIC_KEY]

Please see the section below to know how to set these variables.

Prerequisites

Please setup the global variables in your code-base, the structure is recommend to be like the following:

{
  "supportedSecretAlgorithm": {
    [ALGOTIHM_TYPE_KEY]: {
      "publicKey": "",
      "privateKey": ""
    },
    ...
  },
  "supportedPiiSpecVersion: {
    "ivms101-2020": {},
    "[PII_FORMAT_NAME]": {}
  },
  "supportedPiiSecretFormatType": [
    "FULL_JSON_ENCRYPTION",
    "[OTHERS]"
  ]
}

* The public key and private key store format please refer to Secret Algorithm in GTR

You can let it be the mutable global environment for api rotation propose, and kindly reminds to consider make the Read Lock to avoid the common multi-thrading issue.

To set this global variable is means this "SERVER" has support these algorithm, PII format and PII encrypt format, once the request incoming, the server can automatically pick the supproted algorithm to process the verify. (As well as initator service, to find the same algorithm, PII foramt and PII encryption with target VASP, and initiate the request that the target VASP supported)

// please setup these information on your program
const myENV = {
  "supportedSecretAlgorithm" : {
    "ed25519_curve25519" : {
      "publicKey": "",
      "privateKey": ""
    },
    "rsa" : {
      "publicKey": "",
      "privateKey": ""
    },
  },
  "supportedPiiSpecVersion": {
    "ivms101-2020": {},
    "ivms101-2023": {}
  },
  "supportedPiiSecretFormatType": [
    "FULL_JSON_ENCRYPTION"
  ]
}

Then we move on to the next section.

For `[TARGET_VASP_CODE]`

Set the vaspCode from the response as [TARGET_VASP_CODE]:

const TARGET_VASP_CODE = response.data.vaspCode

For `[TARGET_ALGORITHM]`

Use your myENV.supportedSecretAlgorithm and match it with response.data.standardInfo.publicKeyInfo.secretAlgorithm, then: i. Select your private key as [MY_PRIVATE_KEY] ii. Select their public key as [THEIR_PUBLIC_KEY] iii. Select the algorithm as [TARGET_ALGORITHM] iv. Select your public key as [MY_PUBLIC_KEY]

const TARGET_ALGORITHM = response.data.standardInfo.publicKeyInfo.secretAlgorithm

const selectedAlgorithmFromMyENV = myENV.supportedSecretAlgorithm[TARGET_ALGORITHM]

if(selectedAlgorithmFromMyENV == null) {
    throw new Error("no support algorithm")
}

const MY_PRIVATE_KEY = selectedAlgorithmFromMyENV.privateKey
const MY_PUBLIC_KEY = selectedAlgorithmFromMyENV.publicKey

const THEIR_PUBLIC_KEY = response.data.standardInfo.publicKeyInfo.receiverKeyInfo.publicKey

For `TARGET_PII_SPEC_VERSION`

Use your myENV.supportedPiiSpecVersion to check if response.data.standardInfo.supportedPiiSpecInfo.piiSpecVersion is supported, and save it to a variable as [TARGET_PII_SPEC_VERSION] for later use:

const TARGET_PII_SPEC_VERSION = response.data.standardInfo.supportedPiiSpecInfo.piiSpecVersion
if(myENV.supportedPiiSpecVersion[TARGET_PII_SPEC_VERSION] == null) {
    throw new Error("no support pii spec version")
}

For `[TARGET_PII_SECRET_FORMAT_TYPE]`

Use your myENV.supportedPiiSecretFormatType to check if response.data.standardInfo.piiSecretFormatType is supported, and save it to a variable as [TARGET_PII_SECRET_FORMAT_TYPE] for later use:

const TARGET_PII_SECRET_FORMAT_TYPE = response.data.standardInfo.piiSecretFormatType

if(TARGET_PII_SECRET_FORMAT_TYPE not in myENV.supportedPiiSecretFormatType) {
    throw new Error("not support pii secret format type")
}

About `couldPending`

The counter-party VASP may enter a pending flow. The pending flow can occur in two stages as shown in the table below:

Each stage can be pending. If your compliance requirements only require submitting PII to the counter-party VASP before starting the transaction (without verifying PII), we suggest not proceeding with the transaction if Stage 1 is pending or failed. Refer to the table below for details on each property.

Scenario	Stage	Send Out PII	Verify PII	Can Block Transaction
Before On Chain	Address Verification Pending	No	No	No Transaction
Before On Chain	PII Verification Pending	Sent	No	Start Transaction
After On Chain	TX Verification Pending	No	No	Transaction Already Done
After On Chain	PII Verification Pending	Sent	No	Transaction Already Done

*If you don't want to transact with VASPs that have couldPending=true, you can filter them out.

Now that we've completed the important variable selection, please check the next page to initiate a one-step request.

Best practices:

Always invoke the VASP Detail API before initiating any Travel Rule transaction with a target VASP. This ensures you have the latest and most accurate information about the target VASP's encryption algorithm and public keys.
The publicKeyInfo section provides the public key and encryption algorithm that you must use to encrypt sensitive travel rule data before sending it to the target VASP.
The supportedFeatures, supportedVerifyFields, and requiredPiiFieldsAsBeneficiary fields inform you about the verification capabilities and required Personally Identifiable Information (PII) fields for the beneficiary.
The availability field indicates whether the VASP is currently available to receive travel rule data.
The standardInfo section also includes the PII specification version (piiSpecVersion) and the format type for encrypted PII data (piiSecretFormatType), which you should comply with when preparing data.

Common API 3 - VASP Detail

Where should I integrate?​

To Use​

Sample response​

Prerequisites​

For [TARGET_VASP_CODE]​

For [TARGET_ALGORITHM]​

For TARGET_PII_SPEC_VERSION​

For [TARGET_PII_SECRET_FORMAT_TYPE]​

About couldPending​

Next​