Submit One Step Travel Rule

Version: 3.0.0

Method

POST

Url

https://platform.globaltravelrule.com/api/verify/v2/one_step

This API endpoint is the main endpoint for Travel Rule Request Initiator to start a Travel Rule. This endpoint covers two main verification phases: 1. address or txId verification, 2. PII verification.

Authentication

No authentication

Path Parameters

No path parameters

Query Parameters

No query parameters

Request Body (Required)

Schema

address

RequiredString

address is beneficiary address (in all scenario)

Min Length0

Max Length320

Example

E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp

amount

RequiredString

amount is corresponding to the ticker, the amount of the coin in this transfer, this amount should be string (Reference: Longest AVAX should be decimal(28,18) / numeric(28,18))

Min Length0

Max Length64

Example

8e-18

encryptedPayload

OptionalString

encryptedPayload here is only for support curve25519 format encrypted PII, if you need to use other algorithm, please also fill the payload here, and refer to PiiSecuredInfo structure

Min Length0

Max Length60000

Example

s7GpRAkqDz9whfwaOaBy6PhH5ITStUxN7Uz0mQLXpgZMQJ1HmtpUSnk6hEjGx1zuq0yCyWPVr66BmwgsOy/V2PZt2qR+C5EYArRjIbfYwdfDw051kxlv9dRiMTbZphNViL2YafNJPqKradDA/RmzScQ7g9LsTOmpHZCepLG66eIT+9LatJb6CF...etc

expectVerifyFields

OptionalArray<String>

The PII Info that you expect to be verify, GTR will matches the results if the targetVasp has verified. The verify type code has distinguish by different direction like Originator and Beneficiary. The PII Type code can refer to:

Example

["110026","110025","110045","100031"]

fiatName

RequiredString

fiatName is the currency unit of equality amount of coin, should convert to stable coin (USDT, EURC, USDC...etc) / real world fiat currency like (USD, EUR, NZD, GBP, HKD, CNY, JPY, TRY...etc), please prior to choose fiat currency.

Min Length0

Max Length32

Example

USD

fiatPrice

RequiredString

fiatPrice is the equality amount of coin, the price ratio is always changing, just make sure you convert when the time you initiate the request.

Min Length0

Max Length64

Example

84.12

initiatorPublicKey

RequiredString

initiatorPublicKey here is your public key

Min Length0

Max Length2048

Example

0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=

network

RequiredString

Network name in short symbol, the reference can check the table.

Min Length0

Max Length64

Example

XRP

originatorAddress

OptionalString

address is originator address (in all scenario), pre-transaction approval: use originator person wallet, post-transaction approval: use hot wallet address that record on blockchain

Min Length0

Max Length320

Example

E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp

originatorAddressTag

OptionalString

address is originator address (in all scenario), pre-transaction approval: use originator person wallet, post-transaction approval: use hot wallet address that record on blockchain

Min Length0

Max Length64

Example

E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp

[+]piiSecuredInfo

RequiredObject

PiiSecuredInfo

Example

(Refer to inner structure)

requestId

RequiredString

requestId is the unique id for all transaction, the same travelrule-request invoke process flow should be using same requestId, the recommend format is: "[YOUR_VASP_NAME]-[UUIDv4]"

Min Length0

Max Length64

Pattern

[\w\d_=-]+

Example

testexchange-189e9948-64c7-4a6c-bb4f-859c173321c5

sourceVaspCode

OptionalString

*Required if you're TRSP type user, that you have to bring your member vasp's GTR vaspCode here, that we can recognize who made this travel rule.

Min Length0

Max Length64

Example

MAkGAda4ac

tag

OptionalString

some of network like XRP required to input address tag (memo)

Min Length0

Max Length64

Example

some of network like XRP required to input address tag (memo)

targetVaspCode

RequiredString

targetVaspCode here is the counter-party VASP that you want to send the travel rule request (*Not the assets transfer direction), vaspCode is GTR system's format

Min Length0

Max Length64

Example

MAkGAda4ac

targetVaspPublicKey

RequiredString

targetVaspPublicKey is the counter-party VASP's public key in Curve25519, you can get this public key by vaspDetail api or vaspList api. *If you're using newest version, please mind that this field is for curve25519 format-key, using PiiSecuredInfo structure, but also fill the value same as piiSecuredInfo here

Min Length0

Max Length2048

Example

0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=

ticker

RequiredString

ticker (coin) is the symbol of coin money, could refer to CMC

Min Length0

Max Length64

Example

USDT

txId

OptionalString

*if the travel rule is after on chain, then the txId is required. the tx id format type can check the table.

Min Length0

Max Length256

Example

d1029841dacb031098288b257b628a967eb963bbaccf954506ad0694219497a4

verifyDirection

RequiredInteger (int32)

direction is travelrule direction. verifyDirection: 1 (After On Chain), verifyDirection: 2 (Before On Chain), Perspective if from your system, 1 means you're Beneficiary that receive funds, and you send the Originator KYC/B (IVMS) to check, 2 means you're Originator that you want to send the funds, and you send the Beneficiary KYC/B (IVMS) to check.

Example

1: (After on chain), 2: (Before On Chain)

Example

{
  "requestId": "testexchange-189e9948-64c7-4a6c-bb4f-859c173321c5",
  "verifyDirection": "1: (After on chain), 2: (Before On Chain)",
  "targetVaspCode": "MAkGAda4ac",
  "ticker": "USDT",
  "originatorAddress": "E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp",
  "originatorAddressTag": "E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp",
  "address": "E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp",
  "tag": "some of network like XRP required to input address tag (memo)",
  "network": "XRP",
  "txId": "d1029841dacb031098288b257b628a967eb963bbaccf954506ad0694219497a4",
  "encryptedPayload": "s7GpRAkqDz9whfwaOaBy6PhH5ITStUxN7Uz0mQLXpgZMQJ1HmtpUSnk6hEjGx1zuq0yCyWPVr66BmwgsOy/V2PZt2qR+C5EYArRjIbfYwdfDw051kxlv9dRiMTbZphNViL2YafNJPqKradDA/RmzScQ7g9LsTOmpHZCepLG66eIT+9LatJb6CF...etc",
  "expectVerifyFields": [
    "110026",
    "110025",
    "110045",
    "100031"
  ],
  "piiSecuredInfo": "(Refer to inner structure)",
  "amount": 8e-18,
  "fiatPrice": 84.12,
  "fiatName": "USD",
  "sourceVaspCode": "MAkGAda4ac"
}

Responses

Status HTTP Status: 200, VerifyStatus: 100000

Success case

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 100000,
  "verifyMessage": "Verify Success"
}

Status HTTP Status: 200, VerifyStatus: 200001

Address not found case

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 200001,
  "verifyMessage": "Address Not Found."
}

Status HTTP Status: 200, VerifyStatus: 200007

TX ID Not found case

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 200007,
  "verifyMessage": "TX ID Not Found"
}

Status HTTP Status: 200, VerifyStatus: 200003

default response

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 200003,
  "verifyMessage": "PII Verification Failed"
}

This /one-step API can cover two situations:

1. Pre-transaction Travel Rule: if your VASP as Originator VASP, initiating a Travel Rule request before sending the crypto assets to the blockchain
2. Post-transaction Travel Rule: if your VASP as Beneficiary VASP, initiating a Travel RUle request after you received crypto assets from the blockchain

This /one-step API will run all verification flows in a synchronous way:

1. Address Verification(in pre-transaction situation)or TXID Verification(in post-transaction situation)
2. PII Verification.

If first check failed, Travel Rule process will be terminated right away and your counterparty VASP will not receive your encrypted PII payload.

Please note that, this API will always return HTTP Code as 200 and this API shall time out after 30 seconds.

Once you called /one_step API in a pre-transaction situation, you are required to invoke /notify_tx_id after you successfully execute this asset transfer on the blockchain. This will let your counterparty VASP receive a notification containing the correlation of txId and requestId.

Request Example 1: Travel Rule Initiator as Originator VASP(Pre-transaction situation)

{
  "requestId": "[prefix-uuidv4: KITCHEN_STORE-16e5025a-8e55-4052-8a68-c91620cb28fb]",
  "ticker": "[TICKER NAME: ETH]",
  "amount": "[Amount in crypto: 542.0000000000452]",
  "address": "[Beneficiary Address: 0x339facb1153e01d1e0d21e378da56d851da25ade]",
  "tag": "[TAG-(XRP/XLM/TON), leave blank if not applicable: 164392432]",
  "network": "[NETWORK NAME: ETH]",
  "txId": null,
  "verifyDirection": 2,
  "targetVaspCode": "[Target VASP Code: gdummy]",
  "encryptedPayload": "[Curve25519 encrypted string]",
  "initiatorPublicKey": "[Your public key - Curve25519 Format]",
  "targetVaspPublicKey": "[Target VASP public key - Curve25519 Format]",
  "fiatName": "[FIAT NAME: USD]",
  "fiatPrice": "[FIAT RATIO PRICE: 4593.31]",
  "expectVerifyFields": ["110026", "111001"],
  "piiSecuredInfo": {
    "initiatorKeyInfo": {
      "publicKey": "xxxxxxx"
    },
    "receiverKeyInfo": {
      "publicKey": "xxxxxxx"
    },
    "secretAlgorithm": "curv225519",
    "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT",
    "piiSpecVersion": "ivms101-2020",
    "securedPayload": "[Encrypted PII]",
    "encryptionParams": {
      "ecies": {
        "ephemeralPublicKey": "xxxxxxxxx"
      }
    }
  }
}

Request Example 2: Travel Rule Initiator as Beneficiary VASP (Post-transaction situation)

{
  "requestId": "[prefix-uuidv4: KITCHEN_STORE-16e5025a-8e55-4052-8a68-c91620cb28fb]",
  "ticker": "[TICKER NAME: ETH]",
  "amount": "[Amount in crypto: 542.0000000000452]",
  "address": "[*In Post-transaction travel rule, still use Beneficiary Address: 0x339facb1153e01d1e0d21e378da56d851da25ade]",
  "tag": "[TAG-(XRP/XLM/TON), leave blank if not applicable: 164392432]",
  "network": "[NETWORK NAME: ETH]",
  "txId": "F4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
  "verifyDirection": 1,
  "targetVaspCode": "[Target VASP Code: gdummy]",
  "encryptedPayload": "[Curve25519 encrypted string]",
  "initiatorPublicKey": "[Your public key - Curve25519 Format]",
  "targetVaspPublicKey": "[Target VASP public key - Curve25519 Format]",
  "fiatName": "[FIAT NAME: USD]",
  "fiatPrice": "[FIAT RATIO PRICE: 4593.31]",
  "expectVerifyFields": ["110026", "111001"],
  "piiSecuredInfo": {
    "initiatorKeyInfo": {
      "publicKey": "xxxxxxx"
    },
    "receiverKeyInfo": {
      "publicKey": "xxxxxxx"
    },
    "secretAlgorithm": "curv225519",
    "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT",
    "piiSpecVersion": "ivms101-2020",
    "securedPayload": "[Encrypted PII]",
    "encryptionParams": {
      "ecies": {
        "ephemeralPublicKey": "xxxxxxxxx"
      }
    }
  }
}

Response Full Structure

{
  "data": {
    "encryptedPayload": "RrInXkezrLw...5ogc1koFps=",
    "initiatorPublicKey": "[YOUR PUBLIC KEY]",
    "targetVaspPublicKey": "[TARGET VASP PUBLIC KEY]",
    "targetVaspCode": "[TARGET VASP CODE]",
    "originatorVasp": "",
    "beneficiaryVasp": "",
    "secretType": 1,
    "requestId": "[REQUEST ID]",
    "travelruleId": "[TRAVEL RULE ID]",
    "verifyFields": [
      {
        "message": "matched",
        "status": 1,
        "type": "111006" // Beneficiary Natural Person Name
      },
      {
        "message": "we don't support sorry",
        "status": 2,
        "type": "MY_OWN_NAME" // custom name or type name
      },
      {
        "message": "date of birth matched",
        "status": 1,
        "type": "111024" // Beneficiary Natural Person Date of birth
      }
    ]
  },
  "success": true,
  "verifyMessage": "Verification Success",
  "verifyStatus": 100000
}

Response Example 1: Success

HTTP Status: 200, VerifyStatus: 100000

{
  "verifyStatus": 100000, 
  "verifyMessage": "Verify Success"
}

Response Example 2: Address Not Found

HTTP Status: 200, VerifyStatus: 200001

{
  "verifyStatus": 200001,
  "verifyMessage": "Address Not Found."
}

Response Example 3: TXID Not Found

HTTP Status: 200, VerifyStatus: 200007

{
  "verifyStatus": 200007,
  "verifyMessage": "TX ID Not Found"
}

Response Example 4: PII Verification Failed

HTTP Status: 200, VerifyStatus: 200003

{
  "verifyStatus": 200003,
  "verifyMessage": "PII Verification Failed"
}

Just to highlight, when you receive verifyStatus as 200003, it means PII payload sent by your VASP failed to be verified by your counterparty.

There could be various failure reason:

• Specific PII field you sent is mismatched with their KYC data,
• Certain PII Fields are not included in your PII Payload,
• ...

You can look into the verifyFields array in the response for the detail reason.