> For the complete documentation index, see [llms.txt](https://docs.musepay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.musepay.io/reference/api-reference/kyt-api/query.md).

# Query KYT Result

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters.md).
{% endhint %}

Retrieves the processing status and structured risk result for a KYT transaction check.

<mark style="color:green;">`POST`</mark> `/v1/kyt/query`

## Request body

| Name        | Type   | Required | Description                                                                                                        |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| request\_id | String | Yes      | The same `request_id` used for the original transaction check.                                                     |
| order\_no   | String | No       | Order number returned by the transaction check. If provided, it must match the order associated with `request_id`. |

## Request example

```json
{
  "request_id": "kyt-tx-202609100001",
  "order_no": "FEE202609100001"
}
```

## Response body

| Name          | Type   | Description                                                                                                             |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| request\_id   | String | The request identifier used for the original transaction check.                                                         |
| order\_no     | String | MusePay order number for the screening request.                                                                         |
| status        | Number | Current [order status](/reference/enums/order-status.md): `22` Processing, `44` Failed, `88` Closed, or `99` Success.   |
| risk\_level   | String | Risk level returned by the screening provider. Returned when the analysis has completed and a risk record is available. |
| risk\_status  | String | Risk decision returned by the screening provider. Returned when available.                                              |
| result\_data  | Object | Structured risk metrics. Returned when available.                                                                       |
| created\_time | Number | Risk record creation time as a 13-digit Unix timestamp in milliseconds. Returned when available.                        |
| updated\_time | Number | Risk record update time as a 13-digit Unix timestamp in milliseconds. Returned when available.                          |

### `result_data`

| Name                              | Type   | Description                                                                    |
| --------------------------------- | ------ | ------------------------------------------------------------------------------ |
| source                            | String | Data source used for the screening.                                            |
| riskScore                         | Number | Risk score returned by the data source.                                        |
| riskAmount                        | Number | Amount identified as risky, denominated in USD.                                |
| orderAmtUSDT                      | Number | Transaction amount denominated in USDT, when available.                        |
| riskAmountRatio                   | Number | Proportion of the transaction amount identified as risky.                      |
| riskCategoryAmount                | Object | Risk amount by category. Keys are category names and values are amounts.       |
| riskCategoryAmountPercentage      | Object | Risk amount percentage by category.                                            |
| riskCategoryLevelAmount           | Object | Risk amount by level. Keys include values such as `HIGH`, `MEDIUM`, and `LOW`. |
| riskCategoryLevelAmountPercentage | Object | Risk amount percentage by risk level.                                          |
| riskCategoryLevel                 | Object | Risk level by category. Keys are category names and values are risk levels.    |

## Processing response

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyt-tx-202609100001",
    "order_no": "FEE202609100001",
    "status": 22
  }
}
```

## Completed response

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyt-tx-202609100001",
    "order_no": "FEE202609100001",
    "status": 99,
    "risk_level": "PASS",
    "risk_status": "APPROVED",
    "result_data": {
      "source": "elliptic",
      "riskScore": 0.0316,
      "riskAmount": 54.10,
      "orderAmtUSDT": null,
      "riskAmountRatio": 0,
      "riskCategoryAmount": {
        "Gambling": 2.05,
        "Dark Service": 2.94
      },
      "riskCategoryAmountPercentage": {},
      "riskCategoryLevelAmount": {
        "HIGH": 50.81,
        "MEDIUM": 3.29
      },
      "riskCategoryLevelAmountPercentage": {},
      "riskCategoryLevel": {
        "Gambling": "MEDIUM",
        "Dark Service": "HIGH"
      }
    },
    "created_time": 1788998400000,
    "updated_time": 1788998401000
  }
}
```

{% hint style="info" %}
Risk labels and categories are supplied by the configured screening provider. Build your policy around the returned fields instead of relying on a fixed list of labels.
{% endhint %}