tenderly-alerts

name: tenderly-alerts description: Use when setting up real-time blockchain monitoring on Tenderly — creating wallet/contract alerts (balance thresholds, transaction status, function calls, ERC20 transfers, event emissions), wiring Slack/webhook notifications via the Alerts REST API, troubleshooting 400 "Expressions are not in the right format" errors, or programmatically managing alerts outside the dashboard

Tenderly Alerts

Overview

Tenderly's Alerts API lets you provision real-time on-chain monitoring (balance, tx status, function calls, events, ERC20 transfers) and route notifications to Slack/email/webhooks. The public docs describe the dashboard flow but leave the API's expression schema mostly undocumented — expression type names in the docs (successful_tx, failed_tx, etc.) return 400 "Expressions are not in the right format". This skill captures the empirically-verified schema and the gotchas.

Core Pattern

An alert is an array of expressions (AND'd together) plus a list of delivery_channels. Each expression is { type, expression: {...} }. Type names are NOT free-form — only specific strings work. Wrong type or unknown field → silent drop or 400.

Quick Reference

Auth

# Generate at https://dashboard.tenderly.co/account/authorization
# Header: X-Access-Key (NOT Authorization: Bearer)
curl -H "X-Access-Key: $TOKEN" https://api.tenderly.co/api/v1/...

The me alias for account slug does not work — use the real slug from the dashboard URL (dashboard.tenderly.co/<slug>/<project>). 401 with the right header almost always means wrong slug or empty token (env vars don't persist across separate shell invocations — write the token to a file with chmod 600).

Endpoints

PUT returns 404 — only PATCH works. Despite the name, PATCH is not a partial update: it rejects with "Name cannot be empty" if you omit fields. Standard pattern: GET → mutate the returned alert object → PATCH with full body (drop server-managed fields like id, project_id, created_at, updated_at, color).

Base URL: https://api.tenderly.co/api/v1.

Verified expression types

Naming pattern: the inner field for "stateful" filters tends to use a transaction_* prefix (transaction_success, transaction_value). If a type returns 200 but your filter field comes back null, try renaming the field with that prefix.

Type names that DON'T work (return 400)

successful_tx, failed_tx, successful_transaction, failed_transaction, from_address, caller_address, filtered_caller_address, transaction_address, from, to, tx, address, transaction_value (use tx_value), erc20_transfer, erc20_token_transfer, erc20, transfer, token_transfer, log_emitted, event_emitted, log, event.

For unverified alert types (ERC20 transfer, function call, event emitted, state change, view function, allowlisted/blocklisted callers), the dashboard UI is the fastest discovery path: configure it once in the UI, then GET the alert via API and copy the expressions array as your template.

Full alert payload

{
  "name": "Wallet outgoing tx succeeded",
  "description": "Optional human-readable context",
  "enabled": true,
  "severity": "info | warning | critical",
  "expressions": [
    { "type": "network", "expression": { "network_id": "1" } },
    { "type": "tx_status", "expression": { "transaction_success": true } },
    {
      "type": "whitelisted_caller_addresses",
      "expression": { "addresses": ["0xABCD..."] }
    }
  ],
  "delivery_channels": [{ "id": "<channel_uuid>", "enabled": true }]
}

Common recipes

Balance threshold (wallet running low):

{
  "expressions": [
    { "type": "network", "expression": { "network_id": "1" } },
    {
      "type": "eth_balance",
      "expression": {
        "address": "0x...",
        "threshold": "100000000000000000",
        "operator": "<"
      }
    }
  ],
  "delivery_channels": [{ "id": "...", "enabled": true }],
  "name": "...",
  "enabled": true
}

Any successful tx from a wallet (activity monitor): network + tx_status (true) + whitelisted_caller_addresses.

Failed tx from a wallet (compromise/bug signal): same as above with transaction_success: false.

For the remaining 8 Tenderly alert types (Function Call, Event Emitted, Event Parameter, ERC20 Token Transfer, Allowlisted/Blocklisted Callers, Transaction Value, State Change, View Function) the dashboard UI is the fastest way to discover the exact expression shape: configure the alert in the UI, then GET it via API and copy the returned expressions array as the template.

Delivery channels

Cannot be created via API — only listed/referenced. Set up the destination (Slack OAuth, webhook URL, email, Discord, Telegram, PagerDuty) in the dashboard at /account/<slug>/project/<proj>/alerts/destinations, then:

curl -H "X-Access-Key: $TOKEN" \
  https://api.tenderly.co/api/v1/account/<slug>/delivery-channels

Extract id from the response and reuse across alerts. Channels are account-scoped (visible to every project) unless you pick a project scope in the UI.

Gotchas

• Unknown fields are silently stripped. If you send {type: "tx_status", expression: {address: "0x..", status: "success"}} the response will show expression: {transaction_success: null} — no error, but your filter is gone. Always GET the alert after creation to verify the stored shape matches intent.
• Token in <bash-input> / one-shot export doesn't persist across separate Bash tool invocations. Write to ~/.tenderly_token with chmod 600 and cat it in each curl.
• Balance alerts trigger on tx mutating the balance, not on state. A wallet sitting below threshold won't fire — only a tx involving it will re-evaluate.
• me is not a valid account slug for these endpoints (despite older docs claiming so). Use the real slug.
• Addresses are lowercased on storage but matched case-insensitively.

Negation limitation (no native "NOT in list" expression)

Tenderly's expression set has Allowlisted Callers and Blocklisted Callers, but those filter callers INTO a target contract, not callees FROM a wallet. To express "tx from W to any address NOT in [A, B, …]" (e.g., key-leak detection for a relayer that should only touch specific contracts), there is no native combination. Workaround: create a Web3 Action triggered by any tx where from = W, encode the allowlist in TypeScript, and POST to Slack from the action when the check fails.

Common Mistakes

Verification workflow

After any create/update, always:

1. GET the alert by id
2. Diff expressions returned vs. what you sent
3. Any missing field = silently stripped → schema is wrong