API · version 1

Crypto wallet screening API

One request screens a wallet address and returns a trust score, a risk level, a decision on the transfer and the factors found, with evidence. The response has the same structure for all thirteen networks.

Quick start

  1. Choose a plan or a package and pay for it on the site.
  2. Open your account. The key is issued right after payment and is shown once.
  3. Send your first request from your server.
curl -X POST https://guardpay.online/api/v1/screen \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c2a9e-…" \
  -d '{"address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}'

Authentication

Send the key in the X-Api-Key header or as Authorization: Bearer. Keep it on your server only: never put it in a browser or a mobile app. In your account you can set the list of IP addresses the key is accepted from.

Screen an address

POST /api/v1/screen

One request screens one address. The network is detected from the address format. Each completed check takes one check from your quota.

Request parameters

address
string, required. The wallet address.
includeExplanation
boolean, default true. false returns the response without the text explanation.

Example response

Some fields in the example are shortened.

{
  "api_version": "v1",
  "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "network": "tron",
  "mode": "live",
  "branding": { "line": "AML Screening by GuardPay", "provided_by": null },
  "score": 92,
  "risk": "low",
  "decision": "pass",
  "decision_reason": "no_serious_findings",
  "sanctioned": false,
  "direct_sanctions_hit": false,
  "critical_risk_flag": false,
  "label": null,
  "exchange": null,
  "on_chain": { … },
  "forensics": { … },
  "intel": { … },
  "factors": [ … ],
  "explanation": "…",
  "explanation_withheld": false,
  "sanctions_links": { … },
  "freeze_forecast": { "status": "not_in_plan" },
  "report_url": "https://guardpay.online/check?address=TR7NHq…",
  "verify_url": "https://guardpay.online/verify",
  "coverage": { … },
  "checked_at": "2026-11-19T18:04:11Z",
  "duration_ms": 8420
}

Response fields

address
the address that was screened
network
address network: tron, evm, btc, ltc, doge, xrp, ton, sol, dash, zec, btg, bch, xmr
mode
test for a test key, live for production
branding.line
the line you show your customer next to the result; it always starts with our name
score
reliability score from 0 to 100: higher is safer; 100 means nothing was found against the address, 0 means an established fact against it; null when the check did not finish
risk
risk level by score: low 60–100, medium 40–59, high 15–39, critical 0–14; unknown means the check did not finish, which is not “clean”
decision
recommendation: pass, hold, stop, or unverified when the check did not finish; repeat the request
decision_reason
decision reason code: a short key for your rules and logs
direct_sanctions_hit
the address is listed directly on a sanctions list
critical_risk_flag
true when a critical factor is found: for example sanctions, a mixer, fraud or an issuer freeze
sanctioned
same value as critical_risk_flag; kept for compatibility. A direct list match is shown by direct_sanctions_hit
label
the known name of the address when it is established; otherwise null
exchange
the exchange the address belongs to when it is identified; otherwise null
on_chain
on-chain facts: address age, number of transactions, balance, date of the first transaction
forensics
counterparty summary: how many of them have findings at the first and the second hop, large outgoing transfers
intel
the number of findings about the address and their main category
factors
the factors found. Each has: key (code), severity, label (name) and evidence: addresses, transaction hashes, dates, amounts
explanation
the result explained in plain words
explanation_withheld
true when the explanation text is not returned for this check; the score and the decision do not depend on the text
sanctions_links
links to addresses on sanctions lists through a shared intermediary: amounts, dates, transaction hashes, the list and the designation date. This is an analytical link, not a listing of the address itself
freeze_forecast
forecast of a USDT freeze by the issuer. Included in packages with this tool; on other plans it returns status: not_in_plan
report_url
link to the full report on the site
verify_url
the page where a PDF report is verified as authentic
coverage
which parts of the check were completed for this address
checked_at
check time in UTC
duration_ms
check duration in milliseconds

Long-running checks

Most checks return in the same request. If a check takes longer than 25 seconds, the API answers 202 and returns a job id. The check keeps running; do not send the address again.

HTTP/1.1 202 Accepted
Retry-After: 10

{
  "api_version": "v1",
  "status": "processing",
  "job_id": "3b1f0c52-6a4e-4d0b-9a1e-2f7c8d5e4a10",
  "poll": "/api/v1/screen?job=3b1f0c52-6a4e-4d0b-9a1e-2f7c8d5e4a10",
  "retry_after_seconds": 10
}

Request the result at the address from the poll field with the same key, no more often than once every 10 seconds. While the check is running you get 202. The finished result is the normal screening response. The result is kept for one hour.

curl "https://guardpay.online/api/v1/screen?job=3b1f0c52-6a4e-4d0b-9a1e-2f7c8d5e4a10" \
  -H "X-Api-Key: YOUR_API_KEY"

Several addresses at once

Send the addresses field instead of address: a list of 1 to 50 addresses. Each address is screened as a separate check and takes one check from your quota. Addresses that were not checked are not charged. An address repeated in the list is checked and charged once.

curl -X POST https://guardpay.online/api/v1/screen \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "abc"]}'

The results field keeps the order of your list. A screened address gets the usual screening response with status 200. Any other row has address, status and error, as in the Errors section.

Example response

{
  "api_version": "v1",
  "status": "completed",
  "count": 3,
  "checked": 2,
  "results": [
    { "status": 200, "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "score": 92, "risk": "low", "decision": "pass", … },
    { "status": 200, "address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "score": 34, "risk": "high", "decision": "hold", … },
    { "address": "abc", "status": 400, "error": "invalid_address" }
  ],
  "usage": { "monthly_quota": 2000, "monthly_used": 214 },
  "duration_ms": 14210
}

If the batch takes longer than 25 seconds, the API answers 202 with a job id, as in Long-running checks. While it runs, the answer shows count and done. A row with error not_started was not checked within the time limit and was not charged: send that address again.

Toward the per-minute limit a batch counts as one request; toward the per-hour limit every address in it counts.

Safe retries

Add the Idempotency-Key header with your own unique value. Repeating the request with the same key and the same body within 24 hours returns the stored response with the header Idempotent-Replayed: true and does not take a check. The same key with a different body gets 422.

Decision and risk

The risk field says what is established about the address. The decision field says what to do with the transfer. Build your logic on decision.

ValueMeaningWhat to do
passno serious findingslet the transfer through
holdthere are findings that need a decision by your officerhold the transfer and open the report
stopa fact is established against the address: for example sanctions or an issuer freezestop the transfer
unverifiedthe check did not finishrepeat the request; do not treat the address as clean
Risk levelTrust score
low60–100
medium40–59
high15–39
critical0–14
unknownnull

The trust score runs from 0 to 100: the higher, the safer. The unknown level comes with a null score: the check did not finish, and the address must not be treated as clean.

Errors

An error comes with an HTTP status and an error field. A check is taken only on a successful response.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "rate_limit_exceeded", "retry_after_seconds": 12 }
400 invalid_address
address not recognised; not charged
400 invalid_batch
addresses is not a list of 1 to 50 addresses; not charged
400 invalid_job · 404 job_not_found
the job id is not recognised or does not belong to your key
401 api_key_required · invalid_api_key
key missing or wrong
403 network_disabled
network switched off; not charged
403 ip_not_allowed
request from an IP not on the allow list
403 not_in_plan
the tool is not included in your plan
422 idempotency_key_reused_different_payload
same Idempotency-Key with a different request body
429 rate_limit_exceeded
too frequent; wait for Retry-After
429 monthly_quota_exhausted
the period quota is used up
502 pipeline_unavailable
failure on our side; the check is not charged

Limits

Quota and remainder come in the X-Monthly-Quota, X-Monthly-Used and X-Monthly-Remaining headers. Requests sent too often get 429 with a Retry-After header.

A 429 response carries retry_after_seconds: repeat the request after that many seconds.

PlanRequests per minuteRequests per hour
Developer30500
Business602 000
Growth2005 000
Exchanger602 000
Corporate30010 000
Corporate+30010 000

Networks

The network field returns one of thirteen networks. evm covers Ethereum and compatible networks. Networks are switched on and off in your account; a request for a switched-off network gets 403 and takes no check.

tronevmbtcltcdogexrptonsoldashzecbtgbchxmr

Package tools

The tools below are included in the Exchanger, Corporate and Corporate+ packages. They work both through the API and in your account on the site.

USDT freeze forecast

An estimate of how closely the address resembles wallets the issuer later froze. It comes in the screening response, in the freeze_forecast field: a level and the signals behind it. TRON only. It is an estimate, not a guarantee.

Included: Exchanger, Corporate, Corporate+.

The full description of requests and fields is available in your account after payment.

Address monitoring

You add TRON addresses to monitoring and give the URL of your server. We send a notification to your server when a new event appears for an address: it is added to a sanctions list, gets a new risk label, receives funds from a mixer or a sanctioned address, or is frozen by the issuer.

Included: Exchanger — up to 500 addresses, Corporate — up to 5,000, Corporate+ — up to 10,000.

The full description of requests and fields is available in your account after payment.

Connection graph

For a TRON address the API builds a graph of its counterparties: nodes are addresses, edges are transfers between them, up to 4 hops from the address. The request creates a job, and the result is fetched by the job id. One graph takes one check.

Included: Corporate and Corporate+. A graph deeper than 4 hops — in Corporate+ on request.

The full description of requests and fields is available in your account after payment.

Notifications to your server

Instead of polling the API you can receive events on your server: a check is completed, a check ended with a hold or stop decision, an event on a monitored address. Every notification is signed so that your server can confirm it was sent by us. You set the server URL for monitoring events yourself when you add an address. Notifications about checks are connected by email to compliance@guardpay.online.

The full description of requests and fields is available in your account after payment.

PDF reports

A full PDF report on the address for your records and for your customer. Each page carries a mark by which the report is verified as authentic on the page from the verify_url field.

Included: Corporate and Corporate+.

Brand line

The branding.line field holds the line you show your customer next to the screening result. The line always starts with our name. Your company name is set in your account and is added to this line.

Plans and packages

Payment is made on the site, monthly.

PlanPrice per monthChecks per monthOver the limit
Developer$1491 000noneBuy
Business$4994 000noneBuy
Growth$1 50015 000$0.10Buy
Exchanger$2492 000noneBuy
Corporate$6 900100 000$0.045Buy
Corporate+$7 900100 000$0.045Buy

What is included

Developer · Business · Growth
address screening
Exchanger
screening, freeze forecast, monitoring up to 500 addresses
Corporate
screening, freeze forecast, monitoring up to 5,000 addresses, graph, PDF
Corporate+
everything in Corporate, monitoring up to 10,000 addresses

Packages can first be tried in a free pilot: the terms are on the For Business page.

Choose a plan

Docs in your account

After payment your account opens the extended documentation: exact request and response schemas for the connection graph, monitoring events and their fields, notification signature verification and key settings.

Integration questions: compliance@guardpay.online