EIP-712 Signature Security - HashDit API Documentation

POST

hashdit

eip712-security

{
  "address": "0x1d99c0ac928f58595b9d060c79f799fa38d171f4",
  "chain_id": 1,
  "url": "https://app.uniswap.org",
  "eip712_message": {
    "primaryType": "Permit",
    "types": {
      "EIP712Domain": [
        {"name": "name", "type": "string"},
        {"name": "chainId", "type": "uint256"},
        {"name": "verifyingContract", "type": "address"}
      ],
      "Permit": [
        {"name": "owner", "type": "address"},
        {"name": "spender", "type": "address"},
        {"name": "value", "type": "uint256"},
        {"name": "nonce", "type": "uint256"},
        {"name": "deadline", "type": "uint256"}
      ]
    },
    "domain": {
      "chainId": 1,
      "name": "USD Coin",
      "verifyingContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    },
    "message": {
      "owner": "0x1d99c0ac928f58595b9d060c79f799fa38d171f4",
      "spender": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
      "value": 1000000,
      "nonce": 5,
      "deadline": 1775000000
    }
  }
}

{
  "code": "0",
  "status": "ok",
  "data": {
    "overall_score": 5,
    "overall_risk_level": "Significant Risk",
    "intent": "TOKEN_APPROVAL",
    "recommended_action": "BLOCK",
    "risk_details": [
      {
        "name": "eip712_permit_max_uint_allowance",
        "score": 4,
        "risk_level": "High Risk",
        "description": "Permit-like signature contains near-unlimited allowance."
      }
    ],
    "entities": {
      "addresses": {
        "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45": {
          "score": 0,
          "risk_level": "No Obvious Risk"
        }
      }
    }
  }
}

Synchronous endpoint Analyze an EIP-712 typed-data signing request before the user signs it. The response is a risk assessment with an actionable recommendation. Typical findings: unlimited permits, a login message that actually approves transfers, a blacklisted spender, or a suspicious marketplace order.

The HashDit wrapper uses chain_id and eip712_message. The embedded EIP-712 payload keeps protocol and application casing such as primaryType, verifyingContract, chainId, and application-defined message field names.

Quick Start

{
  "address": "0x1d99c0ac928f58595b9d060c79f799fa38d171f4",
  "chain_id": 1,
  "url": "https://app.uniswap.org",
  "eip712_message": {
    "primaryType": "Permit",
    "types": {
      "EIP712Domain": [
        {"name": "name", "type": "string"},
        {"name": "chainId", "type": "uint256"},
        {"name": "verifyingContract", "type": "address"}
      ],
      "Permit": [
        {"name": "owner", "type": "address"},
        {"name": "spender", "type": "address"},
        {"name": "value", "type": "uint256"},
        {"name": "nonce", "type": "uint256"},
        {"name": "deadline", "type": "uint256"}
      ]
    },
    "domain": {
      "chainId": 1,
      "name": "USD Coin",
      "verifyingContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    },
    "message": {
      "owner": "0x1d99c0ac928f58595b9d060c79f799fa38d171f4",
      "spender": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
      "value": 1000000,
      "nonce": 5,
      "deadline": 1775000000
    }
  }
}

{
  "code": "0",
  "status": "ok",
  "data": {
    "overall_score": 5,
    "overall_risk_level": "Significant Risk",
    "intent": "TOKEN_APPROVAL",
    "recommended_action": "BLOCK",
    "risk_details": [
      {
        "name": "eip712_permit_max_uint_allowance",
        "score": 4,
        "risk_level": "High Risk",
        "description": "Permit-like signature contains near-unlimited allowance."
      }
    ],
    "entities": {
      "addresses": {
        "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45": {
          "score": 0,
          "risk_level": "No Obvious Risk"
        }
      }
    }
  }
}

Request Fields

string

required

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

string

required

Address of the account being asked to sign.

integer

required

EVM chain identifier. See Supported Chains.

string

Originating dApp URL. Without it, URL threat-intelligence checks cannot run.

object

required

Typed-data payload exactly as the dApp sent it. Preserve primaryType, domain, types, message, and application-defined field names.

Show EIP-712 message fields

object

required

Protocol type definitions keyed by struct name. Preserve every type name and field in the original payload.

string

required

Primary EIP-712 struct name, such as Permit. This protocol field intentionally keeps its original casing.

object

required

Domain-separator payload. Preserve protocol fields such as chainId and verifyingContract.

object

required

Typed message body. Its fields are defined by types; forward it unchanged.

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".

string

Signing-flow decision: ALLOW, WARN, or BLOCK.

string

Classified meaning of the typed-data request.

integer

Maximum triggered checkpoint score from 0 to 5.

string

Human-readable risk label corresponding to overall_score.

object[]

Triggered findings with stable names, evidence, severity, and descriptions.

object

Risk enrichment for extracted addresses, URL, and verifying contract.

`recommended_action`

Use this field as the decision. Do not compute your own cutoff from overall_score — that mapping can change.

Value	Meaning
`"ALLOW"`	No significant risk detected.
`"WARN"`	Suspicious signals — warn before the user signs.
`"BLOCK"`	Strong risk — recommend blocking the signature.

A single severe finding is enough to reach BLOCK. Do not treat risk_details as a tally.

`intent`

What the user is actually signing.

Value	Description
`"TOKEN_APPROVAL"`	ERC-20 permit or allowance to a spender.
`"NFT_APPROVAL"`	ERC-721/1155 approval to a spender or operator.
`"TOKEN_TRANSFER"`	EIP-3009 gasless transfer — moves funds outright, no allowance.
`"ORDER_SIGNATURE"`	Marketplace order (Seaport, OpenSea listings).
`"DELEGATION"`	Delegating control to another address.
`"STAKING"`	Staking-related signature.
`"LOGIN"`	Sign-in / authentication message. Typically low risk.
`"UNKNOWN"`	Could not classify.

Show Risk detail fields

Each item is a checkpoint that fired. The array is empty when nothing fired.Branch on name, not on description. Identifiers are stable; wording is not.

string

Stable identifier for the check that fired. Use this field for application logic.

object

Evidence associated with the finding.

integer

Runtime severity score for this finding. risk_level is its human-readable label.

string

Human-readable risk label corresponding to this finding’s score.

string

Human-readable explanation. Display it, but do not parse it for application logic.

Which time-window checkpoint applies depends on intent (approval vs marketplace order vs login). You do not need to pick one — the response names the checkpoint that fired.

Show Entity risk fields

Risk enrichment for addresses extracted from the message, plus the URL and verifying contract when those apply.

object

Always present. Maps each extracted address to its score and risk_level.

integer

Risk score from 0 to 5 for the address represented by the map key.

string

Human-readable address risk label.

object

Present when url was sent and threat-intelligence enrichment succeeded.

integer

Risk score from 0 to 5 for the supplied URL.

string

Human-readable URL risk label.

object

Present when the EIP-712 domain declares verifyingContract. This protocol field intentionally keeps its original casing.

integer

Risk score from 0 to 5 for the verifying contract.

string

Human-readable verifying-contract risk label.

A missing entities.url means either no url was supplied, or enrichment was unavailable. Threat-intelligence timeouts do not turn the call into a 500 — the response is still served from structural analysis.

How to Use the Response

Use recommended_action as the signing-flow decision.
Use intent to describe what the user is authorizing.
Render every risk_details item; use name for application logic and description for copy.
Use entities for contextual address, URL, and verifying-contract risk—not as a replacement for the overall recommendation.

Risk Level Reference

Used for overall_risk_level and nested risk_level fields. overall_score is the maximum triggered score.

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

Errors and Retry Guidance

HTTP	Meaning	Client action
`400`	Invalid typed-data structure, chain, address, or value	Correct the request; do not retry unchanged.
`401`	Missing or invalid API key	Fix authentication.
`422`	Wrapper request schema validation failed	Correct HashDit wrapper fields; preserve protocol payload field names.
`429`	Rate limit exceeded	Retry with exponential backoff and jitter.
`500`	Transient service failure	Retry a bounded number of times with backoff.

​Quick Start

​Request Fields

​Response Fields

​recommended_action

​intent

​How to Use the Response

​Risk Level Reference

​Errors and Retry Guidance

Quick Start

Request Fields

Response Fields

`recommended_action`

`intent`

How to Use the Response

Risk Level Reference

Errors and Retry Guidance