# Gas sponsorship paymasters Source: https://docs.settlemint.com/docs/developers/developer-guides/api-integration/system-paymasters List system paymasters, check funding, manage sponsorship configuration, and rotate paymaster signer keys through the DALP API. System paymaster endpoints let integrations inspect and operate Account Abstraction paymasters for the active system. Use them when your integration needs to monitor gas sponsorship, fund the paymaster EntryPoint deposit, or rotate the sponsorship ticket signer key. The API operates existing paymasters; paymaster deployment stays with the system add-on flow. For the concept model, see [Paymasters and gas sponsorship](/docs/architects/architecture/concepts/paymasters-and-gas-sponsorship) and [Account abstraction model](/docs/architects/architecture/concepts/account-abstraction). For the operator view in the dapp, see [Account Abstraction Control Center](/docs/operators/user-guides/platform-setup/account-abstraction-control-center). For transaction status polling after a queued mutation, see [Transaction tracking](/docs/developers/developer-guides/operations/transaction-tracking). ## Prerequisites [#prerequisites] Before you call these endpoints, use an authenticated organization context. Server integrations can authenticate REST calls with the `X-Api-Key` header shown in the examples. Browser or RPC integrations can use an authenticated user session through the standard cookie or authorization flow. The organization also needs an active system with Account Abstraction support. The list and configuration endpoints can be called before any paymaster is indexed. Address-specific balance and funding calls return a not-found error until the paymaster appears in `GET /api/v2/system/paymasters`. Signer-key calls are narrower: they require the address to belong to a sponsorship-ticket signer paymaster, so a non-signer paymaster can still return not found even after it appears in the list. Funding and signer-key rotation need the operator roles listed in [Access and permissions](#access-and-permissions). They also need wallet verification for user-session calls because those calls queue on-chain work. Read-only balance and configuration calls are useful for monitoring, but they do not prove that future UserOperations are sponsored. Sponsorship depends on the organization setting, the paymaster EntryPoint deposit, and the Account Abstraction transaction path. ## Quickstart [#quickstart] Start by listing paymasters for the active system, then read the EntryPoint deposit for the paymaster your integration will monitor. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` Example response: ```json { "data": [ { "address": "0x1111111111111111111111111111111111111111", "system": "0x2222222222222222222222222222222222222222", "factory": "0x3333333333333333333333333333333333333333", "createdAt": "2026-05-24T08:00:00.000Z" } ], "meta": { "total": 1 }, "links": { "self": "/v2/system/paymasters?sort=-createdAt&page[offset]=0&page[limit]=50", "first": "/v2/system/paymasters?sort=-createdAt&page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/system/paymasters?sort=-createdAt&page[offset]=0&page[limit]=50" } } ``` Then check the EntryPoint deposit: ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters/0x1111111111111111111111111111111111111111/balance" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": { "address": "0x1111111111111111111111111111111111111111", "depositBalance": "1000000000000000000" }, "links": { "self": "/v2/system/paymasters/0x1111111111111111111111111111111111111111/balance" } } ``` `depositBalance` is a wei-denominated integer string. Monitor it as the spendable EntryPoint deposit for this paymaster, not as a fiat amount or accounting balance. ## Endpoints [#endpoints] | Endpoint | Use it for | | ------------------------------------------------------------ | ------------------------------------------------------------- | | `GET /api/v2/system/paymasters` | List paymasters registered for the active system. | | `GET /api/v2/system/paymasters/{address}/balance` | Read the paymaster EntryPoint deposit balance. | | `POST /api/v2/system/paymasters/{address}/deposits` | Fund the paymaster EntryPoint deposit. | | `GET /api/v2/system/paymasters/{address}/signer-key/status` | Read the current signer address and last rotation timestamp. | | `POST /api/v2/system/paymasters/{address}/signer-key/rotate` | Rotate the sponsorship ticket signer key. | | `GET /api/v2/system/paymasters/config` | Read whether paymaster sponsorship is enabled. | | `PUT /api/v2/system/paymasters/config` | Enable or disable paymaster sponsorship for the organization. | Read endpoints use DALP response envelopes: single-resource responses return `data` and `links.self`, and the paymaster list returns `data`, `meta.total`, and pagination links. Mutations that submit on-chain work return the standard asynchronous blockchain mutation response so callers can poll the queued transaction. ## List paymasters [#list-paymasters] List paymasters before calling address-specific endpoints. The list supports collection filters for `address`, `factory`, and `createdAt`. You can sort by `createdAt`, `address`, or `factory`; the default sort is newest first by `createdAt`. Address filters are normalized before DALP applies them, so integrations can pass checksum or lowercase addresses. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` The response uses the collection envelope with `meta.total` and pagination links for the current query. Each item includes: | Field | Meaning | | ----------- | ----------------------------------------------------- | | `address` | Paymaster contract address. | | `system` | System address the paymaster belongs to, or `null`. | | `factory` | Factory address that created the paymaster. | | `createdAt` | Registration timestamp for the indexed paymaster row. | Address-specific endpoints return a not-found error when the supplied address is not indexed for the active system. If you just installed a paymaster, list paymasters again after indexing has caught up. ## Check funding [#check-funding] Use the balance endpoint to read the paymaster EntryPoint deposit. The returned `depositBalance` is a wei-denominated integer string. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/balance" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` Example response: ```json { "data": { "address": "0x1111111111111111111111111111111111111111", "depositBalance": "1000000000000000000" }, "links": { "self": "/v2/system/paymasters/0x1111111111111111111111111111111111111111/balance" } } ``` ## Fund the paymaster [#fund-the-paymaster] Deposit requests fund the paymaster EntryPoint deposit. Send `amount` as a positive wei-denominated integer string. DALP rejects zero, negative, non-numeric, and scientific-notation values. ```bash curl --request POST \ "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/deposits" \ --header "X-Api-Key: $DALP_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "amount": "1000000000000000000" }' ``` Funding requires the paymaster to be indexed for the active system before DALP queues the on-chain deposit transaction. The queued call deposits to the configured EntryPoint for the active network. If the EntryPoint cannot be resolved from the network directory, DALP returns an error instead of queuing the deposit. API-key sessions skip wallet verification. User-session deposits require a configured wallet-verification method, such as PIN code, secret code, or one-time password, and the request must include the matching `walletVerification` payload. A deposit can return a queued blockchain mutation instead of the final balance immediately. In that case, poll the returned status URL until the transaction reaches its terminal state. ```json { "transactionId": "8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a", "status": "QUEUED", "statusUrl": "/api/v2/transaction-requests/8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a" } ``` ## Manage sponsorship configuration [#manage-sponsorship-configuration] The paymaster configuration endpoint controls whether Account Abstraction user operations attach paymaster sponsorship for the organization. It does not create or fund a paymaster by itself. Read the current setting before changing it: ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters/config" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` The response wraps the current organization-level flag in the standard `data` and `links.self` envelope: ```json { "data": { "enabled": false }, "links": { "self": "/v2/system/paymasters/config" } } ``` Update the setting: ```bash curl --request PUT \ "$DALP_API_URL/api/v2/system/paymasters/config" \ --header "X-Api-Key: $DALP_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "enabled": true }' ``` `GET` returns `enabled: false` when no organization configuration row exists yet. `PUT` stores the explicit setting for the organization. Admin, System manager, and Gas manager roles can change the sponsorship setting and fund the paymaster deposit. Signer-key rotation is narrower: only Admin and System manager roles can rotate the key. Changing the sponsorship setting does not rotate the paymaster signer key. Use the signer-key endpoint when the signing key itself must change. ## Rotate the signer key [#rotate-the-signer-key] The signer key signs sponsorship tickets for one signer-type paymaster. Use the status endpoint to inspect the signer address and rotation timestamp. A paymaster that is only visible in the paymaster list is not enough for these routes; the address must belong to the active system and expose the sponsorship-ticket signer type. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/signer-key/status" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` Example response: ```json { "data": { "signerAddress": "0x2222222222222222222222222222222222222222", "rotatedAt": "2026-05-12T00:00:00.000Z" }, "links": { "self": "/v2/system/paymasters/0x1111111111111111111111111111111111111111/signer-key/status" } } ``` Both fields can be `null` when no signer key has been set or the current signer address cannot be resolved from the configured signer provider. DALP does not expose private key material in the status response, and status lookup failures are reported without leaking the stored signer-key value. Rotate the signer key when you need to replace the sponsorship ticket signer for a paymaster: ```bash curl --request POST \ "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/signer-key/rotate" \ --header "X-Api-Key: $DALP_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{}' ``` API-key signer-key rotation uses the `X-Api-Key` header shown above. User-session signer-key rotation must include wallet verification. DALP prepares a new signer, queues the on-chain signer update, and stores the new paymaster-scoped signing key after the update succeeds. The route rejects concurrent rotations for the same paymaster while a rotation is already being prepared or confirmed. In-flight user operations signed with the old key can be rejected after the signer switches. Like deposits, signer-key rotation can return a queued blockchain mutation. Poll the returned status URL before treating the new signer as active in an integration runbook. ## Access and permissions [#access-and-permissions] The API follows the same paymaster role boundaries as the dapp control center. The paymaster list is available to authenticated organization members. Balance and configuration reads require an authenticated organization member with a wallet. Signer-key status, transaction changes, and configuration changes require an operator role. * List paymasters: any authenticated organization member. * Read paymaster balance: authenticated organization member with a wallet. * Read sponsorship configuration: authenticated organization member with a wallet. * Read signer key status: Admin, System manager, Auditor, or Gas manager. * Fund the paymaster EntryPoint deposit: Admin, System manager, or Gas manager. * Enable or disable paymaster sponsorship: Admin, System manager, or Gas manager. * Rotate the signer key: Admin or System manager. Use the dapp control center when an operator needs to confirm role access visually before calling the API from an integration.