Skip to main content
Search

API: Query Verify Status

This API is a pull alternative to the Wallet Verify Callback. Use it when your service did not receive the callback in time, or when you want to actively re-check the status before proceeding with a transfer.

When should I call this API​

The Wallet Verify Callback (callbackType:18) is the primary way to learn the verification result. This Query API is provided for the following situations:

  • The callback from GTR was delayed, lost, or your callback endpoint was temporarily unavailable.
  • Your service wants to actively check progress.

The response payload is the same shape as callbackData in the Wallet Verify Callback, so your callback handler logic can be reused.

Wallet Verify - Query Verify Status​

Please call the following endpoint with requestId as a query parameter:

curl --silent --location --request GET "/api/verify/wallet/verify/query?requestId=[YOUR REQUEST ID]" \
    --cert-type P12 --cert ./certificate.p12:'[MY_PASSWORD_OF_CERT]' \
    --header "Authorization: Bearer [YOUR LOGIN TOKEN]" \
    --header "Connection: keep-alive"

The data object contains:

  • requestId
  • notifyResult
  • walletName
  • metadata
  • addressScreeningResult

addressScreeningResult is only returned after wallet verification succeeds and address screening result is available. For pending, fail, and expired states it is null.

Case 1: Pending​

While the wallet owner has not finished signing, the response will look like below. addressScreeningResult is always null in this state.

{
  "verifyStatus": 100002,
  "verifyMessage": "Pending for verify",
  "data": {
    "requestId": "[REQUEST_ID]",
    "notifyResult": {
      "verifyStatus": 100002,
      "verifyMessage": "Pending for verify",
      "verifyStage": "WALLET_OWNER_VERIFICATION"
    },
    "walletName": "UNKNOWN WALLET APP",
    "metadata": "{\"user_id\":\"123456\"}",
    "addressScreeningResult": null
  }
}

Case 2: Success​

If the wallet owner successfully completed message signing, you can expect the response below with verifyStatus:100000. If address screening has been persisted by GTR, it will be included as addressScreeningResult.

Once you observe this status, you can continue the transfer.

{
  "verifyStatus": 100000,
  "verifyMessage": "wallet signature verified",
  "data": {
    "requestId": "[REQUEST_ID]",
    "notifyResult": {
      "verifyStatus": 100000,
      "verifyMessage": "wallet signature verified",
      "verifyStage": "WALLET_OWNER_VERIFICATION"
    },
    "walletName": "UNKNOWN WALLET APP",
    "metadata": "{\"user_id\":\"123456\"}",
    "addressScreeningResult": {
      "screeningStatus": "COMPLETED",
      "message": "screening result present",
      "vaspEntityName": "Axchange UK",
      "vaspEntityId": "axchange-uk",
      "vaspCode": "axchangeukadjk",
      "riskTags": [
        "Exchange & Trading Platforms",
        "Centralized Exchange",
        "Unknown Wallet"
      ],
      "riskScore": 4.0
    }
  }
}

Case 3: Fail​

If the wallet owner never scanned the QR code with the right wallet or failed to complete message signing, you can expect the response below with verifyStatus:100001. addressScreeningResult will be null.

Once you observe this status, you should stop the process or ask your user to retry with a new requestId.

{
  "verifyStatus": 100001,
  "verifyMessage": "Verification Fail",
  "data": {
    "requestId": "[REQUEST-ID]",
    "notifyResult": {
      "verifyMessage": "Verify Failed",
      "verifyStage": "WALLET_OWNER_VERIFICATION",
      "verifyStatus": 100001
    },
    "addressScreeningResult": null
  }
}

Case 4: Expired​

If the wallet owner never performed any operations and the request was auto-expired by GTR, you can expect the response below with verifyStatus:100031. addressScreeningResult will be null.

Once you observe this status, you should cancel the process from your end.

{
  "verifyStatus": 100031,
  "verifyMessage": "Verification Timeout",
  "data": {
    "requestId": "[REQUEST-ID]",
    "notifyResult": {
      "verifyMessage": "Verification Timeout",
      "verifyStage": "WALLET_OWNER_VERIFICATION",
      "verifyStatus": 100031
    },
    "addressScreeningResult": null
  }
}

Error responses​

Request id not found​

If the requestId you provided does not exist in GTR, you will receive:

{
  "verifyStatus": 100001,
  "verifyMessage": "request id not found",
  "data": null
}

Request id does not belong to your VASP​

If the requestId exists but was not initiated by your VASP, you will receive verifyStatus:100023 (Client Invalid Parameters):

{
  "verifyStatus": 100023,
  "verifyMessage": "this verify request is not belongs to you",
  "data": null
}

Request id is not a Wallet Verify request​

If the requestId exists but corresponds to a different Travel Rule type (e.g. a standard Travel Rule request), you will receive verifyStatus:100023:

{
  "verifyStatus": 100023,
  "verifyMessage": "request id is not a wallet verify request",
  "data": null
}

Missing requestId​

If the requestId query parameter is missing or blank, you will receive verifyStatus:100004 (Client Bad Parameters):

{
  "verifyStatus": 200016,
  "verifyMessage": "requestId is required",
  "data": null
}

Polling guidance​

  • This API is a safety net, not a replacement for the callback. Continue to handle the Wallet Verify Callback as your primary signal.
  • A reasonable polling interval is once every 5 to 10 seconds while verifyStatus is 100002. Avoid tight loops.
  • Stop polling as soon as you observe a terminal state (100000, 100001, 100031), or when verifyExpiredAt from the create-verify response has passed.