> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitrace.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Custom Risk Score

> getTxHashCustomRiskScore - This endpoint retrieves the custom risk scores by given transaction.

### Risk Score Async Workflow

```mermaid theme={null}
sequenceDiagram
    HTTP Client->>+Bitrace AML API: Retrive the Risk Score(s)
    Bitrace AML API->>-HTTP Client: Response the requestId
    loop if the task status is 1000 or 1001
        HTTP Client-->>+Bitrace AML API: requestId
        Bitrace AML API-->>-HTTP Client: Corresponding Risk Score(s)
    end
```


## OpenAPI

````yaml POST /api/v1/tracker/kyt/custom-risk-scores
openapi: 3.0.3
info:
  title: Bitrace AML API
  description: >-
    Bitrace AML API provides comprehensive blockchain and crypto compliance
    tools for real-time risk detection capabilities. The API enables scrutiny of
    crypto transactions, wallet addresses, and crypto tokens with precision and
    efficiency.
  version: 1.0.0
  contact:
    name: Bitrace Support
    email: support@bitrace.io
servers:
  - url: https://api.bitrace.io
    description: Production server
security:
  - apiKeyAuth: []
tags:
  - name: KYA (Know Your Address)
    description: Address risk assessment and entity identification
  - name: KYT (Know Your Transaction)
    description: Transaction monitoring and compliance
  - name: Account API
    description: Account usage and management APIs
  - name: Address Management
    description: Address management on the blacklist and whitelist
paths:
  /api/v1/tracker/kyt/custom-risk-scores:
    post:
      tags:
        - KYT (Know Your Transaction)
      summary: Retrieve Custom Risk Score
      description: >-
        getTxHashCustomRiskScore - This endpoint retrieves the custom risk
        scores by given transaction.
      parameters:
        - name: Content-Type
          in: header
          required: false
          schema:
            type: string
            default: application/json
            enum:
              - application/json
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
            enum:
              - application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required:
                    - hash
                    - network
                  properties:
                    hash:
                      type: string
                      description: The transaction for calculating the custom risk score
                    customId:
                      type: string
                      description: >-
                        The identifier by user-defined, it will be included in
                        response if provided
                    network:
                      $ref: '#/components/schemas/NetworkCore'
                      description: >-
                        The supported chainns short name, ethereum tron btc bsc
                        See at [Supported Chains](#kyt-api-supported-chains)
                    withAddressRiskClue:
                      type: boolean
                      description: >-
                        Include the address risk clue in the response. Default
                        is false.
                      default: false
                    withTxRiskClue:
                      type: boolean
                      description: >-
                        Include the transaction risk clue in the response.
                        Default is false.
                      default: false
                - type: object
                  required:
                    - requestId
                  properties:
                    requestId:
                      type: string
                      description: The request idetifier to get the async result
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CustomRiskScoresResponse'
                    description: >-
                      The success response from create a task to get risk score
                      by given address.
                  - $ref: '#/components/schemas/CustomRiskScoresResponse2'
                    description: The success response from get risk score by given address.
              examples:
                createTask:
                  summary: create task
                  value:
                    success: true
                    code: 1
                    status: SUCCESS
                    data:
                      requestId: '60944883389642198713019658195148'
                      status: 1000
                      customId: '123456'
                    msg: SUCCESS
                retriveTask:
                  summary: retrive task
                  value:
                    success: true
                    code: 1
                    status: SUCCESS
                    data:
                      maxScore: '0'
                      dirData:
                        in: {}
                        out: {}
                      status: 1003
                      requestId: '44012551132382974553231389361325'
                      addressRisks:
                        - address: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          layer: 0
                          percentage: '1'
                          sendAmount: '738'
                          symbol: usdt
                        - address: THTYaGuz1AjhtyShiMuoNsEqr3pvZ5qXA8
                          layer: 0
                          percentage: '0'
                          sendAmount: '0'
                          symbol: usdt
                        - address: TBA6CypYJizwA9XdC7Ubgc5F1bxrQ7SqPt
                          layer: 1
                          percentage: '0.9534026483428104'
                          sendAmount: '24977.5'
                          symbol: usdt
                        - address: TZ6AYmp6wv2kWyLKptUUTTtgTMva7CjCa2
                          layer: 1
                          percentage: '0.044688828689833336'
                          sendAmount: '1170.77'
                          symbol: usdt
                      txRisks:
                        - txId: >-
                            f6498205ae6d820f3b056b646527a12be33855a44b3fcf7556618a233a1b8ce9
                          txType: contract
                          txTime: 1770968187000
                          sender: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          receiver: THTYaGuz1AjhtyShiMuoNsEqr3pvZ5qXA8
                          amount: '738'
                          coin: usdt
                          layer: 0
                          percentage: '1'
                        - txId: >-
                            7c47759ccd4dd54aedaaca822ff36f01405894363e9abd692e46a75dd969fd97
                          txType: contract
                          txTime: 1770098235000
                          sender: TBA6CypYJizwA9XdC7Ubgc5F1bxrQ7SqPt
                          receiver: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          amount: '24977.5'
                          coin: usdt
                          layer: 1
                          percentage: '0.9534026483428104'
                          senderLabel:
                            mainEntity:
                              - code: gate-io-self
                                name: Gate.io
                        - txId: >-
                            c9979965ebb464e115505252b2d91a9adb75917fd3d4d823b7c252417a42d092
                          txType: contract
                          txTime: 1770687639000
                          sender: TZ6AYmp6wv2kWyLKptUUTTtgTMva7CjCa2
                          receiver: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          amount: '81.84'
                          coin: usdt
                          layer: 1
                          percentage: '0.0031238703930248829181405696'
                        - txId: >-
                            cec089d797617536178e6749f6593309bea0e29710c4336e17bfcff1d55dc555
                          txType: contract
                          txTime: 1770769896000
                          sender: TZ6AYmp6wv2kWyLKptUUTTtgTMva7CjCa2
                          receiver: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          amount: '206.96'
                          coin: usdt
                          layer: 1
                          percentage: '0.0078997582665793580454934704'
                        - txId: >-
                            84b8ac74e888fda10ed069d49af7d5fd0a361fccbed2d32bcfd6a4b78a531b8e
                          txType: contract
                          txTime: 1770769935000
                          sender: TZ6AYmp6wv2kWyLKptUUTTtgTMva7CjCa2
                          receiver: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
                          amount: '881.97'
                          coin: usdt
                          layer: 1
                          percentage: '0.03366520003022909503636596'
                      customId: '123456'
                    msg: SUCCESS
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    NetworkCore:
      type: string
      enum:
        - ethereum
        - eth
        - tron
        - btc
        - bsc
      description: Supported blockchain networks
    CustomRiskScoresResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                requestId:
                  type: string
                  description: the corresponding request identifier
                status:
                  $ref: '#/components/schemas/AsyncTaskStatus'
                customId:
                  type: string
                  description: the identifier by user-defined, if provided in request
    CustomRiskScoresResponse2:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                requestId:
                  type: string
                  description: the corresponding request identifier
                status:
                  $ref: '#/components/schemas/AsyncTaskStatus'
                customId:
                  type: string
                  description: the identifier by user-defined, if provided in request
                maxScore:
                  type: string
                  description: the maximum possible risk score
                dirData:
                  type: object
                  properties:
                    in:
                      $ref: '#/components/schemas/DirectionData'
                    out:
                      $ref: '#/components/schemas/DirectionData'
                addressRisks:
                  type: array
                  items:
                    $ref: '#/components/schemas/AddressRisk'
                  nullable: true
                txRisks:
                  type: array
                  items:
                    $ref: '#/components/schemas/TransactionRisk'
                  nullable: true
    BaseResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Request success or not
        code:
          type: integer
          description: Response code (1 for success, other numbers for errors)
        msg:
          type: string
          description: SUCCESS or error message
    AsyncTaskStatus:
      type: integer
      description: >-
        Asynchronous task status code.<ul><li>1000: Queueing</li><li>1001: In
        Progress</li><li>1002: Failed</li><li>1003: Completed</li><li>1006:
        Expired/Timeout</li></ul>
      enum:
        - 1000
        - 1001
        - 1002
        - 1003
        - 1006
    DirectionData:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/StrategyData'
      example:
        default_37287890924998660_51146476853089016489590924639443:
          strategyNo: default_37287890924998660_51146476853089016489590924639443
          strategyName: '3 hop | Severe Risk Address | By Amount '
          details:
            - code: scam
              name: Fraud
              score: '64.91474'
          score: '64.91474'
    AddressRisk:
      type: object
      properties:
        address:
          type: string
          example: TGJQYJ7WGzfd8qsTyWwMz5pMQ4LiHkuGRd
        riskSortBos:
          type: array
          items:
            $ref: '#/components/schemas/RiskSortItem'
        layer:
          type: integer
          example: 1
        percentage:
          type: string
          example: '0.029644753301424447'
        sendAmount:
          type: string
          example: '383135'
        symbol:
          type: string
          example: usdt
    TransactionRisk:
      type: object
      properties:
        txId:
          type: string
          example: b9587f82703facdcfd25ab21b59de2c5cbef36e996db61703d16ef626d1f52ee
        txType:
          type: string
          example: contract
        txTime:
          type: integer
          format: int64
          example: 1710398796000
        sender:
          type: string
          example: TGJQYJ7WGzfd8qsTyWwMz5pMQ4LiHkuGRd
        receiver:
          type: string
          example: TFskN28dBDqv8tLKtM2GwroGx7bKDUSnBW
        amount:
          type: string
          example: '4200'
        coin:
          type: string
          example: usdt
        layer:
          type: integer
          example: 1
        percentage:
          type: string
          example: '0.0003249715219499786136444945'
        senderLabel:
          $ref: '#/components/schemas/SenderLabel'
    Error:
      type: object
      properties:
        success:
          type: boolean
          description: Request success or not
          default: false
        code:
          type: integer
        msg:
          type: string
        status:
          type: string
    StrategyData:
      type: object
      properties:
        strategyNo:
          type: string
          example: default_37287890924998660_51146476853089016489590924639443
        strategyName:
          type: string
          example: '3 hop | Severe Risk Address | By Amount '
        details:
          type: array
          items:
            $ref: '#/components/schemas/RiskDetail'
        score:
          type: string
          example: '64.91474'
    RiskSortItem:
      type: object
      properties:
        risk:
          type: string
          example: Fraud
        riskLevel:
          type: string
          example: super-high
        riskType:
          type: string
          example: scam
    SenderLabel:
      type: object
      properties:
        mainRisk:
          $ref: '#/components/schemas/RiskSortItem'
        mainEntity:
          type: array
          items:
            $ref: '#/components/schemas/EntityItem'
    RiskDetail:
      type: object
      properties:
        code:
          type: string
          example: scam
        name:
          type: string
          example: Fraud
        score:
          type: string
          example: '64.91474'
    EntityItem:
      type: object
      properties:
        code:
          type: string
          example: phishing1-5
        name:
          type: string
          example: Phishing Scam
  responses:
    BadRequest:
      description: Bad Request - Your request is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - Incorrect API key provided
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimit:
      description: Too Many Requests - Rate limit reached or quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error - We had a problem with our server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Access-Key
      description: API key authentication

````