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:
pm_sponsorUserOperation
Purpose: Sponsors a user operation by providing paymaster data to cover gas costs.
Parameters:
Response:
pm_getPaymasterData
Purpose: Gets paymaster data for sponsoring a user operation (functionally equivalent to pm_sponsorUserOperation
).
Parameters: Same as pm_sponsorUserOperation
Response: Same as pm_sponsorUserOperation
pm_getPaymasterStubData
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.
pm_getAcceptedPaymentTokens
Purpose: Returns the list of tokens accepted for gas payments by the paymaster.
Parameters: []
Response:
eth_estimateUserOperationGas
Purpose: Estimates gas limits required for a user operation.
Parameters:
Response:
eth_sendUserOperation
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:
thirdweb_getUserOperationGasPrice
Purpose: Gets current gas prices optimized for user operations.
Parameters: []
Response:
thirdweb_getUserOperationStatus
Purpose: Gets the current status of a submitted user operation.
Parameters:
Response:
Status Values:
not_found
: User operation not foundnot_submitted
: Not yet submitted to mempoolsubmitted
: Submitted to mempoolrejected
: Rejected by bundlerincluded
: Successfully included in a blockfailed
: Transaction failed on-chainqueued
: Queued for processing
zk_paymasterData
Purpose: Gets paymaster data for zkSync chains to enable gasless transactions.
Parameters:
Response:
zk_broadcastTransaction
Purpose: Broadcasts a signed transaction on zkSync chains.
Parameters:
Response:
tw_execute
Purpose: Executes transactions using EIP-7702 (Account Abstraction via Authorization Lists). This enables EOAs to temporarily act as smart contracts.
Parameters:
Response:
tw_getTransactionHash
Purpose: Gets the transaction hash for a queued EIP-7702 transaction.
Parameters:
Response:
The service supports all the standard ERC-4337 bundler methods:
eth_chainId
- Returns the current chain IDeth_getUserOperationByHash
- Retrieves user operation by hasheth_getUserOperationReceipt
- Gets the receipt for a user operationeth_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:
- 400: Invalid parameters, malformed request, or unsupported chain
- 401: Invalid authentication credentials or insufficient permissions
- 500: Internal server error
- 502: Upstream bundler provider error
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:
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: