Token Approval Security - HashDit API Documentation

curl --request POST \
  --url https://service.hashdit.io/v2/hashdit/token-approval-security \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "chainId": "56",
  "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
  "includeBalance": true,
  "includeSpenderRisk": true
}
'

{
  "code": "0",
  "status": "ok",
  "data": {
    "count": 2,
    "hasMore": false,
    "approval_status": [
      {
        "token": "0x55d398326f99059ff775485246999027b3197955",
        "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
        "spender": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
        "amount_raw": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
        "valid_allowance": "4500000000000000000",
        "token_decimal": 18,
        "affected_usd_amount": 4.5,
        "potential_affected_usd_amount": "Unlimited",
        "token_name": "Binance-Peg BSC-USD",
        "balance": "4500000000000000000",
        "spender_risk": {
          "is_risky": false,
          "risk_level": 0,
          "risk_details": [],
          "risk_level_display": "Trusted"
        }
      },
      {
        "token": "0xd8a2ae43fd061d24acd538e3866ffc2c05151b41",
        "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
        "spender": "0xb0b195aefa3650a6908f15cdac7d92f8a5791b0b",
        "amount_raw": "9999999999999999999999",
        "valid_allowance": "9999999999999999999999",
        "token_decimal": 18,
        "affected_usd_amount": 0.02,
        "potential_affected_usd_amount": 0.02,
        "token_name": null,
        "balance": "9999999999999999999999",
        "spender_risk": {
          "is_risky": true,
          "risk_level": 5,
          "risk_details": [
            "blacklist_manual"
          ],
          "risk_level_display": "High Risk"
        }
      }
    ],
    "valid_approved_tokens": [
      {
        "token_name": "Binance-Peg BSC-USD",
        "token_address": "0x55d398326f99059ff775485246999027b3197955",
        "token_price": 1,
        "token_decimal": 18
      }
    ],
    "summary": {
      "total_affected_usd_amount": 4.52,
      "total_potential_affected_usd_amount": 4.52,
      "risky_approval_count": 1,
      "total_risky_usd_amount": 0.02,
      "risky_approval_indices": [
        1
      ]
    }
  }
}

POST

hashdit

token-approval-security

curl --request POST \
  --url https://service.hashdit.io/v2/hashdit/token-approval-security \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "chainId": "56",
  "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
  "includeBalance": true,
  "includeSpenderRisk": true
}
'

{
  "code": "0",
  "status": "ok",
  "data": {
    "count": 2,
    "hasMore": false,
    "approval_status": [
      {
        "token": "0x55d398326f99059ff775485246999027b3197955",
        "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
        "spender": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
        "amount_raw": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
        "valid_allowance": "4500000000000000000",
        "token_decimal": 18,
        "affected_usd_amount": 4.5,
        "potential_affected_usd_amount": "Unlimited",
        "token_name": "Binance-Peg BSC-USD",
        "balance": "4500000000000000000",
        "spender_risk": {
          "is_risky": false,
          "risk_level": 0,
          "risk_details": [],
          "risk_level_display": "Trusted"
        }
      },
      {
        "token": "0xd8a2ae43fd061d24acd538e3866ffc2c05151b41",
        "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
        "spender": "0xb0b195aefa3650a6908f15cdac7d92f8a5791b0b",
        "amount_raw": "9999999999999999999999",
        "valid_allowance": "9999999999999999999999",
        "token_decimal": 18,
        "affected_usd_amount": 0.02,
        "potential_affected_usd_amount": 0.02,
        "token_name": null,
        "balance": "9999999999999999999999",
        "spender_risk": {
          "is_risky": true,
          "risk_level": 5,
          "risk_details": [
            "blacklist_manual"
          ],
          "risk_level_display": "High Risk"
        }
      }
    ],
    "valid_approved_tokens": [
      {
        "token_name": "Binance-Peg BSC-USD",
        "token_address": "0x55d398326f99059ff775485246999027b3197955",
        "token_price": 1,
        "token_decimal": 18
      }
    ],
    "summary": {
      "total_affected_usd_amount": 4.52,
      "total_potential_affected_usd_amount": 4.52,
      "risky_approval_count": 1,
      "total_risky_usd_amount": 0.02,
      "risky_approval_indices": [
        1
      ]
    }
  }
}

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

For each approval: the raw allowance, the realistic exposure after capping to the current balance, the USD value at risk, and — opt-in — risk assessments for the spender, the token, and the owner. A top-level summary aggregates total USD at risk so an approval-manager screen can render its banner without walking the array.

Request Notes

Supported Chains

Only Ethereum (1), BNB Smart Chain (56), and TRON. See Supported Chains. Any other chainId is rejected with 400. Responses are cached ~60 seconds per unique query + flag combination. A revocation the user just made may take up to that long to disappear. On TRON, responses echo case-preserved base58 — TRON encodes its checksum in letter casing, so a lowercased TRON address is not usable. Use the returned form for anything sent to a node or explorer.

Request Combinations

At least one of owner or spender is required. token cannot be sent on its own.

Combination	Allowed
`owner` / `spender` / `owner`+`spender`	Yes
any of the above + `token`	Yes
`token` alone	No — `400`

Opt-In Fields

These response fields are added only when you set the matching request flag to true. All flags default to false. Enable only the enrichments you render — each flag adds a lookup and its own latency. For a wallet-facing approval list, includeBalance + includeSpenderRisk is usually the right pairing.

Request flag	Adds to each row
`includeBalance`	`balance`
`includeAddressTypes`	`spender_type`, `owner_type`
`includeSpenderRisk`	`spender_risk`
`includeTokenRisk`	`token_risk`
`includeOwnerRisk`	`owner_risk`

If the flag is false or omitted, that field is left out of the JSON — you did not ask for it. If the flag is true, the field is always in the JSON. A value means the lookup succeeded. null means the lookup failed; the rest of the row is still valid. Prefer retrying over showing an error screen. In JavaScript, check that the key exists ("spender_risk" in row) before reading it. Do not use row.spender_risk !== null — a missing key is undefined, and undefined !== null is true. Always send includeBalance: true on an approval-management screen. It turns “Unlimited / Unlimited” into “$4.50 at risk now, unlimited going forward”, and it lets an unlimited approval on an emptied wallet correctly report valid_allowance: "0".

Response Notes

USD Fields

Every row always includes both fields. They are never null. They price different amounts and can disagree. amount_raw, valid_allowance, and balance are uint256-scale strings — parse with BigInt. The USD fields are ordinary floats when they are numbers.

Field	Prices	Question it answers
`affected_usd_amount`	`valid_allowance`	How much can be taken right now?
`potential_affected_usd_amount`	`amount_raw` (not capped to the wallet balance)	How much could be taken if the wallet is re-funded?

Each value is one of three types. Check the type before formatting — do not assume a number.

Value	Meaning	Show as
A number	A finite USD figure. `0` means nothing is at risk.	`$1,234.56` or `$0`
`"Unlimited"`	The allowance is unbounded (infinite approval). No dollar figure is invented.	`Unlimited`
`"Unknown"`	Decimals or price were missing, so USD could not be computed. This is not zero — funds may still be at risk.	`Unknown` — never `$0`

With includeBalance: true, an infinite on-chain approval often returns both a number and "Unlimited":

affected_usd_amount: 4.5 — the wallet holds $4.50, so only that can be taken today
potential_affected_usd_amount: "Unlimited" — the allowance is still unbounded, so later deposits can be taken too

Without includeBalance, both fields are often "Unlimited", even if the wallet is empty.

Risk Object

Returned on a row when you set includeSpenderRisk, includeTokenRisk, or includeOwnerRisk.

Field	Use it for
`is_risky`	The yes/no verdict. Show a warning when this is `true`.
`risk_level` / `risk_level_display`	Color and label in the UI (table below).
`risk_details`	Logs and support tickets only.

Do not decide “risky” from risk_level yourself (for example risk_level >= 4). Use is_risky. Do not write logic against risk_details values (for example "blacklist_manual"). Those strings are not a stable list and can change. The array is [] when is_risky is false.

`risk_level`	`risk_level_display`	Suggested UI
`-1`	`"Unknown"`	Grey. Not in the database — not a safety statement.
`0`	`"Trusted"`	Green. Affirmatively verified.
`1`–`3`	`"Low Risk"`	Yellow / informational.
`4`	`"Medium Risk"`	Orange. Ask the user to confirm.
`≥ 5`	`"High Risk"`	Red. Confirmed malicious — block or strongly warn.

When risk_level is 0, the address is considered safe. -1 means “no data” — do not consider the address as safe.

`summary` Totals

summary is a page-level banner. Do not add up the rows yourself.

The same token balance approved to several spenders is counted once, not once per spender.
Only rows with a number USD value are included. "Unlimited" and "Unknown" add 0.
So 0 can mean “nothing at risk” or “every row on this page is unlimited or unpriceable.”
If any row is "Unlimited" or "Unknown", treat the total as a floor: at least $X, plus N unlimited approvals.
includeBalance: true turns most unlimited rows into a number and closes that gap.

valid_approved_tokens is a lookup table for tokens HashDit has indexed (name, address, price, decimals). Unindexed tokens still appear in approval_status; they are just missing from this list. hasMore is evaluated before filter: "only-valid" runs, so a filtered page can show count well below limit while hasMore is still true. Do not stop paginating on a short count.

Headers

X-API-KEY

string

required

Your HashDit API key

Body

application/json

Approval query. At least one of owner or spender is required. token cannot be sent on its own.

chainId

string

required

int or string. Only 1 (Ethereum), 56 (BSC), or 728126428 / "tron" (TRON). Any other chain is rejected with 400. See Supported Chains.

Example:

"56"

owner

string

Owner / approver address. At least one of owner or spender is required.

Example:

"0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87"

spender

string

Spender address. At least one of owner or spender is required.

token

string

Restrict to one token contract. Cannot be sent on its own — token alone returns 400.

page

integer

default:1

1-based page number. Values below 1 are treated as 1.

limit

integer

default:50

Rows per page. Ceiling 100 — higher values are clamped, not rejected.

filter

string

Only "only-valid" is accepted; it drops rows whose valid_allowance is 0. Any other value is a validation error.

includeBalance

boolean

default:false

Read each token's live on-chain balance for the owner.

includeSpenderRisk

boolean

default:false

Add spender_risk to every row.

includeTokenRisk

boolean

default:false

Add token_risk to every row.

includeOwnerRisk

boolean

default:false

Add owner_risk to every row.

includeAddressTypes

boolean

default:false

Classify each spender and owner as "eoa" or "contract".

Response

Successful response. Envelope is {code, status, data}.

code

string

API status code. "0" indicates success.

Example:

"0"

status

string

Example:

"ok"

data

object

Show child attributes

​Request Notes

​Supported Chains

​Request Combinations

​Opt-In Fields

​Response Notes

​USD Fields

​Risk Object

​summary Totals

Headers

Body

Response

Request Notes

Supported Chains

Request Combinations

Opt-In Fields

Response Notes

USD Fields

Risk Object

`summary` Totals