API 1: Generate Challenge

Where should I integrate

Description

This API generates the challengeMsg used in the Address Proving process.

The generated challenge is bound to your VASP and the request parameters you submit. You must later use the same values when building and signing the proofPayload.

For further details of this API, use the following endpoint:

GET $BASE_URL/ext/api/cosmos/v1/address/proof/generate

Request

Please submit the following payload to this endpoint:

curl --silent --location --request GET "$BASE_URL/ext/api/cosmos/v1/address/proof/generate" \
    --header 'Content-Type: application/json' \
    --header 'X-Authorization: [YOUR_ADDRESS_PROVING_TOKEN]' \
    --data-raw '{
        "publicKey": "[BASE64_PUBLIC_KEY]",
        "publicKeyType": "[PUBLIC_KEY_TYPE]",
        "proofAlgo": "[PROOF_ALGORITHM]",
        "walletAddress": "[WALLET_ADDRESS]",
        "userNonce": "[YOUR_RANDOM_NONCE]",
        "publicKeyFormat": "[PEM_OR_DER]"
    }'

Request Fields

Field	Required	Description
publicKey	Yes	Base64-encoded public key corresponding to the private key that will sign the proof payload
publicKeyType	Yes	Public key type. See the supported key type list in Overview
proofAlgo	Yes	Signature algorithm that will be used to sign the proof payload
walletAddress	Yes	The blockchain wallet address to be proved
userNonce	Yes	A user-generated nonce string, such as a UUID or random string
publicKeyFormat	No	Public key format. Supported values are PEM and DER. Defaults to PEM if omitted

Response

You can expect to get the following response:

{
  "verifyStatus": 100000,
  "verifyMessage": "success",
  "data": {
    "challengeMsg": "a1b2c3d4e5f67890"
  }
}

Response Fields

Field	Description
data.challengeMsg	Challenge string generated by GTR. This value must be placed into your proofPayload in the next step

Notes

• The challengeMsg is generated from your authenticated VASP context and request parameters.
• The returned challenge is a 16-character lowercase hexadecimal string.
• You should keep the same walletAddress, proofAlgo, publicKeyType, userNonce, and publicKeyFormat when you proceed to the submit step.
• If publicKeyFormat is omitted, GTR treats it as PEM.

Error Handling

verifyStatus	HTTP Status	verifyMessage	Cause	Action
100001	200	unauthorized	Missing or invalid X-Authorization header	Check your token and request header
100004	400	Validation error text	Required request field is missing or invalid	Check all required request fields
100001	200	missing request body, have to check all the required parameters?	Request body is missing	Send a valid JSON body
100001	200	wrong json request body format, please check if theres any additional , in the tail of key:value, the last key-value should not have , concat at the tail	JSON syntax is invalid	Fix the JSON formatting and resend
100006	500	Internal Server Error, Please contact to GTR official service, Support Id: [SUPPORT_ID]	Unexpected internal server error	Retry later or contact GTR support with the support ID