Transaction Security - HashDit API Documentation

POST

hashdit

transaction-security

curl --request POST \
  --url https://service.hashdit.io/v2/hashdit/transaction-security \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "dapp_url": "https://pancakeswap.finance/swap",
  "evm_transactions": [
    {
      "chain_id": 56,
      "from": "0x8894E0a0c962CB723c1976a4421c95949bE2D4E3",
      "to": "0x55d398326f99059ff775485246999027b3197955",
      "value": "0",
      "data": "0x095ea7b300000000000000000000000010ed43c718714eb63d5aa57b78b54704e256024effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
    }
  ]
}
'

{
  "code": "0",
  "status": "ok",
  "data": {
    "exec_summary": {
      "result_code": "000000000",
      "result_description": "Successful simulation.",
      "error_data": null
    },
    "simulation_error": null,
    "results": [
      {
        "revert": false,
        "platform": "bsc",
        "tx_gas_used": 46284,
        "approve_changes": [
          {
            "token_address": "0x55d398326f99059ff775485246999027b3197955",
            "tokenName": "Binance-Peg BSC-USD",
            "symbol": "BSC-USD",
            "approve_list": [
              {
                "approver_address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
                "spender_address": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
                "begin_value": "0",
                "end_value": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
              }
            ]
          }
        ],
        "balance_changes": []
      }
    ],
    "security": {
      "overall_score": 3,
      "overall_risk_level": "Medium Risk",
      "recommended_action": "WARN",
      "risk_details": [
        {
          "name": "tx_unlimited_approval",
          "score": 3,
          "risk_level": "Medium Risk",
          "description": "Grants 0x10ed43c718714eb63d5aa57b78b54704e256024e an unlimited BSC-USD allowance, spendable at any time until revoked"
        }
      ]
    }
  }
}

Networks: all supported EVM chains, plus Tron. See Supported Chains.

Using The Recommendation

recommended_action is the simplest field to integrate into a signing flow:

Value	Meaning	Suggested UI behavior
`ALLOW`	No risk worth interrupting the user for was detected.	Continue to the normal confirmation screen.
`WARN`	The user should understand one or more risks before signing.	Show every `risk_details[].description` and require confirmation.
`BLOCK`	Strong evidence indicates that the transaction may harm the user.	Advise against signing and stop the default flow.

The score gives finer-grained severity for sorting, analytics or UI colour:

Score	Risk level	Recommendation
`0`	`No Obvious Risk`	`ALLOW`
`1`	`Caution`	`ALLOW`
`2`	`Low Risk`	`WARN`
`3`	`Medium Risk`	`WARN`
`4`	`High Risk`	`BLOCK`
`5`	`Significant Risk`	`BLOCK`

A response can contain multiple findings. Show all of them: each describes a different part of the risk — the dApp domain, the spender, the destination, the asset exposure.

Use name for application logic and description for user-facing copy. Key off name, not description: identifiers are stable, while wording improves over time.

Security Coverage

HashDit combines request context, threat intelligence, contract metadata and simulation evidence. Findings can cover:

Malicious or brand-impersonating dApp URLs
Risky destination addresses and addresses reached by internal calls
Unlimited approvals, approvals to wallet addresses, and NFT approval-for-all
Known-malicious or suspicious function calls
Unverified destinations, recipients and contract functions
Tron account-permission changes

Not every category appears in every response. risk_details contains only the findings triggered for the submitted transaction. Reverts and the actual balance, approval and ownership effects are reported separately, in the simulation result.

Security Analysis Without Simulation

Set simulate to false when you only need the verdict:

{
  "dapp_url": "https://app.example.com/swap",
  "evm_transactions": [
    {
      "chain_id": 56,
      "from": "0x8894E0a0c962CB723c1976a4421c95949bE2D4E3",
      "to": "0x55d398326f99059ff775485246999027b3197955",
      "data": "0x095ea7b3"
    }
  ],
  "simulate": false
}

The response contains data.security and omits exec_summary, results and simulation_error. Checks that depend on execution evidence — an approval created inside a nested call, the proportion of a balance transferred — are unavailable in this mode.

Tron Transactions

Tron accepts two request shapes. The flat evm_transactions shape every other chain uses, or the unsigned transaction object tronWeb.transactionBuilder returns, as tron_transactions. The second lets a wallet forward what it already holds; prefer it on Tron.

Send the object tronWeb.transactionBuilder.* returned, unmodified. Addresses are accepted in either encoding tronWeb emits — 21-byte hex, or the Base58 form you get with visible: true. txID, visible and raw_data_hex are ignored, and the { "method": "tron_sendTransaction", "params": … } provider envelope is unwrapped. dapp_url, simulate and requested_items work exactly as they do for evm_transactions.

Amounts Are Decimal Here

Numbers inside a Tron transaction are read as decimal only — unlike the Numeric Fields of this API, where 0x marks hex. A 0x-prefixed amount is a 400, as is any amount, threshold or key weight that cannot be read. Nothing is defaulted to zero.

Which Operations Are Simulated

raw_data.contract[0].type decides. Simulated. TransferContract, TransferAssetContract, TriggerSmartContract, FreezeBalanceV2Contract, UnfreezeBalanceV2Contract, DelegateResourceContract, UnDelegateResourceContract, WithdrawExpireUnfreezeContract. Assessed, but not simulated. A vote, a reward withdrawal, an account-permission change and a Stake 1.0 freeze are all real transactions with nothing for the simulator to execute: AccountPermissionUpdateContract, VoteWitnessContract, WithdrawBalanceContract, AccountUpdateContract, CancelAllUnfreezeV2Contract, FreezeBalanceContract, UnfreezeBalanceContract, ParticipateAssetIssueContract, CreateSmartContract. For these, results is empty, simulation_error names the operation, and security is still a full assessment. Anything else also returns a verdict rather than an error, so a transaction type Tron adds later keeps working.

Account Permission Changes

AccountPermissionUpdateContract is read in full: which permission block each new key lands in, the signature threshold, the key weights, and — for an active permission — the operations it is limited to.

Finding	When
`tx_tron_permission_transfer`	Another account gains a key that can take value out: an `owner` key, or an `active` key permitting `TransferContract`, `TransferAssetContract`, `TriggerSmartContract` or `AccountPermissionUpdateContract`.
`tx_tron_permission_delegated`	Another account gains a key that cannot: a `witness` key, or an `active` key permitting none of the four above.
`tx_tron_permission_unusable`	A permission’s threshold exceeds the total weight of its own keys, so it could never be used again.
`tx_tron_permission_update`	The signer changes their own permissions and no other account gains a key.

All four come from the request, so they are reported with results empty. The flat evm_transactions shape cannot express this operation at all.

Input requirement: an active permission must carry its 32-byte operations bitmap, as hex or base64. Its contents decide which of the first two findings applies, so a bitmap that cannot be read is a 400.

Surface tx_tron_permission_transfer prominently. One signature grants a key to the account — TRX, every TRC-20 and TRC-10, staked balances and future deposits at once. It is not an approval, so it will not appear in any approval-review screen, and revoking it needs a further permission change.

Numeric Fields

Every int | string field in this request — value, gas, gas_price, max_fee_per_gas, max_priority_fee_per_gas, nonce, type, block_height, token_id, token_value, and the amount inside freeze_balance and delegate_resource — accepts all three of:

Form	Example
JSON number	`1000000`
Decimal string	`"1000000"`
`0x`-prefixed hex	`"0xf4240"`

The three are equivalent. Send strings above 2^53 so JavaScript callers do not lose precision. A hex string must carry the 0x prefix: "f4240" is a 400.

Numbers inside a tron_transactions object are decimal only. See Amounts Are Decimal Here.

Errors

HTTP status	Example status	When it happens
`400`	`invalid request`	A required field is missing, a value cannot be read, two aliases of one field disagree, both request shapes were sent, more than one transaction was sent, or the chain is unsupported.
`401`	Authentication error	`X-API-KEY` is missing or invalid.
`429`	`too many requests`	The caller exceeded its request limit.
`500`	`internal server error`	HashDit could not complete the request.

Error responses include a detail or message explaining the failure:

{
  "code": "-1",
  "status": "invalid request",
  "detail": "send exactly one transaction; batch analysis is not supported"
}

Two more worth recognising, both specific to tron_transactions:

{
  "code": "-1",
  "status": "invalid request",
  "detail": "send either 'tron_transactions' or 'evm_transactions', not both: they describe the same request two different ways and only one of them can be the one the user is signing"
}

{
  "code": "-1",
  "status": "invalid request",
  "detail": "tron_transactions[0]: could not read 'amount' as a number: '0xf4240'. Tron writes these in decimal; a 0x-prefixed value is not a Tron amount"
}

Request/Response

Request fields accept both camelCase and snake_case. See Request Field Names.

Headers

X-API-KEY

string

required

Your HashDit API key.

Body

application/json

Send exactly one transaction, in exactly one of evm_transactions or tron_transactions.

Sending both shapes, or more than one transaction, is a 400.

evm_transactions

object[]

required

The transaction to analyze. Alias: transactions.

Send this or tron_transactions, not both, and send exactly one item.

Required array length: 1 element

Show child attributes

Example:

[
  {
    "chain_id": "56",
    "from": "0x000000000000000000000000000000000000dead",
    "to": "0x6ad549e6312114e646f30cDDde75e15a96d86233",
    "value": "1000000000000000000",
    "data": "0x"
  }
]

tron_transactions

object[]

On Tron you can skip the flattening entirely: send the object tronWeb.transactionBuilder.* returned, unmodified. See the Tron Unsigned Transaction example in the playground.

Unmodified unsigned Tron transactions. Alias: tronTransactions.

Send this or evm_transactions, not both, and send exactly one item. No chain_id is needed — a Tron transaction identifies its own chain.

See Tron Transactions.

Required array length: 1 element

dapp_url

string

Full URL of the dApp that initiated the transaction. Alias: dappUrl.

Optional, recommended.

simulate

boolean

default:true

Defaults to true.

Set to false to return the security verdict without simulation output. exec_summary, results and simulation_error are omitted. Checks that depend on execution evidence — an approval created inside a nested call, the proportion of a balance transferred — are unavailable in this mode.

requested_items

object

Which simulation sections to include in results.

Show child attributes

Response

Successful response.

code: "0" means the API request succeeded; it does not mean the transaction would. Check exec_summary.result_code and results[0].revert for the simulation outcome.

A revert is served at HTTP 200. simulation_error is null when execution produced a result — including a revert.

Every successful call uses the standard envelope: code, status, data.

code

string

"0" when the API request succeeded.

Example:

"0"

status

string

"ok" on success; otherwise an error label.

Example:

"ok"

data

object

Successful payload.

security is always present on success.

exec_summary, results and simulation_error are omitted when simulate is false.

tron_fee_limit is Tron only, and present only when both inputs are available.

Show child attributes

​Using The Recommendation

​Security Coverage

​Security Analysis Without Simulation

​Tron Transactions

​Amounts Are Decimal Here

​Which Operations Are Simulated

​Account Permission Changes

​Numeric Fields

​Errors

​Request/Response

Headers

Body

Response

Using The Recommendation

Security Coverage

Security Analysis Without Simulation

Tron Transactions

Amounts Are Decimal Here

Which Operations Are Simulated

Account Permission Changes

Numeric Fields

Errors

Request/Response