> For the complete documentation index, see [llms.txt](https://wardanalytics.gitbook.io/ward-analytics-spellbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wardanalytics.gitbook.io/ward-analytics-spellbook/queries/risk-analytics.md).

# Risk Analytics

## Risk Queries Introduction

These queries allow you to check whether or not addresses display suspicious behavior with very simple inputs and outputs.

### :magic\_wand: Spell Index

Inspect the function name to learn more about how to use each spell!

## Evaluate Wallet Risk Score

<mark style="color:blue;">`GET`</mark> `/compliance/analyze-address`

Evaluates the risk score of a wallet and specific compliance-related aspects used in this calculation. Also returns in-depth explanations regarding the **source of funds**, **destination of funds**, **contract analysis** (if applicable), and **known labels** for the address.

#### Query Parameters

| Name                                      | Type   | Description        |
| ----------------------------------------- | ------ | ------------------ |
| address<mark style="color:red;">\*</mark> | String | The wallet address |

#### Headers

| Name                                  | Type   | Description  |
| ------------------------------------- | ------ | ------------ |
| api<mark style="color:red;">\*</mark> | String | Your API key |

{% tabs %}
{% tab title="200: OK Wizardry!" %}
{% code title="Example Python Input" lineNumbers="true" %}

```python
requests.get("https://wardanalyticsapi.com/compliance/analyze-address",
        headers = {
            "api": "YOUR_API_KEY"
        }, 
        params = {
            "address": "115GnsdVzGYDGQMeTeMxWUJZySfJ4pgiPT"
        })
```

{% endcode %}

{% code title="Example Output" %}

```json
{
    "address": "0x026713f746e4860f48a8ab2a6020cb2d27ef74f7", // Address requested
    "blockchain": "Ethereum", // Blockchain this address belongs to
    "risk": 3, // Risk level of this address
    "labels": ["Binance", "Exchange"], // Labels assigned to this address
    "timestampScanned": 1699290272, // The last time this address was scanned (UNIX)
    
    "directOutgoingExposure": { // The destination of funds of the address
        "categories": [ // List of categories of entities (Example: "Exchange")
            {
                "entities": [ // List of entites (Example: "Binance")
                    {
                        "addresses": [ // List of addresses of the entity
                            {
                                "hash": "0xeef5105f7c9009d371d6938b310bb849a25c5260",
                                "quantity": 54318.283074567895 // Total funds sent to this address
                            }
                        ],
                        "name": "Individual Wallet",
                        "quantity": 54318.283074567895 // Total funds sent to this entity
                    }
                ],
                "name": "Individual Wallet",
                "total": 54318.283074567895 // Total funds sent to this category
            }
        ],
        "total": 54318.283074567895 // Total funds sent to all categories
    }
    
    // The source of funds of the address
    "directIncomingExposure": {
        "categories": [
            {
                "entities": [
                    {
                        "addresses": [
                            {
                                "hash": "0xc94ebb328ac25b95db0e0aa968371885fa516215",
                                "quantity": 33384.567099151485
                            }
                        ],
                        "name": "Individual Wallet",
                        "quantity": 33384.567099151485
                    }
                ],
                "name": "Individual Wallet",
                "total": 33384.567099151485
            },
            {
                "entities": [
                    {
                        "addresses": [
                            {
                                "hash": "0x267be1c1d684f78cb4f6a176c4911b741e4ffdc0",
                                "quantity": 21321.89737103285
                            }
                        ],
                        "name": "Kraken",
                        "quantity": 21321.89737103285
                    }
                ],
                "name": "Exchange",
                "total": 21321.89737103285
            }
        ],
        "total": 54706.464470184335
    }: { // The destination of funds of the address
        "categories": [ // List of categories of entities (Example: "Exchange")
            {
                "entities": [ // List of entites (Example: "Binance")
                    {
                        "addresses": [ // List of addresses of the entity
                            {
                                "hash": "0xeef5105f7c9009d371d6938b310bb849a25c5260",
                                "quantity": 54318.283074567895 // Total funds sent to this address
                            }
                        ],
                        "name": "Individual Wallet",
                        "quantity": 54318.283074567895 // Total funds sent to this entity
                    }
                ],
                "name": "Individual Wallet",
                "total": 54318.283074567895 // Total funds sent to this category
            }
        ],
        "total": 54318.283074567895 // Total funds sent to all categories
    },
    
    // If empty, these will appear like this. Else, they'll look like the other two fields
    "indirectIncomingExposure": {},
    "indirectOutgoingExposure": {}
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Poorly Cast Spell" %}

{% endtab %}

{% tab title="401: Unauthorized Forbidden Magic (check your API key)" %}

{% endtab %}

{% tab title="429: Too Many Requests Mana Overflow" %}

{% endtab %}

{% tab title="404: Not Found Ancient Knowledge (address has no recent activity)" %}

{% endtab %}
{% endtabs %}

### Primary Fields

Detailed information on primary fields of `/compliance/analyze-address`

<table><thead><tr><th width="302">Key</th><th>Explanation</th></tr></thead><tbody><tr><td><strong>address</strong> <mark style="color:green;">string</mark></td><td>The address that is being analyzed</td></tr><tr><td><strong>blockchain</strong> <mark style="color:green;">string</mark></td><td>The blockchain on which the address was found</td></tr><tr><td><strong>risk</strong> <mark style="color:blue;">float</mark></td><td>The risk level of the address (goes from 0 to 10)</td></tr><tr><td><strong>labels</strong> <mark style="color:green;">list[string]</mark></td><td>The list of known labels for this address</td></tr><tr><td><strong>timestampScanned</strong> <mark style="color:blue;">int</mark></td><td>The timestamp at which the address was last scanned</td></tr><tr><td><strong>incomingDirectExposure</strong> <mark style="color:yellow;">field</mark></td><td>Direct analysis of incoming funds (1 hop)</td></tr><tr><td><strong>incomingIndirectExposure</strong> <mark style="color:yellow;">field</mark></td><td>Indirect analysis of incoming funds (2+ hops)</td></tr><tr><td><strong>outgoingDirectExposure</strong> <mark style="color:yellow;">field</mark></td><td>Direct analysis of outgoing funds (1 hop)</td></tr><tr><td><strong>outgoingIndirectExposure</strong> <mark style="color:yellow;">field</mark></td><td>Indirect analysis of outgoing funds (2+ hops)</td></tr></tbody></table>

{% hint style="warning" %}
Currently, <mark style="color:yellow;">**Bitcoin**</mark> queries do not support indirect exposure and will always appear as empty dictionaries. This will be improved in a future update.
{% endhint %}

### Source / Destination Fields

These fields are highly nested, so an example is easier to understand:

```json
"directOutgoingExposure": { // The destination of funds of the address
        "categories": [ // List of categories of entities (Example: "Exchange")
            {
                "entities": [ // List of entites (Example: "Binance")
                    {
                        "addresses": [ // List of addresses of the entity
                            {
                                "hash": "0xeef5105f7c9009d371d6938b310bb849a25c5260",
                                "quantity": 54318.283074567895 // Total funds sent to this address
                            }
                        ],
                        "name": "Individual Wallet",
                        "quantity": 54318.283074567895 // Total funds sent to this entity
                    }
                ],
                "name": "Individual Wallet",
                "total": 54318.283074567895 // Total funds sent to this category
            }
        ],
        "total": 54318.283074567895 // Total funds sent to all categories
    }
    
    // The source of funds of the address
    "source": {
        "categories": [
            {
                "entities": [
                    {
                        "addresses": [
                            {
                                "hash": "0xc94ebb328ac25b95db0e0aa968371885fa516215",
                                "quantity": 33384.567099151485
                            }
                        ],
                        "name": "Individual Wallet",
                        "quantity": 33384.567099151485
                    }
                ],
                "name": "Individual Wallet",
                "total": 33384.567099151485
            },
            {
                "entities": [
                    {
                        "addresses": [
                            {
                                "hash": "0x267be1c1d684f78cb4f6a176c4911b741e4ffdc0",
                                "quantity": 21321.89737103285
                            }
                        ],
                        "name": "Kraken",
                        "quantity": 21321.89737103285
                    }
                ],
                "name": "Exchange",
                "total": 21321.89737103285
            }
        ],
        "total": 54706.464470184335
    }
```