---
title: "Screen a counterparty wallet address before transacting with it"
method: POST
path: "/v1/metered/wallet-risk"
tags: ["Crypto"]
---

# Screen a counterparty wallet address before transacting with it

`POST /v1/metered/wallet-risk`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/wallet-risk`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Screens a wallet address across EVM, Solana, TON and Bitcoin for known scam, drainer, phishing, dark web and sanctions associations, and returns a risk level with the specific flags behind it. The chain is detected from the address format, so no chain parameter is needed.

This is the key-authenticated twin of `/v1/payg/wallet-risk`, added for callers who hold an API key rather than paying per call over x402. Same handler, same price, same response.

Read `degraded` before you read `risk_flags`. When `degraded` is true an upstream source did not answer, so an empty flag list means the check did not complete rather than that the address is clean. Treat that as no verdict, never as a pass.

**Billing.** $0.05 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

## Request body

- object
  - `address` string, required: Wallet address to screen. EVM (0x...), Solana, TON (EQ.../UQ...) or Bitcoin. The chain is inferred from the format.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `observed_at` string, date-time: When this verdict was observed. Cache keyed on this, not on receipt time.
    - `valid_for_seconds` integer: How long this verdict can be cached before it should be re-checked. Flagged results live 24 hours; clean results live 1 hour, because a hit stays a hit while a clean answer is the one that flips without telling whoever cached it. A degraded result lives 5 minutes. This is a caching hint and a policy default, not a measurement and not a safety guarantee: how fast a verdict really goes stale is bounded by upstream detection latency, which we do not control.
    - `expires_at` string, date-time: observed_at plus valid_for_seconds, precomputed.
    - `degraded` boolean: True when this answer was assembled from incomplete or failed upstream data. Treat it as NO VERDICT, never as clean. An outage that returns an empty finding list is otherwise indistinguishable from a real all-clear, and it fails in the permissive direction.
    - `address` string: The address that was screened, lowercased for EVM.
    - `chain` string: Detected chain: `evm`, `solana`, `ton` or `bitcoin`.
    - `risk_level` string: `HIGH`, `MEDIUM` or `LOW`. LOW with an empty `risk_flags` means nothing known, not a guarantee of safety. Two or more flags give HIGH, one flag gives MEDIUM, with one exception: `sanctions-listed` gives HIGH on its own, because a sanctions match is a compliance event whether or not anything else is known about the address.
    - `risk_flags` string[]: Specific findings. Empty when nothing is known about the address.
    - `metadata` object: Chain-specific detail. Bitcoin returns balance and transaction counts; TON returns contract type and account status. Any key ending in `_error` means that source failed, which is also what sets `degraded`.

## Other responses

- `400`: `address` is missing, or the format matches no supported chain.
- `401`: Missing or invalid API key.
- `402`: No credit balance and no active subscription.
- `405`: Wrong HTTP method. Every endpoint is POST.

---

[API](https://skmtc.dev/relayshield/apis/relayshield-api.md) · [All operations](https://skmtc.dev/relayshield/apis/relayshield-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relayshield/apis/relayshield-api/revisions/4d4721b936dd?raw)