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'
  }
};

Expression Types

You can use different expression types for specifying Alerts’ trigger rules.

Expression Type	Monitoring	Main Use Case	Required Arguments	Optional Arguments
`method_call`	Specific function calls in contracts (direct or internal transactions apply)	Track when important functions are called	- `line_number`: Line where function is defined; `call_position`: Position of call (“first”, “last”, “any”)	None
`whitelisted_caller_addresses`	For calls from specific addresses	Allow-list based access control	- `addresses`: Array of Ethereum addresses	None
`blacklisted_caller_addresses`	For calls from blocked addresses	Block-list based access control	- `addresses`: Array of Ethereum addresses	None
`contract_address`	Specific contract interactions	Track all interactions with a contract	- `address`: Contract address	- `transaction_type`: “direct”, “source”, or “internal”
`network`	Events on specific networks	Multi-chain monitoring	- `network_id`: Network/chain ID	None
`tag`	Contracts with specific tags	Group-based monitoring	- `tag`: Tag string	- `transaction_type`: “direct”, “source”, or “internal”
`tx_status`	Transaction success/failure	Track failed transactions	None	- `transaction_success`: boolean
`function_params`	Function parameter values	Track specific function inputs	- `address`: Contract address; `function_line_number`: Function definition line; `parameter_conditions`: Array of conditions	- Parameter specific options
`tx_value`	Transaction value	Track large transfers	- `transaction_value`: Amount in wei; `operator`: Comparison operator	None
`emitted_log`	Contract events	Track specific events	- `address`: Contract address; `event_name`: Event name; `event_id`: Event signature	- `match_any`: boolean; `decode_events`: boolean; `parameter_conditions`: Array of conditions
`state_change`	Contract state changes	Track storage changes	- `address`: Contract address; `parameter_conditions`: Array of conditions	- Comparison options (threshold, percentage)
`view_function`	Read-only function results	Track computed values	- `address`: Contract address; `input`: ABI encoded function data; `network_id`: Network ID	- `parameter_condition`: Value comparison
`eth_balance`	ETH balance changes	Track balance thresholds	- `address`: Contract address; `threshold`: Balance in wei	None
`erc20_transfer_matcher`	ERC20 transfer consistency	Validate transfer mechanics	- `address`: Token address; `log_name`: Event name; `balances`: State variable name	None
`tx_error`	For transaction errors	Track unexpected failures	None	- `addresses_to_ignore`: Array of addresses
`tx_internal_error`	For internal tx errors	Track internal call failures	None	- `addresses_to_match`: Array of addresses
`no_action`	For inactivity	Track contract dormancy	- `check_after_seconds`: Time threshold	- `no_log`: Log conditions; `no_transaction`: Transaction conditions
`sandwich_transaction`	For sandwich attacks	Track MEV activity	- `address`: Contract address	- `transaction_type`: “direct”, “source”, or “internal”

Notes

For comparison operators (operator), valid values are: >, >=, <, <=, ==, !=, contains, notContains
Parameter types (parameter_type) include: uint, int, bool, address, string, byte
All addresses must be valid Ethereum addresses (0x prefixed, 40 hex chars)
Wei values should be passed as strings to handle large numbers
Network IDs should match the target blockchain (e.g., “1” for Ethereum mainnet)

For more details, explore the API reference:

Alerting API reference

Simple expressions examples

Explore examples of setting up simple expression rules.

1. Method Call Monitoring

Use Case: Monitor specific function calls in your smart contract.

const methodCallAlert = {
  name: "Critical Function Call Alert",
  description: "Monitors calls to critical functions",
  enabled: true,
  expressions: [{
    type: "method_call",
    expression: {
      line_number: 123, // Line where function is defined
      call_position: "any" // "first", "last", or "any"
    }
  },
  {
      "type": "contract_address",
      "expression": {
          "address": "0xe592427a0aece92de3edee1f18e0157c05861564"
      }
  }
  ],
  delivery_channels: [{
    id: "your_channel_id",
    enabled: true
  }]
};
 
await axios.post(
  `/account/${ACCOUNT_ID}/project/${PROJECT_SLUG}/alert`,
  methodCallAlert,
  baseConfig
);

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
);

Setting Up Alerts as Triggers for Web3Actions

Virtual TestNets

Node RPC

Simulation API

Developer Explorer

Monitoring

Other

Platform

Resources