📘

Paymaster API Reference

link

Introduction

This tutorial explains how to use the ZAN AA Paymaster service. Please follow the steps below:

1. Obtain an API Key
2. Create a policy
3. Activate the policy
4. Request the PaymasterAndData
5. Send the UserOperation

Steps

Step1: Obtain an API Key

First, you need to register on the ZAN platform and navigate to the Node Service console to create an API Key. Refer to the tutorial for guidance.

Step2: Create a policy

The relationship between users, API Keys, and policies is illustrated in Figure 1. Users can create multiple API Keys through the Node Service console, and each API Key can be used to create multiple paymaster policies for different blockchain networks. Ultimately, the expenses incurred by all policies will be aggregated to the user's account.

To create a policy, you can make the following call, which creates a paymaster policy on the ETH Sepolia network (chainId: 11155111). For detailed definitions of each field, please refer to the API Reference.

curl --request POST \
--url https://api.zan.top/paymaster/v1/policy/{yourAPIKey} \
-H "Content-Type: application/json" \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
    "policyName":"policyTest",
    "policyType":"sponsorship",
    "chainId":"11155111",
    "rules":{
      "validAfter":"1707205138",
      "validUntil":"1735660800",
      "sponsorshipExpiryMinutes":"10",
      "maxSpendPerAddress":"100000000000000000",
      "maxOperationsPerAddress":"1000",
      "maxSpend":"1000000000000000000",
      "maxOperations":"10000",
      "maxSpendPerUo":"100000000000000000",
      "accessControlType":"neither"
  }
}'

If the creation is successful, the policyId of the policy will be returned.

{"error":null,"data":{"policyId":"111111aaaaaa-1111-2222-3333-1234567890ab"}}

Using the policyId, you can perform operations such as adding, deleting, modifying, and querying policy information, as well as changing its status. For detailed instructions, see the API Reference.

Step3: Activate the policy

The initial state of the created policy is inactive. To use the policy to pay execution gas for UserOperations, you need to update the policy's status to active. You can do so by calling the following method:

curl --request PUT \
--url https://api.zan.top/paymaster/v1/policy/111111aaaaaa-1111-2222-3333-1234567890ab/status \
-H "Content-Type: application/json" \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
  "status":"active"
}'

Upon successful status change, the result will be returned as follows:

{"error":null,"data":{"policyId":"111111aaaaaa-1111-2222-3333-1234567890ab"}}

Besides activating the policy, if you wish to pause the policy's payment activity, you can also update the policy's status to stopped.

Step4: Request the PaymasterAndData

You can now officially use the policyId to request PaymasterAndData. The process of a user constructing a valid UserOperation using the paymaster service should look like as shown in Figure 2.

Please note, when calling eth_estimateUserOperationGas to estimate the gas consumption of executing a UserOperation, it's important to use dummyPaymasterAndDatato populate the paymasterAndData field for accurate estimation.

#eth-sepolia
dummyPaymasterAndData: 0x7915e08ec9e1e4b08b1ac0b086a568fe5d3ba3220000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006575be1ff188fa178364105814dc4bf270fc20175857d63661d18f12ae3a39d1ae13562e5fa5e68582e8669243e2f63e5b2b22b878ca24e987426558cc280c94556f1e921b

To obtain a valid paymasterAndData, send the following request to the AA Paymaster. All parameters for the userOperation object should be the same as those used when calling the eth_estimateUserOperationGas API, except for callGasLimit, verificationGasLimit, and preVerificationGas which are the results returned by the eth_estimateUserOperationGas API.

curl --request POST \
--url https://api.zan.top/node/v1/eth/sepolia/{yourAPIKey} \
-H "Content-Type: application/json" \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "zan_requestPaymasterAndData",
      "params": {
        "policyId":"111111aaaaaa-1111-2222-3333-1234567890ab",
        "entryPoint":"0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
        "userOperation": {
      "initCode": "0x",
      "sender": "0x123...",//your sender address
      "nonce": "0x1",
      "callData": "0x123...",//your call data
      "maxFeePerGas": "0xaaa",
      "maxPriorityFeePerGas": "0xaaa",
      "callGasLimit": "0xaaa",
      "verificationGasLimit": "0xaaa",
      "preVerificationGas": "0xaaa"
    }
  }
}'

If the request is successful, the result will be returned as follows:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
     "paymasterAndData":"0x1230000000..."
     },
  "error":null
  }

Step5: Send the UserOperation

Fill in the paymasterAndData field of your UserOperation with the paymasterAndData returned by zan_requestPaymasterAndData, and you will obtain a valid UserOperation that has its gas paid for by the ZAN AA Paymaster. Send this UserOperation and wait for the transaction to be confirmed on the blockchain. For details on this part, refer to the Bundler section.

Other considerations

Our AA Paymaster service is currently in a trial phase. Users on the free plan have a monthly quota of 0.5 SepoliaETH to experience the Paymaster proxy payment service on the Ethereum Sepolia network.

If you need support for Paymaster service on other blockchain networks, or have any other custom requirements, please feel free to contact us through email, Telegram, Discord, or other channels for further discussion.