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
- Choose a plan or a package and pay for it on the site.
- Open your account. The key is issued right after payment and is shown once.
- 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.
| Value | Meaning | What to do |
|---|---|---|
| pass | no serious findings | let the transfer through |
| hold | there are findings that need a decision by your officer | hold the transfer and open the report |
| stop | a fact is established against the address: for example sanctions or an issuer freeze | stop the transfer |
| unverified | the check did not finish | repeat the request; do not treat the address as clean |
| Risk level | Trust score |
|---|---|
| low | 60–100 |
| medium | 40–59 |
| high | 15–39 |
| critical | 0–14 |
| unknown | null |
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.
| Plan | Requests per minute | Requests per hour |
|---|---|---|
| Developer | 30 | 500 |
| Business | 60 | 2 000 |
| Growth | 200 | 5 000 |
| Exchanger | 60 | 2 000 |
| Corporate | 300 | 10 000 |
| Corporate+ | 300 | 10 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.
| Plan | Price per month | Checks per month | Over the limit | |
|---|---|---|---|---|
| Developer | $149 | 1 000 | none | Buy |
| Business | $499 | 4 000 | none | Buy |
| Growth | $1 500 | 15 000 | $0.10 | Buy |
| Exchanger | $249 | 2 000 | none | Buy |
| Corporate | $6 900 | 100 000 | $0.045 | Buy |
| Corporate+ | $7 900 | 100 000 | $0.045 | Buy |
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.
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