openapi: 3.0.3
info:
  title: Alchemy Gas Manager Paymaster API
  description: The Alchemy Gas Manager API enables developers to sponsor gas fees for end users via the ERC-4337 Account Abstraction standard. Using a Gas Manager policy, developers can define rules for which transactions to sponsor, covering ETH gas fees so users never need to hold native tokens to interact with dApps. Supports gasless transactions, ERC-20 gas payments, and policy-based sponsorship controls.
  version: '1.0'
  contact:
    name: Alchemy Support
    url: https://www.alchemy.com/support
  x-generated-from: documentation
servers:
- url: https://manage.g.alchemy.com/api
  description: Alchemy Gas Manager Management API
- url: https://eth-mainnet.g.alchemy.com/v2/{apiKey}
  description: Ethereum Mainnet RPC
  variables:
    apiKey:
      default: your-api-key
      description: Your Alchemy API key.
tags:
- name: Paymaster
  description: Sponsor user operations via ERC-4337 paymaster endpoints.
paths:
  /sponsorUserOperation:
    post:
      operationId: sponsorUserOperation
      summary: Alchemy Gas Manager Sponsor User Operation
      description: Submits a user operation for gas sponsorship via the ERC-4337 paymaster. Returns a signed paymaster response that the bundler uses to cover gas fees on behalf of the user, enabling gasless transactions.
      tags:
      - Paymaster
      security:
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SponsorUserOperationRequest'
            examples:
              SponsorUserOperationRequestExample:
                summary: Default sponsorUserOperation request
                x-microcks-default: true
                value:
                  id: 1
                  jsonrpc: '2.0'
                  method: alchemy_requestGasAndPaymasterAndData
                  params:
                  - policyId: pol-abc123
                    entryPoint: '0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789'
                    userOperation:
                      sender: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
                      nonce: '0x0'
                      initCode: 0x
                      callData: 0x
      responses:
        '200':
          description: User operation sponsored successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SponsorUserOperationResponse'
              examples:
                SponsorUserOperation200Example:
                  summary: Default sponsorUserOperation 200 response
                  x-microcks-default: true
                  value:
                    id: 1
                    jsonrpc: '2.0'
                    result:
                      paymasterAndData: 0xabc123paymaster
                      preVerificationGas: '0x5208'
                      verificationGasLimit: '0x15f90'
                      callGasLimit: '0x9c40'
        '400':
          description: Bad request - operation rejected by policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse:
      type: object
      title: Error Response
      description: Standard error response.
      properties:
        error:
          type: string
          description: Error code.
          example: UNAUTHORIZED
        message:
          type: string
          description: Human-readable error message.
          example: Invalid API key.
        statusCode:
          type: integer
          description: HTTP status code.
          example: 401
    SponsorUserOperationRequest:
      type: object
      title: Sponsor User Operation Request
      description: JSON-RPC request to sponsor a user operation via the Gas Manager paymaster.
      properties:
        id:
          type: integer
          description: Request ID.
          example: 1
        jsonrpc:
          type: string
          description: JSON-RPC version.
          example: '2.0'
        method:
          type: string
          description: Alchemy paymaster method.
          example: alchemy_requestGasAndPaymasterAndData
        params:
          type: array
          description: Sponsorship parameters array.
          items: {}
    SponsorUserOperationResponse:
      type: object
      title: Sponsor User Operation Response
      description: JSON-RPC response for sponsored user operation requests.
      properties:
        id:
          type: integer
          example: 1
        jsonrpc:
          type: string
          example: '2.0'
        result:
          $ref: '#/components/schemas/SponsorUserOperationResult'
    SponsorUserOperationResult:
      type: object
      title: Sponsor User Operation Result
      description: Paymaster response data for a sponsored user operation.
      properties:
        paymasterAndData:
          type: string
          description: Encoded paymaster address and data for the user operation.
          example: 0xabc123paymaster
        preVerificationGas:
          type: string
          description: Pre-verification gas estimate in hexadecimal.
          example: '0x5208'
        verificationGasLimit:
          type: string
          description: Verification gas limit in hexadecimal.
          example: '0x15f90'
        callGasLimit:
          type: string
          description: Call gas limit in hexadecimal.
          example: '0x9c40'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for Gas Manager Management API authentication.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Alchemy-Token
      description: Alchemy API key for RPC endpoint authentication.