Endpoints - Wavy Node

Your integration is a single server (one URL) that exposes two routes. When you configure the integration URL in the Wavy Node dashboard (e.g., https://your-server.com), Wavy Node appends the route paths automatically:

GET {integrationUrl}/users/{foreign_user_id}
POST {integrationUrl}/webhook

You only need one server and one integration URL. Do not create separate servers or URLs for each route. Wavy Node sends requests to both routes on the same base URL.

`GET /users/{foreign_user_id}`

Wavy Node calls this endpoint to retrieve information about a specific user. The {foreign_user_id} parameter is the user’s ID in your system (the same ID you provided when registering the wallet address).

The foreign_user_id is the identifier you send when creating an address via POST /projects/{projectId}/addresses. This is how Wavy Node links wallets to users in your system.

Your endpoint should return a JSON object with the following structure:

{
  "givenName": "Maria Guadalupe",
  "maternalSurname": "Sánchez",
  "paternalSurname": "Rodríguez",
  "birthdate": "1992-05-15",
  "nationality": "MX",
  "phoneNumber": {
    "countryCode": "+52",
    "phoneNumber": 5512345678
  },
  "email": "[email protected]",
  "address": {
    "country": "MX",
    "region": "CDMX",
    "city": "Ciudad de México",
    "street": "Avenida Insurgentes Sur",
    "colonia": "Condesa",
    "exteriorNumber": "123",
    "interiorNumber": "4B",
    "postalCode": "06100"
  },
  "mexico": {
    "rfc": "ROSM920515XXX",
    "curp": "ROSM920515MDFRXXXX",
    "actividadEconomica": 612012,
    "cuentaRelacionada": "1234567890",
    "monedaCuentaRelacionada": 1,
    "documentoIdentificacion": {
      "tipoIdentificacion": 1,
      "numeroIdentificacion": "IDMEX12345678"
    }
  }
}

Response fields

Field	Type	Description
`givenName`	string	The individual’s given name(s)
`maternalSurname`	string	Maternal surname
`paternalSurname`	string	Paternal surname
`birthdate`	string	Date of birth in `YYYY-MM-DD` format (ISO 8601)
`nationality`	string	ISO 3166-1 alpha-2 country code
`phoneNumber.countryCode`	string	Phone country code
`phoneNumber.phoneNumber`	number	Phone number
`email`	string	Email address
`address`	object	Physical address
`mexico`	object	Fields required for Mexican legislation reports (optional)

The mexico object is only needed if you have Mexican compliance enabled in your dashboard.

Person types for Mexican reports

When Mexican legislation is active, the mexico data feeds the AVI report. A report supports three mutually exclusive person types, and exactly one applies per user.

Persona física
Persona moral
Fideicomiso

An individual account holder. At least one of rfc, curp, or birthdate is required.

{
  "givenName": "Maria Guadalupe",
  "paternalSurname": "García",
  "maternalSurname": "López",
  "birthdate": "1990-05-15",
  "nationality": "MX",
  "mexico": {
    "rfc": "GALM900515XXX",
    "curp": "GALM900515MDFRPN09",
    "actividadEconomica": 8140001,
    "cuentaRelacionada": "012180001234567890",
    "monedaCuentaRelacionada": 1,
    "documentoIdentificacion": {
      "tipoIdentificacion": 1,
      "numeroIdentificacion": "INE123456789"
    }
  }
}

A legal entity. At least one of rfc or fechaConstitucion is required, and a legal representative (representanteApoderado) is mandatory.

{
  "tipoPersona": "moral",
  "denominacionRazon": "Empresa Ejemplo SA de CV",
  "fechaConstitucion": "2015-03-20",
  "nationality": "MX",
  "representanteApoderado": {
    "givenName": "Juan Carlos",
    "paternalSurname": "Martínez",
    "maternalSurname": "Ruiz",
    "birthdate": "1985-08-10",
    "rfc": "MARJ850810XXX",
    "curp": "MARJ850810HDFRRL09",
    "documentoIdentificacion": {
      "tipoIdentificacion": 1,
      "numeroIdentificacion": "INE987654321"
    }
  },
  "mexico": {
    "rfc": "EEJ150320XXX",
    "giroMercantil": 5612001,
    "actividadEconomica": 5612001,
    "cuentaRelacionada": "014320001234567890",
    "monedaCuentaRelacionada": 1,
    "documentoIdentificacion": {
      "tipoIdentificacion": 4,
      "numeroIdentificacion": "ACTA-CONST-2015"
    }
  }
}

A trust. At least one of rfc or identificadorFideicomiso is required, and a fiduciary delegate (delegadoFiduciario) is mandatory.

{
  "tipoPersona": "fideicomiso",
  "denominacionRazon": "Fiduciario Ejemplo SA",
  "nationality": "MX",
  "delegadoFiduciario": {
    "givenName": "Ana María",
    "paternalSurname": "Torres",
    "maternalSurname": "Vega",
    "birthdate": "1980-02-25",
    "rfc": "TOVA800225XXX",
    "curp": "TOVA800225MDFRRN09",
    "documentoIdentificacion": {
      "tipoIdentificacion": 1,
      "numeroIdentificacion": "INE555444333"
    }
  },
  "mexico": {
    "rfc": "FEJ800101XXX",
    "identificadorFideicomiso": "FID-2020-00123",
    "cuentaRelacionada": "012180009876543210",
    "monedaCuentaRelacionada": 1,
    "documentoIdentificacion": {
      "tipoIdentificacion": 4,
      "numeroIdentificacion": "CONTRATO-FID-2020"
    }
  }
}

Codes such as tipoIdentificacion (1=INE, 2=Passport, 4=Incorporation deed), actividadEconomica, and giroMercantil follow the SAT catalogs, published at sppld.sat.gob.mx.

`POST /webhook`

Wavy Node sends real-time notifications to this endpoint. The request body contains:

Field	Type	Description
`type`	string	`notification` or `error`
`data`	object or string	The notification payload or error message

Notification payload

When type is notification, the data object contains transaction and compliance details:

{
    "type": "notification",
    "data": {
        "id": 1,
        "projectId": 1,
        "chainId": 42161,
        "address": {
            "id": 543,
            "userId": "user-in-your-db-123",
            "address": "0xyour-address-involved",
            "description": "Your address' description"
        },
        "txHash": "some-tx-hash",
        "timestamp": "2025-08-20T05:10:57.228Z",
        "amount": {
            "value": 1000000000000000000,
            "usd": 3000
        },
        "token": {
            "name": "Ethereum",
            "symbol": "ETH",
            "decimals": 18,
            "address": null
        },
        "inflictedLaws": [
            {
                "name": "The name of the law inflicted",
                "description": "Description of the law",
                "source": "Source of the law",
                "risk": "warn",
                "country": "mexico",
                "countryCode": "MX"
            }
        ]
    }
}

Notification data fields

Field	Type	Description
`id`	number	Notification ID
`projectId`	number	Project ID
`chainId`	number	Chain ID where the transaction occurred
`address.id`	number	Address ID
`address.userId`	string	User ID in your system (the `foreign_user_id` you provided when registering the address)
`address.address`	string	Wallet address
`address.description`	string	Address description
`txHash`	string	Transaction hash
`timestamp`	string	Transaction timestamp (ISO 8601)
`amount.value`	number	Amount in the token’s smallest unit
`amount.usd`	number	Amount in USD
`token.name`	string	Token name
`token.symbol`	string	Token symbol
`token.decimals`	number	Token decimals
`token.address`	string	Token contract address (`null` for native tokens)
`inflictedLaws`	array	Laws inflicted by the transaction
`inflictedLaws[].name`	string	Law name
`inflictedLaws[].description`	string	Law description
`inflictedLaws[].source`	string	Law source
`inflictedLaws[].risk`	string	`warn` or `illegal`
`inflictedLaws[].country`	string	Country name
`inflictedLaws[].countryCode`	string	ISO country code

Error payload

When type is error, the data field is a string containing the error message.

​GET /users/{foreign_user_id}

​Person types for Mexican reports

​POST /webhook

​Notification payload

​Error payload

`GET /users/{foreign_user_id}`

Person types for Mexican reports

`POST /webhook`

Notification payload

Error payload