# 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
    }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wardanalytics.gitbook.io/ward-analytics-spellbook/queries/risk-analytics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.