From request
to report.

Start in Sandbox

1. Open your company workspace and choose Sandbox.
2. In Developers, create a key with “Read and create checks”. Save the secret when it appears.
3. Send the request below, then retrieve its check ID until the result is ready.

Live requires a separately provisioned organization balance and price. A Live key cannot access Sandbox checks, and personal API keys do not work on these endpoints.

Base URL

https://app.chainysoft.io/api/external/v1/organization

Authentication

X-API-Key: YOUR_ORGANIZATION_KEY

Networks

eth · Ethereum, bsc · BNB Smart Chain, trx · TRON

Create a wallet check

Generate one request ID for each intended check. Persist that ID and the request body before sending. The server returns 202 after saving the job; screening runs asynchronously.

curl https://app.chainysoft.io/api/external/v1/organization/checks \
  -H 'X-API-Key: YOUR_ORGANIZATION_KEY' \
  -H 'Idempotency-Key: wallet-request-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "0x0000000000000000000000000000000000000001",
    "network": "eth",
    "external_reference": "your-customer-reference"
  }'

The address is an input example, not a recommendation or a verified screening result.

The key determines the organization and environment. Do not send an organization override.

{
  "status": true,
  "data": {
    "check": {
      "id": "<check UUID>",
      "environment": "sandbox",
      "state": "queued",
      "settlement": "none",
      "price_cents": 0,
      "currency": "USD"
    },
    "replayed": false
  }
}

Response excerpt. The full check also includes address, network, reference, timestamps and organization ID.

Read the result

curl https://app.chainysoft.io/api/external/v1/organization/checks/CHECK_ID \
  -H 'X-API-Key: YOUR_ORGANIZATION_KEY'

The response is {"status":true,"data":{…check}}. While the check is queued or processing, poll with a delay and backoff. A completed report contains risk_score on a 0–100 scale, risk_level, risks, sandbox, and coverage.

The score describes risk; it is not an automatic approval or rejection of a payment. This endpoint provides wallet screening. It does not include transaction tracing, a graph, or organization risk-rule evaluation.

List checks in the key’s environment. Optional parameters: limit (1–100, default 25), state, q (address or external reference), and cursor.

{
  "status": true,
  "data": {
    "items": [],
    "next_cursor": null
  }
}

Pass next_cursor unchanged for the next page, preserving the same filters. Read-only keys can use both GET endpoints.

Retry without another charge

• Send the same Idempotency-Key and the same payload after a timeout or a lost response. The saved check is returned with replayed: true.
• The request ID is shared across the organization’s keys within an environment. Rotating a key does not create a duplicate.
• Reusing an ID with a different payload returns 409. Sending a new ID creates a new check, even for the same wallet.
• An ID must contain 8–128 ASCII letters, digits, dots, underscores, colons or hyphens.

During the pilot, only enrolled organizations can create checks. A pause stops new submissions while authorized exact retries, result reads and accepted work remain available. A retry with a changed body still returns 409.

Live funds are reserved when a check is accepted. Completion captures the reservation once. A confirmed failure releases it. An uncertain provider outcome keeps the reservation for reconciliation and does not trigger another paid create.

Understand the status

Handle errors

{"status": false, "error": "Idempotency key payload mismatch",
 "code": "IDEMPOTENCY_CONFLICT"}

After an ambiguous network error or server failure, retry the original request ID. A response does not guarantee completion time; use the check state to track progress.