Token Approval Security - HashDit API Documentation

Synchronous endpoint

HashDit-owned request fields are documented in snake_case. Equivalent camelCase input remains accepted for compatibility.

Find a wallet’s active token approvals, current exposure, and risky spenders.

Quick Start

Query an owner’s approvals with balance capping and spender-risk enrichment:

curl --request POST \
  --url https://service.hashdit.io/v2/hashdit/token-approval-security \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "chain_id": "56",
    "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
    "include_balance": true,
    "include_spender_risk": true
  }'

{
  "code": "0",
  "status": "ok",
  "data": {
    "count": 1,
    "has_more": false,
    "approval_status": [
      {
        "token": "0x55d398326f99059ff775485246999027b3197955",
        "owner": "0x26d61f23bbc94d7b2139f9c581722bf4e8b64b87",
        "spender": "0x10ed43c718714eb63d5aa57b78b54704e256024e",
        "amount_raw": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
        "valid_allowance": "4500000000000000000",
        "affected_usd_amount": 4.5,
        "potential_affected_usd_amount": "Unlimited",
        "spender_risk": {
          "is_risky": false,
          "risk_level": 0,
          "risk_level_display": "Trusted",
          "risk_details": []
        }
      }
    ],
    "summary": {
      "total_affected_usd_amount": 4.5,
      "risky_approval_count": 0
    }
  }
}

Request Fields

string

required

Your HashDit API key. Missing or invalid keys return HTTP 401. Keep the key on a trusted server.

string

required

Ethereum, BNB Smart Chain, or TRON identifier, such as "1", "56", or "tron". JSON clients may also send a numeric chain ID. See Supported Chains.

string

Wallet whose outstanding approvals should be returned.

string

Filter approvals by spender. At least one of owner or spender is required.

string

Optional token filter. It cannot be sent without owner or spender.

string

Optional result filter, including only-valid.

integer

Maximum number of approvals to return on this page.

integer

1-based page number. Defaults to 1.

boolean

default:"false"

Add the owner’s current token balance and cap immediate exposure to it.

boolean

default:"false"

Add spender risk enrichment to every row.

boolean

default:"false"

Add token-contract risk enrichment to every row.

boolean

default:"false"

Add owner-address risk enrichment to every row.

boolean

default:"false"

Add spender_type and owner_type classification fields to every row.

At least one of owner or spender is required. token is an optional filter and cannot be sent by itself. For an approval-management screen, set both include_balance and include_spender_risk to true.

Response Fields

string

required

API result code. "0" indicates success; non-zero values indicate an error.

string

required

Request status. A successful completed response returns "ok".

integer

Number of rows in approval_status after filtering.

object[]

The approvals returned for this query.

Show Approval row fields

string

required

Token contract address.

string

required

Address that granted the approval.

string

required

Address allowed to spend the token.

string

required

Raw on-chain allowance in the token’s smallest unit. Parse as a big integer.

string

Amount the spender can use now, capped by the owner’s current balance when include_balance is enabled.

integer | null

Token decimals, or null when they could not be resolved.

number | string

Current USD exposure. The value can also be "Unlimited" or "Unknown".

number | string

Potential USD exposure if the wallet receives more tokens. The value can also be "Unlimited" or "Unknown".

string | null

Token name, or null when the token is not indexed.

string | null

Owner balance in raw units when include_balance is enabled.

string | null

Spender classification when include_address_types is enabled.

string | null

Owner classification when include_address_types is enabled.

object | null

Spender risk result when include_spender_risk is enabled.

Show Spender risk fields

boolean

The spender verdict. Use this field to decide whether to show a risk warning.

integer

Numeric risk level from -1 to 5.

string

Human-readable risk label.

string[]

Diagnostic labels for logging and support. Do not treat them as a stable enum.

object | null

Token risk result when include_token_risk is enabled.

Show Token risk fields

boolean

Token-contract risk verdict.

integer

Numeric risk level from -1 to 5.

string

Human-readable risk label.

string[]

Diagnostic labels for logging and support.

object | null

Owner risk result when include_owner_risk is enabled.

Show Owner risk fields

boolean

Owner-address risk verdict.

integer

Numeric risk level from -1 to 5.

string

Human-readable risk label.

string[]

Diagnostic labels for logging and support.

object[]

Metadata for indexed tokens represented in the approval rows.

Show Valid token fields

string | null

Indexed token name.

string

Token contract address.

number | null

Current USD unit price when available.

integer | null

Token decimals when available.

object

Page-level current exposure and risky-approval totals.

Show Summary fields

number

De-duplicated current USD exposure across this page.

number

De-duplicated potential USD exposure across this page.

integer

Number of approval rows with at least one risky enrichment.

number

Current USD exposure across risky approval rows.

integer[]

Zero-based positions of risky rows in approval_status.

boolean

Continue pagination while this value is true.

How to Use the Response

Render each item in approval_status; it contains the raw allowance and the realistic current exposure.
Use summary for page-level totals instead of summing rows yourself.
Use spender_risk.is_risky for the spender decision. Do not derive a verdict from risk_level.
Continue pagination while has_more is true.
Treat "Unknown" and "Unlimited" USD values as explicit states, never as zero.

Risk Level Reference

Use is_risky as the decision field. The numeric level and display label are for presentation.

`risk_level`	`risk_level_display`	Suggested handling
`-1`	`Unknown`	No data; do not treat as safe.
`0`	`Trusted`	No warning is required.
`1`–`3`	`Low Risk`	Show as informational.
`4`	`Medium Risk`	Warn and ask the user to confirm.
`5` or higher	`High Risk`	Block or show a strong warning.

Errors and Retry Guidance

HTTP	Meaning	Client action
`400`	Unsupported chain, invalid address, or invalid owner/spender/token combination	Correct the request; do not retry unchanged.
`401`	Missing or invalid API key	Fix authentication.
`422`	Request schema validation failed	Correct field names or values.
`429`	Rate limit exceeded	Retry with exponential backoff and jitter.
`500`	Transient service failure	Retry a bounded number of times with backoff.

Responses are cached for approximately 60 seconds per unique query and enrichment-flag combination. A recent revocation can remain visible until that cache expires.

​Quick Start

​Request Fields

​Response Fields

​How to Use the Response

​Risk Level Reference

​Errors and Retry Guidance

Quick Start

Request Fields

Response Fields

How to Use the Response

Risk Level Reference

Errors and Retry Guidance