get https://api.sumsub.com/resources/kyt/txns/query/-
Overview
This method allows you to search for and retrieve specific transactions using flexible filters and query parameters.
It supports a wide range of use cases, including preventing transaction duplication — a particularly useful feature for Travel Rule compliance. Before submitting a new inbound transaction for Travel Rule processing, you can query the system to check whether the mirrored transaction already exists (e.g., if the originating VASP is also a Sumsub client using the Travel Rule solution).
Supported filters
You can add filters directly in the PATH segment of the request. When combined with query parameters, they help in pagination, sorting, and selective field searching. See the request examples for clarity.
The table below includes and explains the filters that are currently supported.
| Field | Type | Description |
|---|---|---|
data.type | String | Transaction type. Possible values:
|
data.txnDate | Date | Date and time when transactions occurred. Format (YYYY-MM-DD hh:mm:ss).Also, the following options are available: • data.txnDate__gte — filters transactions that occurred on or after the specified date and time.• data.txnDate__lte — filters transactions that occurred on or before the specified date and time.⚠️ The value should be URL-encoded (for example, 2025-10-07%2000%3A00%3A00), otherwise a signature mismatch may occur. |
data.info.paymentTxnId | String | Crypto transaction hash identifying the transaction on the blockchain. |
data.info.direction | String | Transaction type. Possible values:
|
data.info.currencyCode | String | Currency code of the transaction in ISO 4217 (for fiat) or standard cryptocurrency symbol format (for example, USD, EUR, BTC, ETH). |
data.info.cryptoParams.cryptoChain | String | Blockchain network or chain used for crypto transactions (for example, BTC, ETH, TRX, BNB). |
data.info.amount | Double | Transaction amount in the specified currencyCode.Also, the following options are available: • data.info.amount__gte — filters transactions where the amount is greater than or equal to the specified value.• data.info.amount__lte — filters transactions where the amount is less than or equal to the specified value. |
data.applicant.paymentMethod.accountId | String | Crypto wallet address or bank card number associated with the applicant. |
data.counterparty.paymentMethod.accountId | String | Crypto wallet address or bank account number of the counterparty involved in the transaction. |
Note
The method is evolving and will support additional filters over time.
Request examples
To construct a valid request, mind the following:
- Separate each filter using a semicolon (
;). - Each filter must follow the
key=valueformat.
Below are a couple of request examples to clarify how to correctly apply filters in the URL path.
// Searches transactions of the finance type, limit results to `2`.
curl -X GET \
'https://api.sumsub.com/resources/kyt/txns/query/-;data.type=finance?limit=2' \
-H 'accept: application/json'
// Checks whether a Travel Rule inbound transaction with a specific crypto hash and sender wallet already exists.
curl -X GET \
'https://api.sumsub.com/resources/kyt/txns/query/-;data.type=travelRule;data.applicant.paymentMethod.accountId=bc1q080rkmk3kj86pxvf5nkxecdrw6nrx3zzy9xl7q;data.info.direction=in;data.info.paymentTxnId=000000000000000000013f2851d71e6ea8dfcc9151654ca4cbbbfd759122589f?order=-createdAt' \
-H 'accept: application/json'
// Searches Travel Rule transactions with USDT/ETH currency where amount is from `100` to `500` which happened on `2025-10-07`.
curl -X GET \
'https://api.sumsub.com/resources/kyt/txns/query/-;data.info.direction=in;data.info.amount__gte=100;data.info.amount__lte=500;data.info.currencyCode=USDT;data.info.cryptoParams.cryptoChain=ETH;data.txnDate__gte=2025-10-07%2000%3A00%3A00;data.txnDate__lte=2025-10-07%2023%3A59%3A59;data.type=travelRule?order=-data.txnDate&limit=1' \
-H 'accept: application/json'
Response explained
The response is a JSON file that represents the list of transactions found in accordance with the filters and parameters specified in the request.
| Field | Type | Description |
|---|---|---|
items | Array of objects | Each object corresponds to a specific transaction. You can see the structured transaction information on the following page. |
totalItems | Integer | Total number of existing transactions matching the criteria specified in the request. |
Response examples
If the request is successfully sent and processed, you will get a response like the one below.
{
"list": {
"items": [
{
"id": "67fe5cbd3d428fcef242df51",
"applicantId": "67f64c4f634cfa68ed8035d6",
"externalUserId": "ipt75sgftybloqwcmi51x",
"clientId": "cool_id",
"data": {
"txnId": "b44563gwi7m7s613kfj9wk",
"txnDate": "2025-04-15 13:18:53+0000",
"applicant": {
"externalUserId": "ipt75sgftybloqwcmi51x",
"type": "individual",
"paymentMethod": {
"type": "crypto",
"accountId": ""
},
"device": {
"ipInfo": {
"ip": "87.141.63.130",
"countryCode2": "DE",
"countryCode3": "DEU",
"city": "Berlin",
"lat": 52.5583,
"lon": 13.3826,
"asn": 3320,
"asnOrg": "Deutsche Telekom AG",
"riskyAsn": true
},
"fingerprint": "cdtevzq0v1o"
}
},
"counterparty": {
"externalUserId": "q6o6p38q79o7pdr81vhkbq",
"fullName": "Jack Posek",
"type": "individual",
"paymentMethod": {
"type": "crypto"
}
},
"type": "finance",
"info": {
"paymentTxnId": "84bf83c10dfddc9d1f0ea6a1a131c638488fb161e819dae25fd8128c671d2d5a",
"type": "On-chain transfer",
"direction": "in",
"amount": 2.0,
"currencyCode": "BTC",
"currencyType": "crypto",
"amountInDefaultCurrency": 151515.15151515152,
"defaultCurrencyCode": "EUR",
"paymentDetails": "Birthday Present"
},
"sourceKey": "DemoCryptoTxn",
"props": {
"customProperty": "Custom value that can be used in rules",
"dailyOutLimit": "10000"
}
},
"score": 0,
"review": {
"reviewId": "jWmbC",
"attemptId": "mofgi",
"attemptCnt": 2,
"elapsedSincePendingMs": 1826,
"createDate": "2025-04-15 13:18:53+0000",
"reviewStatus": "onHold",
"confirmed": false
},
"createdAt": "2025-04-15 13:18:53+0000",
"scoringResult": {
"score": 0,
"dryScore": 0,
"matchedRules": [
{
"id": "67fd1b2eea9e83c6c702cbec",
"name": "cry-mon-cry-scr-fai-nuIN",
"revision": 1,
"title": "Crypto Monitoring (Crystal): Screening failed",
"score": 0,
"dryRun": false,
"action": "onHold"
}
],
"failedRules": [
{
"id": "67fd1b2eea9e83c6c702cbe9",
"name": "cry-mon-cry-new-scr-MNnN",
"revision": 1,
"title": "Crypto Monitoring (Crystal): New screening",
"dryRun": false,
"action": "score",
"error": "Applicant and counterparty wallets are empty. 'applicantPaymentMethodFingerprint' must not be null for the inbound transactions",
"stage": "pre",
"preScoringRunnerType": "cryptoTxn"
}
],
"action": "onHold",
"ruleCnt": 10,
"dryRunRuleCnt": 0
},
"txnInactive": false
},
{
"id": "67fe5d043d428fcef242df65",
"applicantId": "67fd1f02b9779f2ac49f742f",
"externalUserId": "93qy7ja4kwb1ypnwqokqmk",
"clientId": "cool_id",
"data": {
"txnId": "i6mf69id0prl2qbuzb4hzn",
"txnDate": "2025-04-15 13:20:04+0000",
"applicant": {
"externalUserId": "93qy7ja4kwb1ypnwqokqmk",
"type": "individual",
"paymentMethod": {
"type": "crypto",
"accountId": ""
},
"device": {
"ipInfo": {
"ip": "87.141.63.130",
"countryCode2": "DE",
"countryCode3": "DEU",
"city": "Berlin",
"lat": 52.5583,
"lon": 13.3826,
"asn": 3320,
"asnOrg": "Deutsche Telekom AG",
"riskyAsn": true
},
"fingerprint": "a81pno7qmt"
}
},
"counterparty": {
"externalUserId": "j57zpzq0hkny4r5qsqy3v",
"fullName": "Jack Posek",
"type": "individual",
"paymentMethod": {
"type": "crypto"
}
},
"type": "finance",
"info": {
"paymentTxnId": "84bf83c10dfddc9d1f0ea6a1a131c638488fb161e819dae25fd8128c671d2d5a",
"type": "On-chain transfer",
"direction": "in",
"amount": 2.0,
"currencyCode": "BTC",
"currencyType": "crypto",
"amountInDefaultCurrency": 151515.15151515152,
"defaultCurrencyCode": "EUR",
"paymentDetails": "Birthday Present"
},
"sourceKey": "DemoCryptoTxn",
"props": {
"customProperty": "Custom value that can be used in rules",
"dailyOutLimit": "10000"
}
},
"score": 0,
"review": {
"reviewId": "tnnlD",
"attemptId": "xfijh",
"attemptCnt": 2,
"elapsedSincePendingMs": 808,
"createDate": "2025-04-15 13:20:04+0000",
"reviewStatus": "onHold",
"confirmed": false
},
"createdAt": "2025-04-15 13:20:04+0000",
"scoringResult": {
"score": 0,
"dryScore": 0,
"matchedRules": [
{
"id": "67fd1b2eea9e83c6c702cbec",
"name": "cry-mon-cry-scr-fai-nuIN",
"revision": 1,
"title": "Crypto Monitoring (Crystal): Screening failed",
"score": 0,
"dryRun": false,
"action": "onHold"
}
],
"failedRules": [
{
"id": "67fd1b2eea9e83c6c702cbe9",
"name": "cry-mon-cry-new-scr-MNnN",
"revision": 1,
"title": "Crypto Monitoring (Crystal): New screening",
"dryRun": false,
"action": "score",
"error": "Applicant and counterparty wallets are empty. 'applicantPaymentMethodFingerprint' must not be null for the inbound transactions",
"stage": "pre",
"preScoringRunnerType": "cryptoTxn"
}
],
"action": "onHold",
"ruleCnt": 10,
"dryRunRuleCnt": 0
},
"txnInactive": false
}
],
"totalItems": 2
}
}
If the request fails (e.g., incorrect data or filters provided), you will receive an HTTP response containing an error code along with a message explaining the error. For example:
{
"code": 400,
"correlationId": "00000000000000000000000000000000",
"errorCode": 0,
"description": "Invalid parameters provided",
"type": "com.sumsub.commons.restler.exceptions.RestDslException"
}
If no transactions matching the specified criteria are found, the response will contain an empty items array.
{
"list": {
"items": [],
"totalItems": 0
}
}