starknet_estimateMessageFee - Estimate L1-to-L2 Message Fee

Estimates the L2 fee required to process a message sent from Ethereum (L1) to Starknet (L2). This method simulates the l1_handler transaction that would be triggered by the L1 message and returns the estimated gas and fee breakdown.

Overview

Starknet's L1-to-L2 messaging allows Ethereum smart contracts to send messages to Starknet contracts. When a message is sent from L1, the Starknet sequencer creates an l1_handler transaction to execute the corresponding function on the L2 contract. This method estimates the resources and fees required for that L2 execution.

This is important for bridge operators, cross-layer DeFi protocols, and any application that sends messages from Ethereum to Starknet, because the fee must be paid on L1 when the message is sent.

Important: The sample payload below is illustrative. starknet_estimateMessageFee only succeeds when the message matches a real l1_handler flow on the target contract. Reusing the literal values here on mainnet returns EXPECTED_FROM_BRIDGE_ONLY, so replace them with a bridge-generated message from your integration before relying on the success example.

How L1-to-L2 Messaging Works

1. An Ethereum contract calls the Starknet Core contract's sendMessageToL2 function
2. The message includes the target L2 contract, entry point selector, and payload
3. The Starknet sequencer picks up the message and creates an l1_handler transaction
4. The L2 contract's handler function executes with the provided payload
5. The fee for L2 execution must be estimated and paid upfront on L1

Illustrative Payload Error Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 40,
    "message": "Contract error",
    "data": {
      "revert_error": {
        "error": {
          "error": "0x45585045435445445f46524f4d5f4252494447455f4f4e4c59 ('EXPECTED_FROM_BRIDGE_ONLY')"
        }
      }
    }
  }
}

When you replace the illustrative payload with a real bridge-handler message, the method returns the standard fee object described in the table above. Keep the selector and payload aligned with the target contract's l1_handler ABI or Starknet rejects the estimate before execution.

Errors

Examples

# Estimate fee for an L1-to-L2 message
curl -X POST https://api-starknet-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "starknet_estimateMessageFee",
    "params": [
      {
        "from_address": "0xbe1259ff905cadbbaa62514388b71bdefb8aacc1",
        "to_address": "0x073314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
        "entry_point_selector": "0x02d757788a8d8d6f21d1cd40bce38a8222d70654214e96ff95d8086e684fbee5",
        "payload": [
          "0x01234567890abcdef",
          "0x0de0b6b3a7640000",
          "0x0"
        ]
      },
      "latest"
    ],
    "id": 1
  }'

# Parse the current error from the illustrative payload
curl -s -X POST https://api-starknet-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "starknet_estimateMessageFee",
    "params": [
      {
        "from_address": "0xbe1259ff905cadbbaa62514388b71bdefb8aacc1",
        "to_address": "0x073314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
        "entry_point_selector": "0x02d757788a8d8d6f21d1cd40bce38a8222d70654214e96ff95d8086e684fbee5",
        "payload": ["0x1"]
      },
      "latest"
    ],
    "id": 1
  }' | jq '{
    code: .error.code,
    message: .error.message,
    revert: .error.data.revert_error.error.error
  }'

Use Cases

• Bridge Operations - Estimate the L2 processing fee before sending tokens from Ethereum to Starknet
• Cross-Layer DeFi - Calculate costs for L1-initiated actions on L2 protocols
• Fee Budgeting - Pre-calculate message fees with safety margins to avoid underpayment
• User Interfaces - Display estimated bridging costs to users before they confirm L1 transactions
• Protocol Development - Test and optimize l1_handler functions for gas efficiency

Related Methods

• starknet_estimateFee - Estimate fee for L2 transactions
• starknet_getMessagesStatus - Check L1-to-L2 message processing status
• starknet_getTransactionReceipt - Get receipt for the resulting l1_handler transaction
• starknet_call - Read-only contract call for testing handler logic