Address reports

You often know things about an address before any dataset does: a customer was scammed through it, or a deposit address on your platform belongs to you. POST /v1/address-reports lets you send that knowledge to us. There are two kinds of report.

report_type	What it says	Needs
abuse (the default)	The address is used for abuse.	A category and at least one verifiable proof: evidence_url or evidence_tx_hash.
own_deposit	The address is one of your own deposit addresses.	No category and no proof.

What a report does

A report goes into a separate intake queue. It never changes a verdict, a score or a label by itself: a screening result stays exactly what the ruleset and the published labels say. Only a later review can turn a report into a published label. The account behind a report is kept for abuse control only and is never attached to a label that may later be published from it.

The received status in the response is a receipt, not a decision. Do not rely on a report to change the result of a check; keep applying your own policy to the verdicts you get.

Request

POST /v1/address-reports with the checks:write scope (see Authentication).

Field	Required	Description
chain	yes	tron, ethereum, bsc, base or bitcoin.
address	yes	The address, at most 160 characters. It is checked for the chain, including the checksum where the format has one.
report_type	no	abuse (default) or own_deposit.
category	for abuse	scam, illicit or exploit. Not accepted for own_deposit.
evidence	yes	A short description of what you know, 1 to 2000 characters.
evidence_url	for abuse, unless evidence_tx_hash is sent	A public https link that supports the report, at most 2048 characters. We never fetch it.
evidence_tx_hash	for abuse, unless evidence_url is sent	A transaction hash on the same chain that shows the abuse, at most 160 characters. It must be well formed for the chain.

Unknown fields are rejected. Abuse is a serious accusation: send only what you can substantiate.

curl

curl -s -X POST https://api.leeri.ai/v1/address-reports \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "address": "'"$ADDRESS"'",
    "report_type": "abuse",
    "category": "scam",
    "evidence": "Received customer funds under a fake investment offer.",
    "evidence_tx_hash": "'"$TX_HASH"'"
  }'

Node.js

const response = await fetch('https://api.leeri.ai/v1/address-reports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chain: 'tron',
    address,
    report_type: 'abuse',
    category: 'scam',
    evidence: 'Received customer funds under a fake investment offer.',
    evidence_tx_hash: txHash,
  }),
});
const { data } = await response.json();

console.log(response.status, data.report_id, data.duplicate);

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/address-reports",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    json={
        "chain": "tron",
        "address": address,
        "report_type": "abuse",
        "category": "scam",
        "evidence": "Received customer funds under a fake investment offer.",
        "evidence_tx_hash": tx_hash,
    },
    timeout=30,
)
data = response.json()["data"]

print(response.status_code, data["report_id"], data["duplicate"])

To confirm one of your own deposit addresses, send "report_type": "own_deposit" with chain, address and evidence, and no category or proof.

Response

A new report answers 202; a repeat answers 200. Both carry the report in data:

Field	Description
report_id	The id of the intake record. Stable across repeats of the same report.
status	received.
chain, address	As stored: EVM and bech32 addresses are lowercased, every other form is kept as sent.
report_type, category	As filed. category is null for own_deposit.
duplicate	true when your account already filed a report of this type for this address in this environment.
created_at	When the report was first received.

There is one report per account, key environment, chain, address and report type. Filing it again answers 200 with the stored report and duplicate: true, and never overwrites the evidence you sent the first time.

Limits and errors

Address reports are limited to 10 per minute per account, across all of its keys; see Rate limits and quotas.

Status	Code	When
400	VALIDATION_ERROR	An unknown field; an address that is invalid for the chain (format or checksum); a missing category on an abuse report, or a category on an own_deposit one; an abuse report with neither evidence_url nor evidence_tx_hash; an evidence_url that is not https; or a transaction hash that is malformed for the chain.
403	SCOPE_ERROR	The key does not have the checks:write scope.
429	RATE_LIMIT_EXCEEDED	More than 10 reports in a minute. Retry after Retry-After.
503	RATE_LIMIT_STORE_UNAVAILABLE	The rate-limit store is unavailable; the request is refused rather than served without a limit. Retry shortly.