# System paymasters Source: https://docs.settlemint.com/docs/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. For the operator view in the dapp, see [Account Abstraction Control Center](/docs/user-guides/platform-setup/account-abstraction-control-center). For transaction status polling after a queued mutation, see [Transaction tracking](/docs/developer-guides/operations/transaction-tracking). ## 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. | Responses use the DALP single-resource or collection envelope with `data` and `links.self`. Mutations that submit on-chain work use the standard asynchronous blockchain mutation response. ## List paymasters [#list-paymasters] List paymasters before calling address-specific endpoints. The list supports collection filters for `address`, `factory`, and `createdAt`. The default sort is newest first by `createdAt`. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` 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 and requires wallet verification before DALP queues the on-chain deposit transaction. ## Manage sponsorship configuration [#manage-sponsorship-configuration] The paymaster configuration endpoint controls whether Account Abstraction user operations attach paymaster sponsorship for the organization. Read the current setting: ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/paymasters/config" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` 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. 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 paymaster. Use the status endpoint to inspect the signer address and rotation timestamp: ```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. 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 '{}' ``` Signer key rotation requires wallet verification. After the on-chain signer update succeeds, DALP stores the new paymaster-scoped signing key and returns the new signer address and rotation timestamp. In-flight user operations signed with the old key can be rejected after the signer switches. ## 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. | Operation | Roles | | --------------------------------------- | ----------------------------------------------- | | 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, and Gas manager | | Fund the paymaster EntryPoint deposit | Admin, System manager, and Gas manager | | Enable or disable paymaster sponsorship | Admin, System manager, and Gas manager | | Rotate the signer key | Admin and System manager | Use the dapp control center when an operator needs to confirm role access visually before calling the API from an integration.