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

# Address Poisoning — Single Address

<span className="api-lifecycle-source" data-lifecycle="sync">Synchronous endpoint</span>

Analyze one target address for threat-intelligence and visual-mimicry signals. HashDit-owned request fields are documented in `snake_case`; equivalent camelCase input remains accepted for compatibility.

<Warning>
  All verdict flags are the strings `"0"` and `"1"`, not booleans. Compare a flag with `"1"`; the string `"0"` is truthy in JavaScript.
</Warning>

## Quick Start

Include `user_address` whenever the connected wallet is available. It enables the classic address-poisoning check against lookalike transaction-history entries.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://service.hashdit.io/v2/hashdit/address-poisoning \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --data '{
      "chain_id": 56,
      "address": "0x938915fd4b7c188a21ad73ed655ae1f18c334146",
      "user_address": "0x938915fd4b7c188a211113ed655ae1f18c334146"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": "0",
    "status": "ok",
    "data": {
      "target_address": {
        "is_poisoning": "1",
        "mimics_user": "1",
        "mimics_exchange": "0"
      },
      "token_address": {},
      "target_address_input": "0x938915fd4b7c188a21ad73ed655ae1f18c334146",
      "user_address_input": "0x938915fd4b7c188a21ad73ed655ae1f18c334146",
      "token_address_input": ""
    }
  }
  ```
</ResponseExample>

## Request Fields

<ParamField header="X-API-KEY" type="string" required>
  Your HashDit API key. Missing or invalid keys return HTTP `401`. Keep the key on a trusted server.
</ParamField>

<ParamField body="chain_id" type="string" required>
  Network identifier, such as `"56"`. JSON clients may also send a numeric chain ID; supported non-EVM aliases are accepted.
</ParamField>

<ParamField body="address" type="string" required>
  Target address to analyze.
</ParamField>

<ParamField body="user_address" type="string">
  Connected wallet address used for the lookalike comparison.
</ParamField>

<ParamField body="token_address" type="string">
  Token contract to compare with well-known tokens on the same chain.
</ParamField>

## Response Fields

<ResponseField name="code" type="string" required>
  `"0"` indicates that the request completed successfully.
</ResponseField>

<ResponseField name="status" type="string" required>
  `"ok"` for a completed request.
</ResponseField>

<ResponseField name="data.target_address.is_poisoning" type="string">
  Aggregate target verdict: `"1"` when a poisoning signal was detected, otherwise `"0"`.
</ResponseField>

<ResponseField name="data.target_address.mimics_user" type="string">
  `"1"` when the target is confusable with `user_address`.
</ResponseField>

<ResponseField name="data.target_address.mimics_exchange" type="string">
  `"1"` when the target is confusable with a known exchange or bridge address.
</ResponseField>

<ResponseField name="data.token_address.is_poisoning" type="string">
  Aggregate token verdict when `token_address` was supplied.
</ResponseField>

<ResponseField name="data.token_address.mimics_top_token" type="string">
  `"1"` when the token resembles a well-known token on that chain.
</ResponseField>

<ResponseField name="data.token_address.matched_token" type="string">
  The matched token label, or an empty string when there is no match.
</ResponseField>

## How to Use the Response

* Branch on `data.target_address.is_poisoning`; it is the aggregate target verdict.
* Use `mimics_user` and `mimics_exchange` to explain why a warning was shown.
* `user_address` enables the classic poisoning comparison. If omitted, `mimics_user` remains `"0"`.
* `"0"` means no configured signal was detected. It is not a guarantee that an address is safe.
* If `token_address` was not requested, `data.token_address` may be an empty object.

## Errors and Retry Guidance

| HTTP | Meaning | Client action |
| - | - | - |
| `400` | Unsupported chain or invalid address | Correct the request; do not retry unchanged. |
| `401` | Missing or invalid API key | Fix authentication; do not retry unchanged. |
| `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. |