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 provide 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 verifyStatus field on the outer response reflects the current state in GTR for this requestId:

• 100002 - Pending: the wallet owner has not finished signing yet.
• 100000 - Success: the wallet owner has completed signing.
• 100001 - Fail: the wallet owner failed to sign or signed with the wrong wallet.
• 100031 - Expired: the request was auto-expired without any user action.

You may keep polling while verifyStatus is 100002. Once you observe a terminal state (100000, 100001, 100031), stop polling.

About address screening result

For Query Verify Status, screeningResult is only included when verifyStatus is 100000 (Success). For any other state, including pending, fail, and expired, screeningResult will be null.

This is consistent with the Wallet Verify Callback behaviour - screening is only meaningful after the wallet owner has signed successfully.

Note: even on 100000 Success, screeningResult may still be null for a brief moment because GTR persists the screening result asynchronously. If your service strictly needs the screening result, you can poll one more time after observing the success state.

Case 1: Pending

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

{
  "verifyStatus": 100002,
  "verifyMessage": "Pending: Verification incomplete / waiting for verification",
  "data": {
    "requestId": "[REQUEST-ID]",
    "notifyResult": {
      "verifyMessage": "Pending for verify",
      "verifyStage": "WALLET_OWNER_VERIFICATION",
      "verifyStatus": 100002
    },
    "screeningResult": 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 screeningResult.

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

{
  "verifyStatus": 100000,
  "verifyMessage": "Verification Success",
  "data": {
    "requestId": "[REQUEST-ID]",
    "notifyResult": {
      "verifyMessage": "Verify Success",
      "verifyStage": "WALLET_OWNER_VERIFICATION",
      "verifyStatus": 100000
    },
    "screeningResult": {
      "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. screeningResult 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
    },
    "screeningResult": 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. screeningResult 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
    },
    "screeningResult": 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.