> ## 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.
</Warning>

```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](/integrations/endpoints) 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.
</Warning>

| 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Wavy Node monitors on-chain activity">
    Wavy Node watches your registered addresses for suspicious transactions, regulatory violations, and interactions with blacklisted wallets.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.
</Warning>

| 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:

<CardGroup cols={2}>
  <Card title="Use the template" icon="github" href="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>

  <Card title="Build from scratch" icon="code" href="/integrations/authentication">
    Use any framework or language. Start by setting up authentication.
  </Card>
</CardGroup>

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

<CardGroup cols={3}>
  <Card title="Authentication" icon="lock" href="/integrations/authentication">
    Learn how to verify requests from Wavy Node.
  </Card>

  <Card title="Endpoints" icon="plug" href="/integrations/endpoints">
    Implement the required endpoints for your integration.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API documentation.
  </Card>
</CardGroup>