REST API

REST API · v1

Dolix API documentation

The Dolix API gives programmatic access to our tools: AML scoring for addresses and transactions, counterparty blacklist search & reports, and PDF receipt forensics. One HTTPS endpoint, JSON in and out, key-based auth.

Every response is JSON with an ok field. Success: { "ok": true, … }. Error: { "ok": false, "error": "…" } with the matching HTTP status.

Base URL

https://api.dolix.io

first request

curl "https://api.dolix.io/health"
# → { "ok": true, "dbAuth": true }

Authentication

Every protected route requires the X-API-Key header. A key is issued to each user inside the Telegram bot (API section) — one live key per account, rotatable without losing the token balance. Requests without a key get 401. If your client prefers Authorization: Bearer <key>, that is accepted too.

key header

curl -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/profile/full?value=98765432"

🔑 Treat the key as a secret. If it leaks, rotate it in the bot — the old key stops working immediately.

Tokens & billing

Paid routes spend tokens: heavier work costs more. Every account starts with 100 free tokens. Tokens belong to the user — rotating the key never resets them. Out of tokens → any paid call returns 402.

Function	Tokens
/profile/full · check a counterparty	3
/v1/aml/address	10
/v1/aml/txid	15
/v1/receipts/check	10
/v1/blacklist/report · add to the blacklist	5

A paid response carries spend headers:

headers

X-Tokens-Cost: 10
X-Tokens-Remaining: 90

Out of tokens → 402 with details:

402 Payment Required

{
  "ok": false,
  "error": "insufficient_tokens",
  "function_code": "aml_address",
  "required": 10,
  "available": 4
}

Rate limits

On top of tokens there is a frequency anti-flood — by default 60 req/min and 2000/day per key. It protects infrastructure and fires before any token spend: exceeding it returns 429 and costs no tokens. Remaining budgets are in the headers.

headers

X-RateLimit-Remaining-Minute: 58
X-RateLimit-Remaining-Day: 4972
X-RateLimit-Total-Used: 1284

Errors

A uniform JSON error with ok:false. When data is missing/unavailable, AML and receipt checks fail closed — an error, never a fabricated 'clean' result — and no tokens are charged.

400	bad_request	Invalid request
401	Unauthorized	Missing/invalid key
402	insufficient_tokens	Out of tokens
403	forbidden	Key/function not allowed
404	Not found	Feature disabled by flag
429	Rate limit exceeded	Rate limit or daily token cap
503	busy / needs_async	Saturated / deadline
500	internal_error	Server error

Service

GET/health

Health check

no key

Lightweight liveness ping. No key, no tokens — use it for uptime monitoring.

Errors

500

internal_error

Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  "https://api.dolix.io/health"

Response · 200 OK

{
  "ok": true,
  "dbAuth": true
}

Counterparty check

GET/profile/full

Check a counterparty

🔑 X-API-Key3 tok.PIIbehind a flag

The main counterparty check: status, violations, statistics and — where available — contact data. A subject is required: free-text value OR exactly one typed param (uid/card/phone/nick/link). Contains personal data; access is governed by server policy.

Query parameters

value	string	Free-text query (or use typed uid/card/phone/nick/link).
base	string	Counterparty platform.bybit · mexc · tg_wallet · all
ads	boolean	Include the counterparty's ads (heavier).
currency	string	Currency for monetary fields.
limit	integer	Page size.
offset	integer	Pagination offset.

Errors

400	bad_request	Invalid or missing parameters. The body carries a specific error code.
401	Unauthorized	Missing or invalid X-API-Key header.
402	insufficient_tokens	Not enough tokens for this call. See X-Tokens-Remaining header and the required field.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/profile/full?value=98765432&base=bybit"

Response · 200 OK

{
  "ok": true,
  "query": "98765432",
  "base": "bybit",
  "total": 1,
  "results": [
    {
      "uid": "98765432",
      "base": "bybit",
      "status": "blacklisted",
      "nickname": "fast_otc_deals",
      "complaints": 4,
      "violations": [
        {
          "type": "non_release",
          "reportedAt": "2026-05-30T11:02:00Z"
        }
      ],
      "stats": {
        "totalOrders": 1280,
        "completionRate": 0.91
      }
    }
  ]
}

AML scoring

GET/v1/aml/address

AML address risk score

🔑 X-API-Key10 tok.behind a flag

Live transaction-graph trace and a risk score for an address (0–100 %, risk level, top connections, fund flow). Proprietary engine, networks TRC20/BEP20/ETH/TON. A cold check takes up to 30–60 s. Fail-closed: if data is unavailable you get 503 + insufficient_data — a clean verdict is never fabricated.

Query parameters

networkrequired	string	Address network.TRC20 · BEP20 · ETH · TON
addressrequired	string	Address to check.

Errors

400	bad_request	Invalid or missing parameters. The body carries a specific error code.
401	Unauthorized	Missing or invalid X-API-Key header.
402	insufficient_tokens	Not enough tokens for this call. See X-Tokens-Remaining header and the required field.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
503	busy / needs_async	Engine saturated or sync deadline exceeded. Retry per Retry-After. No tokens are charged.
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/v1/aml/address?network=TRC20&address=TXk...9pQ"

Response · 200 OK

{
  "ok": true,
  "status": "ok",
  "kind": "address",
  "address": "TXk...9pQ",
  "networkCode": "TRC20",
  "scoringVersion": 50,
  "riskLevel": "high",
  "score": 72,
  "scorePercent": "72.0%",
  "decision": "deny",
  "cached": false,
  "degraded": false,
  "coverage": {
    "tier": "ok",
    "hasProviderErrors": false
  },
  "topConnections": [
    {
      "address": "TM...aZ",
      "amount": "12,500 USDT",
      "direction": "in",
      "label": "sanctioned_exchange"
    }
  ],
  "fundFlowSummary": {
    "inflow": "31,200 USDT",
    "outflow": "30,980 USDT",
    "balance": "220 USDT"
  },
  "checkedAt": "2026-06-24T09:15:00Z"
}

GET/v1/aml/txid

AML transaction risk score

🔑 X-API-Key15 tok.behind a flag

Resolves a transaction by hash, identifies the primary transfer and scores the sender's risk. Returns the same fields as the address check plus primaryTransfer.

Query parameters

networkrequired	string	Transaction network.TRC20 · BEP20 · ETH · TON
txidrequired	string	Transaction hash.

Errors

400	bad_request	Invalid or missing parameters. The body carries a specific error code.
401	Unauthorized	Missing or invalid X-API-Key header.
402	insufficient_tokens	Not enough tokens for this call. See X-Tokens-Remaining header and the required field.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
503	busy / needs_async	Engine saturated or sync deadline exceeded. Retry per Retry-After. No tokens are charged.
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/v1/aml/txid?network=BEP20&txid=0xab...7c3d"

Response · 200 OK

{
  "ok": true,
  "status": "ok",
  "kind": "transaction",
  "txid": "0xab...7c3d",
  "networkCode": "BEP20",
  "senderAddress": "0x4a2...b9f1",
  "recipientAddress": "0x77c...12ab",
  "riskLevel": "low",
  "score": 6,
  "scorePercent": "6.0%",
  "decision": "allow",
  "degraded": false,
  "coverage": {
    "tier": "full",
    "hasProviderErrors": false
  },
  "primaryTransfer": {
    "from": "0x4a2...b9f1",
    "to": "0x77c...12ab",
    "amount": "500",
    "amountUsd": 500,
    "asset": "USDT"
  },
  "checkedAt": "2026-06-24T09:16:00Z"
}

GET/v1/aml/health

AML engine status

🔑 X-API-Keybehind a flag

Scoring version, the sync deadline and per-network coverage (which networks can be scored synchronously).

Errors

401	Unauthorized	Missing or invalid X-API-Key header.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/v1/aml/health"

Response · 200 OK

{
  "ok": true,
  "deadlineMs": 60000,
  "scoringVersion": 50,
  "coverage": {
    "TRC20": {
      "sync": true,
      "keyed": true
    },
    "BEP20": {
      "sync": true,
      "keyed": true
    },
    "ETH": {
      "sync": true,
      "keyed": true
    },
    "TON": {
      "sync": true,
      "keyed": true,
      "requiresKeyForSync": true
    }
  }
}

Receipt check

POST/v1/receipts/check

PDF receipt forensics

🔑 X-API-Key10 tok.behind a flag

Accepts a PDF payment receipt / statement and returns an authenticity verdict: extracted fields, the forensic check set and findings. Personal data is returned only with include_pii=1.

Query parameters

include_pii

boolean

Return personal data from the receipt (names, cards, account).

Request body

multipart/form-data — multipart/form-data with a `file` part — or application/json with { fileBase64, fileName }. A raw application/pdf body is rejected (415).

Errors

400	bad_request	Invalid or missing parameters. The body carries a specific error code.
401	Unauthorized	Missing or invalid X-API-Key header.
402	insufficient_tokens	Not enough tokens for this call. See X-Tokens-Remaining header and the required field.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
503	busy / needs_async	Engine saturated or sync deadline exceeded. Retry per Retry-After. No tokens are charged.
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl -X POST \
  -H "X-API-Key: $DOLIX_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf \
  "https://api.dolix.io/v1/receipts/check"

Response · 200 OK

{
  "ok": true,
  "verdict": {
    "hasForgerySignals": true,
    "confidence": "высокий",
    "suspiciousCount": 2,
    "warningCount": 1,
    "definitiveCount": 1
  },
  "receipt": {
    "documentType": "transfer",
    "issuer": "Сбербанк",
    "operation": "Перевод",
    "status": "Выполнено",
    "amount": "45 000,00 ₽",
    "operationId": "1234567890",
    "paymentFingerprint": "a1b2c3"
  },
  "pdf": {
    "origin": "screenshot_to_pdf",
    "pages": 1,
    "hasSignature": false,
    "hasQr": false
  },
  "findings": [
    {
      "level": "high",
      "code": "font_mismatch",
      "message": "Шрифт суммы отличается от шаблона банка."
    }
  ],
  "checks": [
    {
      "code": "producer",
      "ok": false,
      "label": "Производитель PDF"
    }
  ],
  "analysisDegraded": false,
  "file": {
    "sizeBytes": 81234,
    "sha256": "9f2c..."
  }
}

GET/v1/receipts/health

Forensic toolchain status

🔑 X-API-Keybehind a flag

Availability of the forensic binaries on the host (qpdf, pdftotext, tesseract, magick, …) and a degraded flag.

Errors

401	Unauthorized	Missing or invalid X-API-Key header.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl \
  -H "X-API-Key: $DOLIX_API_KEY" \
  "https://api.dolix.io/v1/receipts/health"

Response · 200 OK

{
  "ok": true,
  "tools": {
    "qpdf": true,
    "pdftotext": true,
    "tesseract": true,
    "magick": true
  },
  "degraded": false
}

Blacklist

POST/v1/blacklist/report

Submit a blacklist report

🔑 X-API-Key5 tok.behind a flag

Enqueues a submission for moderation. Body = exactly one typed identifier (or value) + a mandatory review text. Idempotent via Idempotency-Key. Tokens are refunded if a moderator rejects it.

Request body

application/json — JSON with the subject and review text.

Fields

base	string	Counterparty platform.bybit · mexc · tg_wallet
uid \| card \| phone \| nick \| linkrequired	string	Exactly one typed subject identifier.
reviewrequired	string	Review text (required, goes through moderation).
idempotency_key	string	Idempotency key (also accepted as the Idempotency-Key header).

Errors

400	bad_request	Invalid or missing parameters. The body carries a specific error code.
401	Unauthorized	Missing or invalid X-API-Key header.
402	insufficient_tokens	Not enough tokens for this call. See X-Tokens-Remaining header and the required field.
403	forbidden	Key disabled, or the function is not permitted for this key / disabled by server policy.
404	Not found	Feature disabled by a server flag (the route is invisible until the operator enables it).
500	internal_error	Internal server error. The request did not complete; no tokens are charged.

Request · cURL

curl -X POST \
  -H "X-API-Key: $DOLIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base":"bybit","uid":"98765432","review":"Не отпустил средства после оплаты, динамил 3 часа."}' \
  "https://api.dolix.io/v1/blacklist/report"

Response · 200 OK

{
  "ok": true,
  "submission_id": "1042",
  "status": "pending",
  "idempotent": false
}