Bundler & Paymaster API Reference

The Coinbase Bundler & Paymaster API provides ERC-4337 account abstraction endpoints to send transactions from smart account wallets, and to sponsor gas for user transactions.

Get started

1. Create a new CDP account or sign in to your exsiting account.
2. Create a Base project.
3. Activate Paymaster and automatically receive 0.25 ETH in gas credits.
4. Start sending user operations and sponsoring user transactions!
5. Apply for additional gas credits as you scale.

Example repository

See paymaster-bundler-examples on Github for help integrating our Paymaster with SDKs.

Need Help?

Join the Base Discord and let us know in #developer-support if you need assistance.

Bundler methods

eth_supportedEntryPoints

This endpoint retrieves an array of supported entry points. Currently, the only supported entrypoint is 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789.

Request/Response

Request (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_supportedEntryPoints"
}

Response (JSON)

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

eth_getUserOperationByHash

This endpoint returns a UserOperation based on the hash returned from eth_sendUserOperation.

Parameters

Name	Type	Req	Description
hash	array	Y	The hash of the user operation to retrieve

Returns

Type	Description
sender	Account initiating the user operation
nonce	Nonce
initCode	initCode (needed if the account needs to be created)
preVerificationGas	Amount of gas to pay for to compensate the bundler for pre-verification execution and calldata
maxFeePerGas	Maximum fee per gas to pay for the execution of this operation
maxPriorityFeePerGas	Maximum priority fee per gas
signature	Signature from the account
verificationGasLimit	Amount of gas to allocate for the verification step
callGasLimit	Amount of gas to allocate the main execution call
paymasterAndData	Hex string signed by the paymaster for a sponsored transaction
blockNumber	Block number in which UserOperation is included
blockHash	Block hash in which UserOperation is included
transactionHash	Transaction hash of the UserOperation

Request/Response

Request (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getUserOperationByHash",
  "params": [
    "0x77c0b560eb0b042902abc5613f768d2a6b2d67481247e9663bf4d68dec0ca122"
  ]
}

Response (JSON)

{
  "jsonrpc": "2.0",
   "id": 1,
  "result": {
            sender, // string
            nonce, // string
            initCode, // string
            callData, // string
            callGasLimit, // string
            verificationGasLimit, // string
            preVerificationGas, // string
            maxFeePerGas, // string
            maxPriorityFeePerGas, // string
       signature, // string 
     paymasterAndData, // string 
      blockNumber, // integer 
      blockHash, // string 
      transactionHash, // string 
    }
}

eth_getUserOperationReceipt

This endpoint returns a receipt based on the hash returned from eth_sendUserOperation.

Parameters

Name	Type	Req	Description
hash	array	Y	The hash of the user operation to retrieve

Returns

Type	Description
userOpHash	Hash of the User Operation
entryPoint	Entrypoint that the User Operation was sent to
sender	Account initiating the user operation
nonce	Nonce
paymaster	Paymaster used in the user operation
actualGasCost	Actual gas consumed by this UserOperation
actualGasUsed	Total gas used by this UserOperation
success	Whether the execution completed successfully
reason	If reverted, the reason the execution failed
logs	Logs generated by this UserOperation (not including logs of other UserOperations in the same bundle)
receipt	TransactionReceipt object for the entire bundle

Request (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_getUserOperationReceipt",
  "params": [
    "0x77c0b560eb0b042902abc5613f768d2a6b2d67481247e9663bf4d68dec0ca122"
  ]
}

Response (JSON)

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "userOpHash": "0x13574b2256b73bdc33fb121052f64b3803161e5ec602a6dc9e56177ba387e700",
    "entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
    "sender": "0x023fEF87894773DF227587d9B29af8D17b4dBB5A",
    "nonce": "0x1",
    "paymaster": null,
    "actualGasCost": "0x6f75ef8d",
    "actualGasUsed": "0x329af",
    "success": true,
    "reason": "",
    "logs": [
      {
        "address": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
        "topics": [
          "0xbb47ee3e183a558b1a2ff0874b079f3fc5478b7454eacf2bfc5af2ff5878f972"
        ],
        "data": "0x",
        "blockNumber": "0x27fb22e",
        "transactionHash": "0x0f9b0e5868beaf345d8d55895c8037ae85adb91c422c00badcdcae8a0bf247a1",
        "transactionIndex": "0x4",
        "blockHash": "0x965e08190b1093c078bde81f67362203834784e34cf499d516f1a7b9c7a7b29e",
        "logIndex": "0x13",
        "removed": false
      }
    ],
    "receipt": {
      "blockHash": "0x965e08190b1093c078bde81f67362203834784e34cf499d516f1a7b9c7a7b29e",
      "blockNumber": "0x27fb22e",
      "from": "0x425d190ef5F561aFc8728593cA13EAf2FD9E3380",
      "to": "0x25aD59adbe00C2d80c86d01e2E05e1294DA84823",
      "cumulativeGasUsed": "0xe13e1",
      "gasUsed": "0x329af",
      "contractAddress": null,
      "logs": [
        null
      ],
      "logsBloom": "0x000000010000000000000000800000000000000000000008000000000200000000080000020000020002080100010000001080000000000000100210000000000000000000000008000000000000808010000000000000000001000000000000000000000e000000000000000000080000002200000000408880000000000040000020000000000001000000080000002040000000040000000000000008000020000000000100000040000000000000000000000000000000000220000000400000000000000000000100000010000044000000800020000a100000010020000000000040000081000000000000000000000000000000400000000000100000",
      "status": 1,
      "type": "0x2",
      "transactionHash": "0x0f9b0e5868beaf345d8d55895c8037ae85adb91c422c00badcdcae8a0bf247a1",
      "transactionIndex": "0x4",
      "effectiveGasPrice": "0x6f75ef8d"
    }
  }
}

eth_sendUserOperation

This endpoint sends a UserOperation for inclusion in the Bundler’s private mempool. The signature must be a valid signature from the smart account.

Parameters

Name	Type	Req	Description
UserOperation	UserOperation	Y	The UserOperation. You may add a paymasterAndData field if the transaction is sponsored.
entryPoint	string	Y	EntryPoint address that the UserOperation is intended for.

Request (JSON)

{
  "jsonrpc": "2.0",
   "id": 1,
  "method": "eth_sendUserOperation",
  "params": [
            {
            sender, // address
            nonce, // uint256
            initCode, // string
            callData, // string
            callGasLimit, // string
            verificationGasLimit, // string
            preVerificationGas, // string
            maxFeePerGas, // string
            maxPriorityFeePerGas, // string
       signature, // string 
     paymasterAndData, // string 
        }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
  ]
}

Response (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1234...5678"
}

Error (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "message": "AA21 didn't pay prefund",
    "code": -32500
  }
}

eth_estimateUserOperationGas

This endpoint will estimate the gas values for a UserOperation. The signature field is ignored and can be a dummy value, but is recommended to be of the same size as an actual signature for an accurate estimate.

Parameters

Name	Type	Req	Description
UserOperation	UserOperation	Y	The UserOperation. You can use a dummy signature but the signature must be the correct size for an accurate gas estimate.
entryPoint	string	Y	EntryPoint address that the UserOperation is intended for.

Returns

Type	Description
preVerificationGas	Amount of gas to compensate the bundler for pre-verification execution and calldata
verificationGasLimit	Amount of gas to allocate for the verification step
callGasLimit	Amount of gas to allocate the main execution call

Request (JSON)

{
  "jsonrpc": "2.0",
   "id": 1,
  "method": "eth_estimateUserOperationGas",
  "params": [
            {
            sender, // address
            nonce, // uint256
            initCode, // string
            callData, // string
            callGasLimit, // string
            verificationGasLimit, // string
            preVerificationGas, // string
            maxFeePerGas, // string
            maxPriorityFeePerGas, // string
       signature, // string 
     paymasterAndData, // string 
        }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
  ]
}

Response (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
      "preVerificationGas": "0x...",
      "verificationGasLimit": "0x...",
      "callGasLimit": "0x...",
  }
}

Error (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "message": "Error reason here.",
    "code": -32601
  }
}

Paymaster methods

pm_sponsorUserOperation

This endpoint sends a UserOperation to a paymaster for off-chain verification based on the custom gas policies set in Coinbase Developer Platform.

If approved, it returns the paymasterAndData and updated gas values, which can be appended to the UserOperation before signing.

Parameters

Name	Type	Req	Description
UserOperation	UserOperation	Y	The UserOperation. You can use a dummy signature but the signature must be the correct size for an accurate gas estimate.
entryPoint	string	Y	EntryPoint address that the UserOperation is intended for.
context	JSON object	N	(Optional) For a dummy paymasterAndData response, use { "dummy" : true } as the third parameter. The Paymaster will use a dummy signature and skip the gas estimation step.

Returns

Type	Description
paymasterAndData	Signed hex string to put as a field in eth_sendUserOperation
preVerificationGas	Amount of gas to compensate the bundler for pre-verification execution and calldata
verificationGasLimit	Amount of gas to allocate for the verification step
callGasLimit	Amount of gas to allocate the main execution call

Request (JSON)

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pm_sponsorUserOperation",
    "params": [
        {
            sender, // address
            nonce, // uint256
            initCode, // string
            callData, // string
            callGasLimit, // string
            verificationGasLimit, // string
            preVerificationGas, // string
            maxFeePerGas, // string
            maxPriorityFeePerGas, // string
        }, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"
        }
    ]
}

Response (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
      "paymasterAndData": "0x1234...5678",
      "preVerificationGas": "0x...",
      "verificationGasLimit": "0x...",
      "callGasLimit": "0x...",
  }
}

Error (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "message": "Error reason here.",
    "code": -32601
  }
}