Risk Address APIRisk Address API 接口文档

This document explains how to query address risk information through the API. Two access methods are supported: 本文档面向 API 调用者，用于说明如何查询地址风险信息。接口支持两种访问方式：

• Direct access with an API Key使用 API Key 直接访问
• One-time paid access through x402 without an API Key不使用 API Key，通过 x402 完成单次付费访问

1. Base Information1. 基础信息

Production API base URL:生产环境 API 地址：

https://api.blockjust.com

Risk address lookup endpoint:风险地址查询接口：

POST /v1/address/risk-check

Full URL:完整地址：

POST https://api.blockjust.com/v1/address/risk-check

Request content type:请求格式：

Content-Type: application/json

2. Request Parameters2. 请求参数

Request body:请求体：

{
  "chain_id": "<chain_id>",
  "address": "<evm_address>"
}

Fields:字段说明：

Common supported chain identifiers:当前支持的常用链标识：

3. Access Method 1: API Key3. 方式一：API Key 访问

If you have an API Key, include it in the request header:如果你已经获得 API Key，可以在请求头中携带：

x-api-key: <api_key>

Example:示例：

curl -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <api_key>" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'

If the API Key is valid and has not exceeded its limits, the API returns the query result directly.如果 API Key 有效且未超过调用限制，接口会直接返回查询结果。

If the API Key is invalid, missing, or the caller chooses one-time paid access, the request enters the x402 flow.如果 API Key 无效、未携带 API Key，或者调用方选择单次付费访问，则会进入 x402 访问流程。

4. Access Method 2: x402 Paid Access4. 方式二：x402 付费访问

4.1 Flow4.1 调用流程

The x402 access flow is:x402 访问流程如下：

1. The caller sends a risk-check request without x-api-key.
2. The server pre-checks whether the query can be completed.
3. If the pre-check succeeds, the server returns 402 Payment Required.
4. The caller uses the x402 payment requirement from the 402 response to complete payment authorization.
5. The caller sends the same request again with the generated PAYMENT credential.
6. The server verifies the PAYMENT credential.
7. If verification succeeds, the server returns the final risk result.1. 调用方不携带 x-api-key，请求风险查询接口
2. 服务端先检查该查询是否可以正常完成
3. 如果查询预检成功，服务端返回 402 Payment Required
4. 调用方根据 402 响应中的 x402 payment requirement 完成付款签名/授权
5. 调用方使用生成的 PAYMENT 凭证，再次请求同一个接口
6. 服务端验证付款凭证
7. 验证通过后返回最终风险查询结果

Note: The server performs a query pre-check before returning a payment request. If the risk query is temporarily unavailable, the API returns an error directly and does not ask the caller to pay first.注意：服务端会在返回付款请求前先执行查询预检。如果风险查询服务暂时不可用，接口会直接返回错误，不会要求调用方先付款。

4.2 First Request: Without API Key4.2 第一次请求：不携带 API Key

Example:示例：

curl -i -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'

If the pre-check succeeds, the response is:如果预检成功，返回：

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
PAYMENT-REQUIRED: <encoded_x402_payment_requirement>

{}

Response structure:响应结构：

PAYMENT-REQUIRED: <encoded x402 payment requirement>

{}

The payment requirement represented by PAYMENT-REQUIRED has the following structure:PAYMENT-REQUIRED 对应的付款要求结构如下：

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "<resource_url>",
    "description": "<resource_description>",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "<network>",
      "amount": "<amount>",
      "asset": "<asset_contract_address>",
      "payTo": "<receiver_address>",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "<asset_name>",
        "version": "<asset_version>"
      }
    }
  ]
}

Fields:说明：

The caller should read the PAYMENT-REQUIRED response header and pass it to an x402-compatible client, SDK, or Agent wallet.调用方应读取 PAYMENT-REQUIRED 响应头，并交给支持 x402 的客户端、SDK 或 Agent 钱包处理。

4.3 Generate the PAYMENT Credential4.3 生成 PAYMENT 凭证

The caller must use an x402-compatible client, SDK, or Agent wallet to complete payment authorization based on the PAYMENT-REQUIRED response header.调用方需要使用支持 x402 的客户端、SDK 或 Agent 钱包，根据 PAYMENT-REQUIRED 响应头完成付款授权。

The generated credential must be included in the request header:生成后的凭证需要放在请求头：

PAYMENT: <x402 payment payload>

PAYMENT is usually an encoded string generated by the x402 client. Callers should not construct it manually.PAYMENT 通常是由 x402 客户端生成的编码字符串，调用方不应该手动拼接。

Example format:示例形式：

PAYMENT: <encoded_x402_payment_payload>

4.4 Second Request: With PAYMENT Credential4.4 第二次请求：携带 PAYMENT 凭证

The caller must send the same endpoint and request body as the first request, with the additional PAYMENT header.同调用方需要使用和第一次完全相的接口与请求体，并额外携带 PAYMENT 请求头。

Example:示例：

curl -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -H "PAYMENT: <x402 payment payload>" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'

If payment verification succeeds, the API returns 200 OK and the final risk result.如果付款验证通过，接口返回 200 OK 和最终风险查询结果。

The successful response may include a PAYMENT-RESPONSE response header. If present, it can be saved as payment settlement or receipt-related information.成功响应中可能包含 PAYMENT-RESPONSE 响应头。若存在，该字段可作为 x402 付款结算响应或收据相关信息，调用方可以按需保存。

5. Successful Response5. 成功响应

The successful response structure is the same for both API Key access and x402 access.无论使用 API Key 访问还是 x402 访问，成功后返回结构一致。

Example: risk tags matched示例：命中风险标签

{
  "request_id": "<request_id>",
  "address": "<evm_address>",
  "chain_id": "<chain_id>",
  "risk_level": "<risk_level>",
  "risk_reasons": [
    {
      "tag_type": "<risk_tag_type>",
      "tag_name": "<risk_tag_name>"
    },
    {
      "tag_type": "<risk_tag_type>",
      "tag_name": "<risk_tag_name>"
    }
  ],
  "access_mode": "<access_mode>"
}

Example: no risk tags matched示例：未命中风险标签

{
  "request_id": "<request_id>",
  "address": "<evm_address>",
  "chain_id": "<chain_id>",
  "risk_level": "<risk_level>",
  "risk_reasons": [],
  "access_mode": "<access_mode>"
}

Fields:字段说明：

Risk levels:风险等级：

Risk reason fields:风险原因字段：

6. Error Response6. 错误响应

Error response structure:错误响应结构：

{
  "request_id": "<request_id>",
  "error": "<error_code>",
  "message": "<error_message>"
}

Common errors:常见错误码：

7. API Key Limits7. API Key 调用限制

An API Key may have the following limits:API Key 可能配置以下限制：

If a limit is exceeded, the API returns 429 or 403.如果超过限制，接口会返回 429 或 403。

8. Integration Notes8. 调用建议

1. API Key users should use the x-api-key request header.API Key 用户建议长期使用 x-api-key 请求头。
2. x402 users should use an x402-compatible client or Agent to handle the payment flow automatically.x402 用户应使用支持 x402 的客户端或 Agent 自动处理付款流程。
3. After receiving 402 Payment Required, do not repeatedly send invalid PAYMENT requests. Complete payment authorization based on the payment requirement.收到 402 Payment Required 后，不要反复构造无效 PAYMENT 请求，应根据响应中的 payment requirement 完成真实付款授权。
4. When retrying with PAYMENT, keep the method, URL, and request body the same as the first request.第二次携带 PAYMENT 重试时，请保持请求方法、URL 和请求体一致。
5. Save request_id for troubleshooting.建议保存 request_id，便于排查异常。
6. If 502 RISK_QUERY_ERROR is returned, the query is temporarily unavailable. No payment is required; retry later.若返回 502 RISK_QUERY_ERROR，表示当前查询暂时不可用，调用方不需要付款，稍后重试即可。

9. Full Examples9. 完整调用示例

API Key ModeAPI Key 模式

curl -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <api_key>" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'

x402 Modex402 模式

First request:第一次请求：

curl -i -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'

After receiving 402 Payment Required, use an x402 client to generate the PAYMENT credential.收到 402 Payment Required 后，使用 x402 客户端生成 PAYMENT 凭证。

Second request:第二次请求：

curl -X POST "https://api.blockjust.com/v1/address/risk-check" \
  -H "Content-Type: application/json" \
  -H "PAYMENT: <x402 payment payload>" \
  -d '{
    "chain_id": "<chain_id>",
    "address": "<evm_address>"
  }'