13-Asset-Transfer-Data-Request

This API works in the reverse way of 'Asset Transfer Authorization'. So when an anonymous transaction is transferred, it will request for the Travel Rule data to make it identified.

❗️Due to the complexity of the ivms101 standard, we recommend using CodeVASP-Cipher. If, for internal security reasons, you are unable to use it, please carefully read the ivms101 standard section in the developer guide.

❗️This API works in a synchronous manner, providing an immediate response upon request.

❗️For GTR-affiliated member companies, the currency and network parameters are required. For coin-specific network details, please refer to [12-Interoperability page with other protocols].

When requesting to, GTR member companies, you must include the Originator object in IVMS101 format. The provided Originator information will be verified by the GTR member VASP. Differences in behavior between CodeVASP and GTR member VASPs:

• CodeVASP: Requests missing Travel Rule data from the Originating VASP.
• GTR: Validates whether the Originator matches the Beneficiary by verifying the Beneficiary's KYC information provided within the Originator object.

Endpoint

PUT /v1/code/verification/tx/{vaspEntityId}

Request Parameters

Headers

Path Parameters

Body Parameters

Info: For the originator's personal information, as of August 7 2024, individual's name and date of birth are to be sent for the individual, and only information on the legal person and representative name is to be sent for the legal person.

transferId: Use the 'requestId' from 'Search VASP by TXID'.

txid: It is a unique value used to identify a specific transaction executed on the blockchain for virtual asset transfer. It is unique and generated by the blockchain API.

beneficiaryAddress: Beneficiary's wallet address. Attach secondary addresses like tag or memo after a ':' delimiter.

currency: Symbol of the transferred virtual asset, which is case-insensitive. This parameter is mandatory for GTR-affiliated member companies.

network: Specifies the network to distinguish coins existing across multiple networks. This parameter is mandatory for GTR-affiliated member companies.

payload: An object for containing IVMS101 messages. Please refer to the [04-IVMS101] page.

Response

Fields

result: This is the result of asset transfer data request.

-normal: The request was processed correctly, the transaction was received.

-error: The request was not processed. Please check 'reasonType'.

reasonType: If the result value is error, a value which identifies the detailed reason.

-NOT_FOUND_TXID: When the cannot be found

-LACK_OF_INFORMATION: When a required field of IVMS101 was missing.

-UNKNOWN: Others.

reasonMsg: This describes a detailed message explaining the reasonType.

transferId: 'transferId' received from 'Asset Transfer Data Request' API.

currency: This is a symbol of the virtual asset you want to transfer. (This is case insensitive.)

amount: This is the total volume of virtual assets you want to transfer.

historicalCost: This is an acquisition cost of the virtual asset to be transferred (The requirements of National Tax Service. However, it is not used yet.)

tradePrice: This is the amount of the virtual asset transfer converted to a type of legal tender. If there is no its own price information, convert this using the price API of other VASP. Please refer to 'tradePrice' calculation below.

tradeCurrency: This is a legal tender code, which follows the ISO 4217 standard used when converting to a legal tender. The following currencies can be entered: 'KRW', 'USD', 'EUR', 'JPY', 'CNY', 'GBP', 'CAD', 'AUD', 'HKD', 'SGD'. If you need to use any other currency code, please inform the CodeVASP team! For more details, please refer to the FAQ page.

isExceedingThreshold: Indicates whether the tradePrice exceeds the Travel Rule threshold specified by law.

payload: This is an object to contain an IVMS101 message. Please refer to [04-IVMS101].

📘 'tradePrice' calculation

In the "tradePrice" field, you should enter the value calculated by multiplying the quantity of the asset by its price in fiat currency. In the "tradeCurrency" field, you should specify the type of fiat currency. For example, if you are transferring 2 BTC and the price at that moment is 42,708 USD, then the total price is 42,708 USD * 2 = 85,416 USD. In this case, you value should be as follows:

"tradePrice": "85416", "tradeCurrency": "USD",

Examples

Request

curl --request PUT \
     --url https://trapi-dev.codevasp.com/v1/code/verification/tx/vaspEntityId \
     --header 'X-Code-Req-Datetime: 2024-03-04T15:10Z' \
     --header 'X-Code-Req-Nonce: 989166249' \
     --header 'X-Code-Req-PubKey: YourPubkey' \
     --header 'X-Code-Req-Remote-PubKey: beneficiaryPubkey' \
     --header 'X-Code-Req-Signature: Signature' \
     --header 'X-Request-Origin: code:yourVaspEntityId' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "transferId": "681f27dd-43e4-4ea3-9bcc-607426d6349f",
  "txid": "311BFF73D9B7969CCF1042186180159C724FAB59013A7A034A93E5FB9D6BAFE6",
  "beneficiaryAddress": "address:tag",
  "payload": "encrypted ivms101 payload"
}'

Response

{
  "transferId": "b09c8d00-8da9-11ec-b909-0242ac120002",
  "result": "error",
  "reasonType": "UNKNOWN_TRANSFER_ID"
}