Thirdweb Bundler - API Reference

The Thirdweb Bundler is a service that provides Account Abstraction (ERC-4337 and EIP-7702) bundler functionality with integrated paymaster services, zkSync chains support, and EIP-7702 transaction delegation.

• Url format
• Authentication
• Request Format
• Paymaster Methods
• User Operation Methods
• Gas Price Methods
• Status and Tracking Methods
• zkSync-Specific Methods
• EIP-7702 Methods
• Standard ERC-4337 Methods
• Error Responses
• Policy Enforcement

• Chain Parameter: the chain id is always specified in the subdomain (e.g., <chain_id>.bundler.thirdweb.com)
• Version Parameter: the version is specified in the path, we recommend using /v2

https://<chain_id>.bundler.thirdweb.com/v2

All requests require authentication via:

• Client ID: Provided as X-Client-Id: <client_id> header - used for frontend authentication
• Secret Key: Provided as X-Secret-Key: <secret_key> header - used for backend authentication

All RPC requests follow the JSON-RPC 2.0 specification:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "<method_name>",
  "params": [...]
}

Purpose: Sponsors a user operation by providing paymaster data to cover gas costs.

Parameters:

[
  {
    "sender": "0x...", // Address of the smart account
    "nonce": "0x...", // Nonce for the operation
    "initCode": "0x...", // Account initialization code (if needed)
    "callData": "0x...", // The call data to execute
    "callGasLimit": "0x...", // Gas limit for the call
    "verificationGasLimit": "0x...", // Gas limit for verification
    "preVerificationGas": "0x...", // Pre-verification gas
    "maxFeePerGas": "0x...", // Maximum fee per gas
    "maxPriorityFeePerGas": "0x...", // Maximum priority fee per gas
    "paymasterAndData": "0x...", // Paymaster data (EntryPoint v0.6)
    // OR for EntryPoint v0.7:
    "paymaster": "0x...", // Paymaster address
    "paymasterData": "0x...", // Paymaster data
    "paymasterVerificationGasLimit": "0x...",
    "paymasterPostOpGasLimit": "0x..."
  },
  "0x...", // Entry point address
  "0x...", // Chain ID (hex)
]

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "paymaster": "0x...", // Paymaster address
    "paymasterData": "0x...", // Paymaster data
    "paymasterAndData": "0x..." // Combined paymaster data (v0.6)
  }
}

Purpose: Gets paymaster data for sponsoring a user operation (functionally equivalent to pm_sponsorUserOperation).

Parameters: Same as pm_sponsorUserOperation Response: Same as pm_sponsorUserOperation

Purpose: Gets stub paymaster data for gas estimation purposes without actual sponsorship.

Parameters: Same as pm_sponsorUserOperation Response: Similar to pm_sponsorUserOperation but with placeholder data for estimation.

Purpose: Returns the list of tokens accepted for gas payments by the paymaster.

Parameters: []

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "acceptedTokens": []
  }
}

Purpose: Estimates gas limits required for a user operation.

Parameters:

[
  {
    "sender": "0x...", // Smart account address
    "nonce": "0x...", // Account nonce
    "initCode": "0x...", // Initialization code (if deploying)
    "callData": "0x...", // Transaction call data
    "maxFeePerGas": "0x...", // Maximum fee per gas
    "maxPriorityFeePerGas": "0x..." // Maximum priority fee
  },
  "0x...", // Entry point address
  {} // State overrides (optional)
]

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "preVerificationGas": "0x...", // Pre-verification gas
    "verificationGasLimit": "0x...", // Verification gas limit
    "callGasLimit": "0x...", // Call gas limit
    // For EntryPoint v0.7:
    "paymasterVerificationGasLimit": "0x...",
    "paymasterPostOpGasLimit": "0x..."
  }
}

Purpose: Submits a user operation to the bundler for execution on-chain.

Parameters: Same format as the user operation object used in other methods.

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x..." // User operation hash
}

Purpose: Gets current gas prices optimized for user operations.

Parameters: []

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "maxFeePerGas": "0x...", // Recommended max fee per gas
    "maxPriorityFeePerGas": "0x..." // Recommended priority fee
  }
}

Purpose: Gets the current status of a submitted user operation.

Parameters:

["0x..."] // User operation hash (hex string)

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": "not_found|not_submitted|submitted|rejected|included|failed|queued",
    "transactionHash": "0x..." // Transaction hash (null if not yet included)
  }
}

Status Values:

• not_found: User operation not found
• not_submitted: Not yet submitted to mempool
• submitted: Submitted to mempool
• rejected: Rejected by bundler
• included: Successfully included in a block
• failed: Transaction failed on-chain
• queued: Queued for processing

Purpose: Gets paymaster data for zkSync chains to enable gasless transactions.

Parameters:

[
  {
    "nonce": "0x...", // Transaction nonce
    "from": "0x...", // Sender address
    "to": "0x...", // Recipient address
    "gas": "0x...", // Gas limit
    "gasPrice": "0x...", // Gas price
    "value": "0x...", // ETH value to send
    "data": "0x...", // Transaction data
    "maxFeePerGas": "0x...", // EIP-1559 max fee
    "maxPriorityFeePerGas": "0x...", // EIP-1559 priority fee
    "chainId": "0x..." // Chain ID
  }
]

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "paymaster": "0x...", // Paymaster contract address
    "paymasterInput": "0x..." // Encoded paymaster input data
  }
}

Purpose: Broadcasts a signed transaction on zkSync chains.

Parameters:

[
  {
    "nonce": "0x...",
    "from": "0x...",
    "to": "0x...",
    "gas": "0x...",
    "gasPrice": "0x...",
    "value": "0x...",
    "data": "0x...",
    "maxFeePerGas": "0x...",
    "maxPriorityFeePerGas": "0x...",
    "chainId": "0x...",
    "signedTransaction": "0x..." // Raw signed transaction bytes
  }
]

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x..." // Transaction hash
}

Purpose: Executes transactions using EIP-7702 (Account Abstraction via Authorization Lists). This enables EOAs to temporarily act as smart contracts.

Parameters:

[
  "0x...", // EOA address that will execute the calls
  {
    "calls": [
      {
        "target": "0x...", // Contract address to call
        "value": "0x...", // ETH value to send (hex)
        "data": "0x..." // Call data
      }
      // ... more calls
    ],
    "uid": "0x..." // Unique identifier for the batch (bytes32)
  },
  "0x...", // Signature authorizing the execution
  {
    // Authorization list (optional)
    "chainId": 1,
    "address": "0x...",
    "nonce": "0x...",
    "yParity": 0,
    "r": "0x...",
    "s": "0x..."
  }
]

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "queueId": "..." // Queue ID for tracking the transaction
  }
}

Purpose: Gets the transaction hash for a queued EIP-7702 transaction.

Parameters:

["queue_id"] // Queue ID returned from tw_execute

Response:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "transactionHash": "0x..." // Transaction hash (null if not yet mined)
  }
}

The service supports all the standard ERC-4337 bundler methods:

• eth_chainId - Returns the current chain ID
• eth_getUserOperationByHash - Retrieves user operation by hash
• eth_getUserOperationReceipt - Gets the receipt for a user operation
• eth_supportedEntryPoints - Lists supported EntryPoint contracts
• Any other standard bundler RPC methods defined in ERC-4337

All methods may return error responses following the JSON-RPC 2.0 error format:

{
  "id": 1,
  "jsonrpc": "2.0",
  "error": {
    "code": 400,
    "message": "Detailed error description"
  }
}

• 400: Invalid parameters, malformed request, or unsupported chain
• 401: Invalid authentication credentials or insufficient permissions
• 500: Internal server error
• 502: Upstream bundler provider error

// Invalid chain
{
  "error": "Invalid chain: unsupported_chain",
  "chain": "unsupported_chain",
  "code": 400
}
 
// Mainnet access denied
{
  "error": "Mainnets not enabled for this account, please enable billing...",
  "code": 401
}
 
// Invalid user operation hash
{
  "error": "Invalid userOpHash parameter",
  "code": 400
}

Paymaster methods support policy-based access control. When a transaction is subject to policy evaluation:

• The system evaluates paymaster requests against configured policies
• Policies can restrict based on:
  • Contract addresses being called
  • Transaction data
  • Gas limits
  • Sender addresses
  • Custom endpoint logic

If a request is rejected by policy, the response format is:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "policyId": "policy_123", // ID of the policy that rejected the request
    "reason": "Transaction rejected by policy: Unauthorized contract call"
  }
}

Policy enforcement applies to:

• pm_sponsorUserOperation
• pm_getPaymasterData
• zk_paymasterData

• Rate limits may apply based on your billing plan
• Mainnet access requires billing information
• Testnet access is available on free plans

For the most up-to-date list of supported chains, check the thirdweb dashboard.

For easier integration, consider using the thirdweb SDKs:

• JavaScript/TypeScript SDK
• React SDK
• Unity SDK
• Dotnet SDK
• Unreal Engine SDK