Skip to main content

​
Tenderly Alerts API

This guide covers setting up both simple and complex alerting rules using Tenderly’s API. We’ll explore each expression type and then combine them into sophisticated monitoring solutions.

Alerting API reference

​
Introduction

Tenderly’s Alert API allows you to create simple and complex Alerts. A simple alert consists of one rule, for example method_call will get triggered when a transaction invokes your public or external method. A complex alert can have several conditions, and will get triggered when all of them are met. For example, an alert with method_call and state_change will trigger when a transaction calls the given method and updates the specified storage slot. When defining an Alert using the API, you need to specify the following:
  • delivery channels that get notified when alerting rule is triggered. See more about Delivery Channels.
  • expressions array that will trigger the alert when all conditions represented by individual expressions are met.
You can create delivery channels only via Dashboard, but you can fetch them using the API.

​
Authentication

Before creating alerts, you’ll need to set up authentication and identify your project: 
const TENDERLY_API_KEY = 'your_api_key';
const PROJECT_SLUG = 'your_project_slug';
const ACCOUNT_ID = 'me';  // Use 'me' or your specific account ID

// Base configuration for axios
const baseConfig = {
  baseURL: 'https://api.tenderly.co/api/v1',
  headers: {
    'X-Access-Key': TENDERLY_API_KEY,
    'Content-Type': 'application/json'
  }
};

​
2. State Change Monitoring

Use Case: Monitor changes in contract state variables, especially useful for tracking critical parameters like paused state or balance thresholds. 
const stateChangeAlert = {
  name: "Critical State Change Alert",
  description: "Monitors important state changes",
  enabled: true,
  expressions: [{
    type: "state_change",
    expression: {
      address: "0x1234....",
      parameter_conditions: [
        {
          parameter_name: "pause",
          parameter_type: "bool",
          compare_change: true
        },
        {
          parameter_name: "totalSupply",
          parameter_type: "uint",
          compare_percentage: true,
          comparison_value: "5",
          operator: ">="
        }
      ]
    }
  }],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};

await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  stateChangeAlert,
  baseConfig
);

​
3. Event Monitoring

Use Case: Monitor specific events emitted by your contracts, with parameter filtering. 
const eventAlert = {
  name: "Large Transfer Event Alert",
  description: "Monitors large transfer events",
  enabled: true,
  expressions: [{
    type: "emitted_log",
    expression: {
      address: "0x1234....",
      event_name: "Transfer",
      event_id: "0x241ea03ca20251805084d27d4440371c34a0b85ff108f6bb5611248f73818b80",
      parameter_conditions: [
        {
          parameter_name: "amount",
          parameter_type: "uint",
          operator: ">=",
          comparison_value: "1000000000000000000" // 1 ETH
        }
      ],
      decode_events: true
    }
  }],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};

await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  eventAlert,
  baseConfig
);

​
Complex Alert Examples

Explore examples of showing complex expression rules. The alert will get triggered when every expression in the expressions array is satisfied.

​
1. Security Monitoring System

Use Case: Comprehensive security monitoring combining multiple conditions:
  • Monitor admin function calls
  • Track large value transfers
  • Watch for blacklisted addresses
  • Alert on state changes to critical parameters
const securityAlert = {
  name: "Security Monitoring System",
  description: "Comprehensive security monitoring for contract",
  enabled: true,
  expressions: [
    {
      "type": "contract_address",
      "expression": {
          "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
      }
    },
    // Admin function monitoring
    {
      type: "method_call",
      expression: {
        line_number: 123,
        call_position: "any"
      }
    },
    // Blacklist checking
    {
      type: "blacklisted_caller_addresses",
      expression: {
        addresses: [
          "0xblacklisted1...",
          "0xblacklisted2..."
        ]
      }
    },
    // Large value transfers
    {
      type: "tx_value",
      expression: {
        transaction_value: "100000000000000000000", // 100 ETH
        operator: ">"
      }
    },
    // Critical state changes
    {
      type: "state_change",
      expression: {
        address: "0x1234....",
        parameter_conditions: [
          {
            parameter_name: "pause",
            parameter_type: "bool",
            compare_change: true
          },
          {
            parameter_name: "owner",
            parameter_type: "address",
            compare_change: true
          }
        ]
      }
    }
  ],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};

await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  securityAlert,
  baseConfig
);

​
2. DeFi Protocol Monitor

Use Case: Monitor a DeFi protocol for:
  • Large trades/swaps
  • Significant price impacts
  • Liquidity changes
  • Failed transactions
  • Sandwich attacks
const defiMonitor = {
  name: "DeFi Protocol Monitor",
  description: "Comprehensive DeFi protocol monitoring system",
  enabled: true,
  expressions: [
    // Monitor large swaps via events
    {
      type: "emitted_log",
      expression: {
        address: "0xpool_address",
        event_name: "Swap",
        event_id: "0x...", // Swap event signature
        parameter_conditions: [
          {
            parameter_name: "amountOut",
            parameter_type: "uint",
            operator: ">=",
            comparison_value: "1000000000000000000000" // 1000 tokens
          }
        ],
        decode_events: true
      }
    },
    // Monitor liquidity changes
    {
      type: "state_change",
      expression: {
        address: "0xpool_address",
        parameter_conditions: [
          {
            parameter_name: "reserve0",
            parameter_type: "uint",
            compare_percentage: true,
            comparison_value: "10",
            operator: ">="
          },
          {
            parameter_name: "reserve1",
            parameter_type: "uint",
            compare_percentage: true,
            comparison_value: "10",
            operator: ">="
          }
        ]
      }
    },
    // Monitor for sandwich attacks
    {
      type: "sandwich_transaction",
      expression: {
        address: "0xpool_address",
        transaction_type: "direct"
      }
    },
    // Monitor failed transactions
    {
      type: "tx_error",
      expression: {
        addresses_to_ignore: [] // Monitor all addresses
      }
    }
  ],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};

await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  defiMonitor,
  baseConfig
);

​
3. ERC20 Token Monitor with Inactivity Alerts

Use Case: Comprehensive token monitoring including:
  • Transfer monitoring
  • Balance checks
  • State consistency checks
  • Inactivity monitoring
const tokenMonitor = {
  name: "ERC20 Token Monitor",
  description: "Comprehensive ERC20 token monitoring with inactivity alerts",
  enabled: true,
  expressions: [
    // Monitor Transfer event consistency
    {
      type: "erc20_transfer_matcher",
      expression: {
        address: "0xtoken_address",
        log_name: "Transfer",
        balances: "balances"
      }
    },
    // Monitor large transfers
    {
      type: "emitted_log",
      expression: {
        address: "0xtoken_address",
        event_name: "Transfer",
        event_id: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        parameter_conditions: [
          {
            parameter_name: "value",
            parameter_type: "uint",
            operator: ">=",
            comparison_value: "1000000000000000000000" // 1000 tokens
          }
        ]
      }
    },
    // Monitor total supply changes
    {
      type: "state_change",
      expression: {
        address: "0xtoken_address",
        parameter_conditions: [
          {
            parameter_name: "totalSupply",
            parameter_type: "uint",
            compare_percentage: true,
            comparison_value: "1",
            operator: ">="
          }
        ]
      }
    },
    // Monitor for inactivity
    {
      type: "no_action",
      expression: {
        no_log: {
          address: "0xtoken_address",
          event_name: "Transfer",
          event_id: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        },
        check_after_seconds: 86400 // 24 hours
      }
    }
  ],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};

await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  tokenMonitor,
  baseConfig
);