Skip to main content
Integrations connect your application with Wavy Node. By creating an integration, you can receive real-time notifications about your users’ on-chain activity and provide Wavy Node with the necessary data to monitor their wallets.

​
How it works

Your integration is a server that exposes two endpoints that Wavy Node calls:
  1. GET /users/{foreign_user_id} — Wavy Node requests user data from your system for compliance checks and report generation.
  2. POST /webhook — Wavy Node sends you real-time alerts when suspicious activity is detected.

​
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: 
{
  "foreign_user_id": "usr_123",
  "mexico": {
    "nombre": "Juan",
    "apellido_paterno": "Pérez",
    "apellido_materno": "López",
    "rfc": "PELJ900101XXX",
    "curp": "PELJ900101HDFRPN09",
    "pais_nacionalidad": "MX",
    "actividad_economica": 1234567,
    "documento_identificacion": {
      "tipo_identificacion": 1,
      "numero_identificacion": "ABC123456"
    }
  }
}
The complete type definitions for each legislation are available in the @wavynode/utils package.
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 LegislationRequired FieldContent
Mexico (MX)mexicoPersonal data, RFC/CURP, address, ID document
Colombia (CO)colombiaUser data required by Colombian 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:
This information is required to generate regulatory reports. Without it, reports will not be generated.
CountryFieldExample
Mexico (MX)RFCXAXX010101000
Colombia (CO)NIT900123456-7
El Salvador (SV)NIT0614-123456-001-0
Guatemala (GT)NIT1234567-8

​
Getting started

There are two ways to create a new integration:

Use the template

A ready-to-go Nitro application with all required endpoints and authentication already set up. Ideal for local development.

Build from scratch

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

Authentication

Learn how to verify requests from Wavy Node.

Endpoints

Implement the required endpoints for your integration.

API Reference

Explore the full API documentation.