The Gas Manager Admin API enables your to programmatically create, update, and manage gas manager policies for your app. Gas manager policies define how and when you will sponsor your user’s gas fees.
The Gas Manager Admin API allows you to manage policies for Alchemy Paymaster. This guide will walk you through the process of creating, retrieving, updating, and deleting policies using the Gas Manager Admin API.
NOTE
The Gas Manager Admin API is currently in a Limited Private Beta phase. Access is restricted to a selected group of users who have been granted permission to test and provide feedback. The functionality and behavior of these methods may change before the public release. Please note that availability, performance, and support are not guaranteed during this period.
If you are interested in receiving updates on this product, please sign up here. We will keep you informed as the product progresses and becomes more widely accessible. Thank you for your interest.
By using the Gas Manager Admin API, you can define policies for how your Alchemy Apps should sponsor gas for users. There are specific rules you can set that limit how users of your app can qualify for gas sponsorship. To actually use the sponsorships themselves, consult the Gas Manager Coverage API reference.
Getting Started
To get started, first create an Alchemy app on the dashboard. Make sure the network for this app is set to the network you will be sponsoring gas on. This will be where all requests are sent, either from your services or the end-user’s web app.
Then, create a gas manager policy connected to this app. In the dashboard, this can be done under the “Paymaster” tab. To do so via the API, send a request to the Create Policy endpoint.
Creating a policy
To create the gas manager policy, send a POST request to https://manage.alchemy.com/api/paymaster/policy.
The request headers should have the Authorization field set to Bearer <token>, where <token> is replaced with your management API key.
The body should contain:
{
"app_id": "app_sid", // String ID of the app
"rules": {
"max_spend_usd": "5000.00",
"max_spend_per_sender_usd": "100.00",
"max_count_global": "100",
"max_count_per_sender": "2",
"sender_allowlist": [
"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"0x70997970c51812dc3a010c7d01b50e0d17dc79c8"
],
"sender_blocklist": [
"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"0x70997970c51812dc3a010c7d01b50e0d17dc79c8"
],
"start_time": "1674228753", // Unix Timestamp
"end_time": "1679340742", // Unix Timestamp
"max_spend_per_uo_usd": "20.00",
"sponsorship_expiry_ms": "86400000" // millis from signing
}
}
The app id should be the string id of the app you would like to connect this policy to. To find it, view the URL of the app you’ve created on the dashboard, i.e. https://dashboard.alchemy.com/apps/<app_sid>.
The rules fields define the criteria used by the policy when deciding whether or not a sponsor a user operation. All of them are optional except sponsorship_expiry_ms, which must be set to a value between 60000 (1 minute) and 86400000 (1 day).
To view a full list of all supported rules, please see the Rulesreference.
Activating your policy
After your policy is created, it will initially be in the “inactive” state, meaning it is not ready to sponsor user operations yet. This can be confirmed by viewing the response to the create policy request, or calling GET https://manage.alchemy.com/api/paymaster/policy/:id. It should return:
{
"data": {
"policy": {
"policy_id": "<policy_id>",
"app_id": "<app_id>"
"status": "inactive",
"rules": {rules_object}
}
}
}
Make note of the returned policy ID. To activate your policy, send a request to the update policy status endpoint. This is a PUT request at https://manage.alchemy.com/api/paymaster/policy/:id/status.
This request should use the same Authorization header as before, with the Authorization field set to Bearer <token>, where the <token> is your management API key.
The body should contain:
{
"status": "active"
}
If successful, the response should contain the policy with the status field now set to active.
Using your policy
NOTE
This step may change as we update the Alchemy SDK and the sponsorship API.
To use the policy, your app should send a JSON-RPC request to your app using the alchemy_requestPaymasterAndData method. This will be at the endpoint https://<NETWORK>.g.alchemy.com/v2/<APP_API_KEY>, where <NETWORK> depends on which network your app was created with and <APP_API_KEY> is your app’s API key.
First, prepare your user operation with all fields except for signature and paymasterAndData. Then, send your partial user operation, along with the ERC-4337 EntryPoint you wish to use, using the JSON-RPC method alchemy_requestPaymasterAndData. An example request would look like:
{
id: 1,
jsonrpc: '2.0',
method: 'alchemy_requestPaymasterAndData',
params: [
{
policyId: '437b72ae-c19b-4fe2-a2ea-daf2873108cc',
entryPoint: '0x0576a174D229E3cFA37253523E645A78A0C91B57',
paymasterTrackedSenderNonce: '0x1',
userOperation: {
sender: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
nonce: 1,
initCode: '0x',
callData: '0xf86d808504a817c8008252089435673546dac357595acd835353535da7c35353535880de0b6b3a7640000801ca0e0d2e3f3d8de8a0c9f25d0b02c7a8a91e7e1c818e6f37a49d8b04f9a9a96a1a0620a6c8d95e0f289bfbf2b3d3e476de6b9bc6d0e974c06f1e4de5be7c5ef0e10',
callGasLimit: 50000,
verificationGasLimit: 30000,
preVerificationGas: 2000,
maxFeePerGas: 60,
maxPriorityFeePerGas: 3
}
}
]
}
The response, if successful, should contain the data you need for the paymasterAndData field. A successful response would look like:
{
"id": 1,
"jsonrpc": "2.0",
"result": {
// The 0x-prefixed hex string for the user to put into the UO's paymasterAndData field. Contains:
"paymasterAndData": "0xc03aac639bb21233e0139381970328db8bceeb67fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000007aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1c"
}
}
Then, that field can be included in the useroperation sent to Alchemy’s bundler service via eth_sendUserOperation [eth_sendUserOperation.
API Schema
- Standard: REST
- Transport: HTTPS
- Endpoint: https://manage.alchemy.com/
- Authentication: Only dashboard access for now, programmatic API access coming soon.
Shared Format
The Paymaster Admin API has the following data envelope for all responses.
{
"data": {}, // response
"error": {
"msg": "<error_msg>"
}
}
On success with no data field, an empty response will be returned with status code 204.
Rules
The rules for a gas manager policy are formatted as:
{
"max_spend_usd": "5000.00",
"max_spend_per_sender_usd": "100.00",
"max_count_global": "100",
"max_count_per_sender": "2",
"sender_allowlist": [
"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"0x70997970c51812dc3a010c7d01b50e0d17dc79c8"
],
"sender_blocklist": [
"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
"0x70997970c51812dc3a010c7d01b50e0d17dc79c8"
],
"start_time": "1674228753", // Unix Timestamp
"end_time": "1679340742", // Unix Timestamp
"max_spend_per_uo_usd": "20.00",
"sponsorship_expiry_ms": "86400000" // millis from signing
}
The rules start_time and sponsorship_expiry_ms are required, and all others are optional.
Policy
Each policy is represented as:
{
"policy_id": "<policy_id>",
"app_id": "<app_id>"
"status": "active" | "inactive",
"rules": {rules_object}
}