> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavynode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect your application with Wavy Node by setting up a single integration server with two routes to receive real-time compliance notifications and serve user data.

Integrations connect your application with Wavy Node. By creating an integration, you set up a single server that Wavy Node communicates with to receive real-time notifications about your users' on-chain activity and to retrieve the user data needed for compliance.

## How it works

Your integration is a **single server** that exposes **two routes** under the same base URL. When you configure the integration URL in the dashboard (e.g., `https://your-server.com`), Wavy Node calls both routes on that same server:

1. `GET {integrationUrl}/users/{foreign_user_id}` — Wavy Node requests user data from your system for compliance checks and report generation.
2. `POST {integrationUrl}/webhook` — Wavy Node sends you real-time alerts when suspicious activity is detected.

> [!WARNING]
>
> You only need **one server** and **one integration URL**. Do not create separate servers or separate URLs for each route — both routes live on the same server.

```mermaid theme={null}
sequenceDiagram
    participant You as Your App
    participant WN as Wavy Node
    participant BC as Blockchain

    You->>WN: 1. Register addresses with foreign_user_id
    WN->>BC: 2. Monitor on-chain activity
    BC-->>WN: Transaction detected
    WN-->>You: 3. POST /webhook (real-time alert)
    WN->>You: 4. GET /users/{foreign_user_id}
    You-->>WN: User data for compliance
    WN->>WN: 5. Generate compliance report
```

### Wallet-to-user matching

The match between wallets and users happens when you register addresses in our system. When you create an address via the API, you include the `foreign_user_id`, which is the user's ID in your system. This is how we know which user owns each wallet.

If a user has multiple wallets, register each wallet with the same `foreign_user_id`. We handle the linking automatically.

When we need user data (for example, to generate a compliance report), we call your integration endpoint `/users/{foreign_user_id}`. You must return the required user data for each legislation you have enabled in your project.

For example, if you have Mexican legislation active, all users must include the `mexico` field populated with the user's personal and fiscal information:

```json theme={null}
{
  "givenName": "Juan",
  "paternalSurname": "Pérez",
  "maternalSurname": "López",
  "nationality": "MX",
  "mexico": {
    "rfc": "PELJ900101XXX",
    "curp": "PELJ900101HDFRPN09",
    "actividadEconomica": 1234567,
    "documentoIdentificacion": {
      "tipoIdentificacion": 1,
      "numeroIdentificacion": "ABC123456"
    }
  }
}
```

See [Endpoints](https://docs.wavynode.com/integrations/endpoints.md) for the full response schema. The complete type definitions for each legislation are available in the `@wavynode/utils` package.

> [!WARNING]
>
> Your endpoint must return the required data for all active legislations in your project. Missing or empty fields will cause compliance report generation to fail.

| Active Legislation | Required Field | Content |
| - | - | - |
| Mexico (MX) | `mexico` | Personal data, RFC/CURP, address, ID document |
| Colombia (CO) | `colombia` | User data required by Colombian AML regulations |
| El Salvador (SV) | `elSalvador` | User data required by Salvadoran AML regulations |
| Guatemala (GT) | `guatemala` | User data required by Guatemalan AML regulations |

### Integration flow

**1. Register addresses for monitoring**

Use `POST /projects/{projectId}/addresses` to add wallet addresses you want to monitor. Include the `foreign_user_id` parameter to link each wallet to a user in your system.

**2. Wavy Node monitors on-chain activity**

Wavy Node watches your registered addresses for suspicious transactions, regulatory violations, and interactions with blacklisted wallets.

**3. Wavy Node requests user data when needed**

When Wavy Node needs user information (e.g., to generate a compliance report), it calls your `GET /users/{foreign_user_id}` endpoint. You must return the required user data for all the legislations you have enabled in your project. See the type definitions in `@wavynode/utils` for the exact fields required by each legislation.

**4. You receive real-time alerts**

When suspicious activity is detected, Wavy Node sends a notification to your `POST /webhook` endpoint with the transaction details and regulatory violations.

All requests from Wavy Node are signed with HMAC-SHA256 so you can verify their authenticity.

### Organization compliance data

Before Wavy Node can generate regulatory reports, you must configure your organization's compliance data in the dashboard. Navigate to **Management → Organization** in the sidebar and fill in the **Compliance Data** section. This includes:

* **Platform domain** — Your platform's domain (auto-formatted to uppercase, e.g., `wavynode.com` → `WAVYNODE`).
* **Tax IDs** — The tax identifier for each country where you have active legislation:

> [!WARNING]
>
> This information is required to generate regulatory reports. Without it, reports will not be generated.

| Country | Field | Example |
| - | - | - |
| Mexico (MX) | RFC | `XAXX010101000` |
| Colombia (CO) | NIT | `900123456-7` |
| El Salvador (SV) | NIT | `0614-123456-001-0` |
| Guatemala (GT) | NIT | `1234567-8` |

## Getting started

There are two ways to create a new integration:

> [card] [Use the template](https://github.com/wavy-node/integration)
>
> A ready-to-go Nitro application with all required endpoints and authentication already set up. Ideal for local development.

> [card] [Build from scratch](https://docs.wavynode.com/integrations/authentication.md)
>
> Use any framework or language. Start by setting up authentication.

## `@wavynode/utils` package

We provide an npm package with utilities to simplify the integration process:

```bash theme={null}
npm install @wavynode/utils
```

This package includes:

* `validateSignature` — Verify the authenticity of requests from Wavy Node.
* Type definitions for each legislation's required user data (e.g., `MexicoUserData`, `ColombiaUserData`).

## Next steps

> [card] [Authentication](https://docs.wavynode.com/integrations/authentication.md)
>
> Learn how to verify requests from Wavy Node.

> [card] [Endpoints](https://docs.wavynode.com/integrations/endpoints.md)
>
> Implement the required endpoints for your integration.

> [card] [API Reference](https://docs.wavynode.com/api-reference/introduction.md)
>
> Explore the full API documentation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.