ZeroDev Paymaster RPC

openapi: 3.0.1
info:
  title: ZeroDev Bundler & Paymaster RPC
  description: >-
    OpenAPI description of ZeroDev's account-abstraction infrastructure. ZeroDev
    does NOT expose a REST API; the bundler and paymaster are JSON-RPC 2.0
    services accessed by HTTP POST to a single project-scoped URL of the form
    https://rpc.zerodev.app/api/v3/{projectId}/chain/{chainId}. The same URL
    serves both the ERC-4337 bundler methods (eth_sendUserOperation,
    eth_estimateUserOperationGas, eth_getUserOperationByHash,
    eth_getUserOperationReceipt, eth_supportedEntryPoints, eth_chainId) and the
    paymaster methods (zd_sponsorUserOperation, pm_sponsorUserOperation, the
    ERC-7677 pair pm_getPaymasterStubData / pm_getPaymasterData, and
    zd_getERC20PaymasterAddress). Authentication is by the projectId embedded in
    the URL path. This document models that single JSON-RPC endpoint; the RPC
    method is selected via the "method" field of the request body, not via the
    HTTP path. Append ?provider=ULTRA_RELAY to route through ZeroDev UltraRelay.
  termsOfService: https://zerodev.app/terms
  contact:
    name: ZeroDev
    url: https://zerodev.app
  version: '3.0'
servers:
  - url: https://rpc.zerodev.app
    description: ZeroDev meta-infrastructure RPC host
paths:
  /api/v3/{projectId}/chain/{chainId}:
    post:
      operationId: jsonRpc
      tags:
        - JSON-RPC
      summary: ZeroDev bundler & paymaster JSON-RPC endpoint
      description: >-
        Single JSON-RPC 2.0 endpoint. POST a request envelope whose "method"
        selects an ERC-4337 bundler method or a ZeroDev/ERC-7677 paymaster
        method. The projectId path parameter authenticates the call; the chainId
        path parameter selects the target EVM chain (e.g. 1 Ethereum, 8453 Base,
        42161 Arbitrum, 84532 Base Sepolia).
      parameters:
        - name: projectId
          in: path
          required: true
          description: ZeroDev project ID from the dashboard; acts as the API credential.
          schema:
            type: string
        - name: chainId
          in: path
          required: true
          description: Numeric EVM chain ID of the target network.
          schema:
            type: integer
        - name: provider
          in: query
          required: false
          description: Optional underlying provider override (e.g. ULTRA_RELAY).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              eth_sendUserOperation:
                summary: Submit a UserOperation (bundler)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_sendUserOperation
                  params:
                    - sender: '0x1234567890123456789012345678901234567890'
                      nonce: '0x0'
                      callData: '0x'
                      callGasLimit: '0x88b8'
                      verificationGasLimit: '0x33450'
                      preVerificationGas: '0xc350'
                      maxFeePerGas: '0x59682f00'
                      maxPriorityFeePerGas: '0x3b9aca00'
                      signature: '0x'
                    - '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
              eth_estimateUserOperationGas:
                summary: Estimate gas for a UserOperation (bundler)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_estimateUserOperationGas
                  params:
                    - sender: '0x1234567890123456789012345678901234567890'
                      nonce: '0x0'
                      callData: '0x'
                      signature: '0x'
                    - '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
              eth_getUserOperationReceipt:
                summary: Fetch a UserOperation receipt (bundler)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_getUserOperationReceipt
                  params:
                    - '0xdead00000000000000000000000000000000000000000000000000000000beef'
              eth_supportedEntryPoints:
                summary: List supported EntryPoint contracts (bundler)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_supportedEntryPoints
                  params: []
              zd_sponsorUserOperation:
                summary: ZeroDev gas sponsorship (paymaster)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: zd_sponsorUserOperation
                  params:
                    - chainId: 8453
                      userOp:
                        sender: '0x1234567890123456789012345678901234567890'
                        nonce: '0x0'
                        callData: '0x'
                        signature: '0x'
              pm_sponsorUserOperation:
                summary: Pimlico-compatible sponsorship (paymaster)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: pm_sponsorUserOperation
                  params:
                    - sender: '0x1234567890123456789012345678901234567890'
                      nonce: '0x0'
                      callData: '0x'
                      signature: '0x'
                    - '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
              pm_getPaymasterStubData:
                summary: ERC-7677 stub paymaster data (paymaster)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: pm_getPaymasterStubData
                  params:
                    - sender: '0x1234567890123456789012345678901234567890'
                      nonce: '0x0'
                      callData: '0x'
                    - '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
                    - '0x2105'
                    - {}
              pm_getPaymasterData:
                summary: ERC-7677 final paymaster data (paymaster)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: pm_getPaymasterData
                  params:
                    - sender: '0x1234567890123456789012345678901234567890'
                      nonce: '0x0'
                      callData: '0x'
                    - '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
                    - '0x2105'
                    - {}
              zd_getERC20PaymasterAddress:
                summary: Resolve the ERC-20 paymaster address (paymaster)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: zd_getERC20PaymasterAddress
                  params:
                    - entryPoint: '0x0000000071727De22E5E9d8BAf0edAc6f37da032'
                      gasToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
              eth_chainId:
                summary: Return the chain ID (bundler)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: eth_chainId
                  params: []
      responses:
        '200':
          description: >-
            JSON-RPC response envelope. HTTP 200 is returned for both successful
            results and JSON-RPC errors; inspect the "result" and "error" fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
              examples:
                userOpHash:
                  summary: eth_sendUserOperation result (UserOp hash)
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result: '0xdead00000000000000000000000000000000000000000000000000000000beef'
                gasEstimate:
                  summary: eth_estimateUserOperationGas result
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      preVerificationGas: '0xc350'
                      verificationGasLimit: '0x33450'
                      callGasLimit: '0x88b8'
                sponsorResult:
                  summary: zd_sponsorUserOperation result
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    result:
                      paymaster: '0x0000000000000039cd5e8aE05257CE51C473ddd1'
                      paymasterData: '0x00000000...'
                      preVerificationGas: '0xc350'
                      verificationGasLimit: '0x33450'
                      callGasLimit: '0x88b8'
                error:
                  summary: JSON-RPC error envelope
                  value:
                    jsonrpc: '2.0'
                    id: 1
                    error:
                      code: -32602
                      message: Invalid params
components:
  schemas:
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
        - id
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: integer
            - type: string
        method:
          type: string
          description: >-
            The JSON-RPC method. Bundler methods: eth_sendUserOperation,
            eth_estimateUserOperationGas, eth_getUserOperationByHash,
            eth_getUserOperationReceipt, eth_supportedEntryPoints, eth_chainId.
            Paymaster methods: zd_sponsorUserOperation, pm_sponsorUserOperation,
            pm_getPaymasterStubData, pm_getPaymasterData,
            zd_getERC20PaymasterAddress.
          enum:
            - eth_sendUserOperation
            - eth_estimateUserOperationGas
            - eth_getUserOperationByHash
            - eth_getUserOperationReceipt
            - eth_supportedEntryPoints
            - eth_chainId
            - zd_sponsorUserOperation
            - pm_sponsorUserOperation
            - pm_getPaymasterStubData
            - pm_getPaymasterData
            - zd_getERC20PaymasterAddress
        params:
          type: array
          description: Positional parameters; shape depends on the method.
          items: {}
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
        - id
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          oneOf:
            - type: integer
            - type: string
        result:
          description: Present on success; shape depends on the method.
        error:
          $ref: '#/components/schemas/JsonRpcError'
    JsonRpcError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          description: Optional error detail.
    UserOperation:
      type: object
      description: >-
        ERC-4337 UserOperation. Field set differs between EntryPoint v0.6 and
        v0.7 (v0.7 splits gas/paymaster fields and uses packed accountGasLimits
        on-chain); SDK-built operations carry the appropriate fields.
      properties:
        sender:
          type: string
        nonce:
          type: string
        factory:
          type: string
        factoryData:
          type: string
        callData:
          type: string
        callGasLimit:
          type: string
        verificationGasLimit:
          type: string
        preVerificationGas:
          type: string
        maxFeePerGas:
          type: string
        maxPriorityFeePerGas:
          type: string
        paymaster:
          type: string
        paymasterVerificationGasLimit:
          type: string
        paymasterPostOpGasLimit:
          type: string
        paymasterData:
          type: string
        signature:
          type: string