Analysis

Analyze blockchain wallet addresses for risk scoring, transaction patterns, and compliance data.

All endpoints in this section are accessible with an API key.

---

Analyze Wallet

Submits a wallet address for analysis. The analysis runs asynchronously — you'll receive a jobId to track progress.

GET /api/analysis/{wallet}

Rate limit: 3 requests/minute

Path parameters:

Parameter	Type	Description
wallet	string	Blockchain wallet address (EVM 0x... or TRON T...)

Query parameters:

Parameter	Type	Default	Description
depth	integer	1	Analysis depth (1-5)
minAmountUsd	number	—	Minimum transaction amount in USD to include
network	string	ethereum	Single network to analyze
networks	string	—	Comma-separated list of networks (overrides network)

Supported networks: ethereum, polygon, bnb, arbitrum, base, tron

Optional headers:

Header	Description
Idempotency-Key	Opaque string. Replays with the same key return the original jobId without re-charging. See Idempotency.

Example:

curl -H "X-API-Key: ak_live_your_key_here" \
  -H "Idempotency-Key: 7b4d8e2c-1a3f-4f1e-9b6a-5d0e8c2a7b91" \
  "https://mvp.amlyou.com/api/analysis/0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18?networks=ethereum,polygon&depth=2"

Response 202 Accepted:

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued"
}

When a retry hits an existing Idempotency-Key, the response is 200 OK with the original jobId and "status": "duplicate" — no new work is enqueued and no tokens are frozen.

Use the returned jobId to poll for results via Get Job Status.

---

Get Job Status

Check the status of an analysis job. Poll this endpoint until the status is completed or failed.

GET /api/analysis/jobs/{jobID}

Rate limit: 12 requests/minute

Path parameters:

Parameter	Type	Description
jobID	UUID	The job ID returned by the analyze endpoint

Example:

curl -H "X-API-Key: ak_live_your_key_here" \
  https://mvp.amlyou.com/api/analysis/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response 200 OK (pending):

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending"
}

Response 200 OK (completed):

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "reportId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
}

Job statuses: pending, processing, completed, failed

---

Check Address Analyzed

Check whether a wallet address has already been analyzed on given networks, and the cost of running a new analysis.

GET /api/analysis/check/{wallet}

Rate limit: 12 requests/minute

Path parameters:

Parameter	Type	Description
wallet	string	Blockchain wallet address

Query parameters:

Parameter	Type	Default	Description
network	string	ethereum	Single network to check
networks	string	—	Comma-separated list of networks

Example:

curl -H "X-API-Key: ak_live_your_key_here" \
  "https://mvp.amlyou.com/api/analysis/check/0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18?networks=ethereum,polygon"

Response 200 OK:

{
  "networks": {
    "ethereum": {
      "analyzed": true,
      "cost": 10
    },
    "polygon": {
      "analyzed": false,
      "cost": 5
    }
  },
  "totalCost": 15
}

tip

Use this endpoint before submitting an analysis to check the cost upfront. Previously analyzed addresses cost more to update (10 credits) than new analyses (5 credits).

---

Get Aggregated Report

Returns an aggregated report combining results from multiple networks for a single wallet address.

GET /api/analysis/aggregated/{wallet}

Rate limit: 12 requests/minute

Path parameters:

Parameter	Type	Description
wallet	string	Blockchain wallet address

Query parameters:

Parameter	Type	Required	Description
networks	string	Yes	Comma-separated list of networks

Example:

curl -H "X-API-Key: ak_live_your_key_here" \
  "https://mvp.amlyou.com/api/analysis/aggregated/0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18?networks=ethereum,polygon"

Response 200 OK:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "overallRiskScore": 25,
  "networks": {
    "ethereum": {
      "riskScore": 20,
      "analyzed": true
    },
    "polygon": {
      "riskScore": 30,
      "analyzed": true
    }
  }
}

note

All requested networks must have been analyzed beforehand. Use Analyze Wallet first if needed.

---

Billing

Each analysis request consumes tokens from your account balance. The billing flow:

1. Freeze — Tokens are reserved before analysis begins
2. Spend — Reserved tokens are consumed on success
3. Unfreeze — Reserved tokens are returned if analysis fails

If you have insufficient balance, the API returns:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient token balance to perform this analysis. Please top up your account."
  }
}

Error Responses

Status	Code	Description
400	invalid_address	The wallet address format is invalid
402	insufficient_balance	Not enough tokens to perform analysis
404	address_not_found	No data found for this address
429	rate_limit_exceeded	Too many requests (see Rate Limits)
500	analysis_failed	Internal error during analysis