Gas sponsorship paymasters

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 and Account abstraction model. For the operator view in the dapp, see Account Abstraction Control Center. For transaction status polling after a queued mutation, see Transaction tracking.

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. 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

Start by listing paymasters for the active system, then read the EntryPoint deposit for the paymaster your integration will monitor.

curl --request GET \
  "$DALP_API_URL/api/v2/system/paymasters" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Example response:

{
  "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:

curl --request GET \
  "$DALP_API_URL/api/v2/system/paymasters/0x1111111111111111111111111111111111111111/balance" \
  --header "X-Api-Key: $DALP_API_TOKEN"

{
  "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

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 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.

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:

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

Use the balance endpoint to read the paymaster EntryPoint deposit. The returned depositBalance is a wei-denominated integer string.

curl --request GET \
  "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/balance" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Example response:

{
  "data": {
    "address": "0x1111111111111111111111111111111111111111",
    "depositBalance": "1000000000000000000"
  },
  "links": {
    "self": "/v2/system/paymasters/0x1111111111111111111111111111111111111111/balance"
  }
}

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.

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.

{
  "transactionId": "8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a"
}

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:

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:

{
  "data": {
    "enabled": false
  },
  "links": {
    "self": "/v2/system/paymasters/config"
  }
}

Update the setting:

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

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.

curl --request GET \
  "$DALP_API_URL/api/v2/system/paymasters/$PAYMASTER_ADDRESS/signer-key/status" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Example response:

{
  "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:

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

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.