> ## 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 — Batch Addresses

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

Analyze multiple transaction-history targets and token contracts in one request. Every input item carries its own `chain_id`, so one batch may cover more than one network.

<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

Provide at least one `user_addresses` item and at least one item across `target_addresses` and `token_addresses`. The three arrays may contain at most 1000 items in total.

<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 '{
      "user_addresses": [
        {"chain_id": 1, "address": "0x938915fd4b7c188a21ad73ed655ae1f18c334146"}
      ],
      "target_addresses": [
        {"chain_id": 56, "address": "0x938915fd4b7c188a21ad73ed655ae1f18c334146"},
        {"chain_id": 999999, "address": "0x1111111111111111111111111111111111111111"}
      ],
      "token_addresses": [
        {"chain_id": 56, "address": "0x55d39f326f99059ff775485246999027b3197956"}
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": "0",
    "status": "ok",
    "data": {
      "target_addresses": [
        {
          "chain_id": 56,
          "address": "0x938915fd4b7c188a21ad73ed655ae1f18c334146",
          "is_poisoning": "1",
          "mimics_user": "1",
          "mimics_exchange": "0"
        },
        {
          "chain_id": 999999,
          "address": "0x1111111111111111111111111111111111111111",
          "error": {
            "code": "unsupported_chain",
            "detail": "unsupported chainId: 999999"
          }
        }
      ],
      "token_addresses": [
        {
          "chain_id": 56,
          "address": "0x55d39f326f99059ff775485246999027b3197956",
          "is_poisoning": "0",
          "mimics_top_token": "0",
          "matched_token": ""
        }
      ]
    }
  }
  ```
</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="user_addresses" type="object[]" required>
  One or more connected wallet addresses used for lookalike comparisons.
</ParamField>

<ParamField body="user_addresses[].chain_id" type="string" required>
  Network identifier for this user address, sent as a string in Try It. JSON clients may also send a numeric chain ID.
</ParamField>

<ParamField body="user_addresses[].address" type="string" required>
  User address on the specified chain.
</ParamField>

<ParamField body="target_addresses" type="object[]" default="[]">
  Transaction-history addresses to analyze. At least one target or token item is required.
</ParamField>

<ParamField body="token_addresses" type="object[]" default="[]">
  Token contracts to analyze. At least one target or token item is required.
</ParamField>

<ParamField body="target_addresses[].chain_id" type="string" required>
  Network identifier for this target item, sent as a string in Try It. JSON clients may also send a numeric chain ID.
</ParamField>

<ParamField body="target_addresses[].address" type="string" required>
  Target address on the specified chain.
</ParamField>

<ParamField body="token_addresses[].chain_id" type="string" required>
  Network identifier for this token item, sent as a string in Try It. JSON clients may also send a numeric chain ID.
</ParamField>

<ParamField body="token_addresses[].address" type="string" required>
  Token contract on the specified chain.
</ParamField>

## Response Fields

<ResponseField name="code" type="string" required>
  API result code. `"0"` indicates success; non-zero values indicate an error.
</ResponseField>

<ResponseField name="status" type="string" required>
  Request status. A successful completed response returns `"ok"`.
</ResponseField>

<ResponseField name="data.target_addresses" type="object[]">
  Target results in input order.
</ResponseField>

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

<ResponseField name="data.target_addresses[].mimics_user" type="string">
  `"1"` when the target resembles a user address in the same address family.
</ResponseField>

<ResponseField name="data.target_addresses[].mimics_exchange" type="string">
  `"1"` when the target resembles a known exchange or bridge address.
</ResponseField>

<ResponseField name="data.token_addresses" type="object[]">
  Token results in input order.
</ResponseField>

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

<ResponseField name="data.target_addresses[].error" type="object">
  Per-item validation error. Its presence does not invalidate successful siblings.
</ResponseField>

## How to Use the Response

* Results preserve the separate target and token groups and their input order.
* An item with `error` failed validation; successful sibling items remain usable.
* Branch on each successful item's `is_poisoning` value and compare it with the string `"1"`.
* `mimics_user`, `mimics_exchange`, and `mimics_top_token` explain the detected signal.
* `"0"` means no configured signal was detected. It is not a guarantee of safety.

## Errors and Retry Guidance

| Condition | Where reported | Client action |
| - | - | - |
| Unsupported item chain | Item `error.code = "unsupported_chain"` | Remove or correct that item; keep successful siblings. |
| Invalid item address | Item `error.code = "invalid_address"` | Correct that address; keep successful siblings. |
| Empty target and token arrays | HTTP `422` | Add at least one target or token item. |
| More than 1000 total items | HTTP `422` | Split the workload into smaller batches. |
| Missing or invalid API key | HTTP `401` | Fix authentication; do not retry unchanged. |
| Rate limit exceeded | HTTP `429` | Retry with exponential backoff and jitter. |
| Transient service failure | HTTP `500` | Retry a bounded number of times with backoff. |