Gas treasury runway and fee split

When DALP sponsors gas for advanced accounts, the cost comes out of a funded treasury. The gas treasury runway endpoints report how much that treasury holds, how fast it is burning, and how many days of sponsorship remain. An operator finds out about an empty gas tank from a dashboard rather than from failed user operations. The same surface tunes the fee split that refills the treasury from transaction fees, sets the runway warning thresholds your monitoring reads, and recovers balances that landed on the splitter contract.

Use these endpoints when your integration needs to watch sponsored-gas runway, adjust how much of each transaction fee flows back to the paymaster, or pull stranded funds out of the splitter.

Requires: advanced accounts enabled for the deployment.

For the funding, sponsorship, and signer-key surface of the paymaster itself, see Gas sponsorship paymasters. The in-house bundler that submits the sponsored operations is documented in Bundler. To poll transaction status after a queued mutation, see Transaction tracking.

How the treasury refills

Advanced accounts let users transact without holding native gas. When a bundle settles, the EntryPoint pays out a refund, and DALP routes that refund between a bundler buffer and the paymaster deposit that funds sponsorship. While sponsorship is enabled, the bps value sets the bundler's share of each refund in basis points from 0 to 10000, and the remainder is deposited to the paymaster to refill the gas tank. A lower bps sends more of each refund back to the treasury; bps of 0 routes the entire refund to the paymaster deposit, and bps of 10000 sends it all to the bundler. While sponsorship is disabled, the full refund goes to the bundler and none reaches the treasury.

Runway is the projection of how long the current balances last at the recent burn rate. DALP samples treasury balances over time, measures the native spend across the trailing seven days, and divides remaining balance by that burn to estimate runwayDays. When usage is too low to establish a burn rate, runway is reported as null rather than as an infinite or zero value.

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 advanced accounts support, and the gas treasury (the refund splitter) must be installed for the organization. The status and threshold reads respond before the treasury is installed: status returns a not-installed snapshot with zeroed balances, and the threshold read returns the stored or default warning levels. The configuration and recovery mutations require the treasury to be installed and return a not-installed error until it is.

Status and history reads also depend on indexed prerequisites. Reading live runway needs the paymaster, bundler, and EntryPoint addresses to be resolved for the active network. Until indexing and configuration catch up, the live status read returns a dependency error you can retry rather than a partial result.

Quickstart

Read the current treasury status for the active organization. The status read is the one call most monitoring starts from.

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

Example response:

{
  "data": {
    "installed": true,
    "address": "0x1111111111111111111111111111111111111111",
    "bps": 2500,
    "sponsorshipEnabled": true,
    "paymasterDeposit": "1200000000000000000",
    "bundlerBalance": "800000000000000000",
    "refundSplitterBalance": "50000000000000000",
    "runwayDays": "42"
  },
  "links": {
    "self": "/v2/system/refund-splitter/status"
  }
}

Read runwayDays as the headline health signal: it is the estimated number of days the current gas treasury lasts at the recent burn rate, returned as a decimal string or null when no burn rate is available. Treat the balance fields as wei-denominated integer strings, not fiat amounts.

When the treasury is not installed for the organization, the same endpoint returns a zeroed snapshot so monitoring code can branch on one field:

{
  "data": {
    "installed": false,
    "address": null,
    "bps": 0,
    "sponsorshipEnabled": false,
    "paymasterDeposit": "0",
    "bundlerBalance": "0",
    "refundSplitterBalance": "0",
    "runwayDays": null
  },
  "links": {
    "self": "/v2/system/refund-splitter/status"
  }
}

Endpoints

Read endpoints use DALP response envelopes: single-resource responses return data and links.self, and the history list returns data, meta, and pagination links. The on-chain mutations that change the fee split, toggle sponsorship, or recover a balance return the standard asynchronous blockchain mutation response, so callers poll the queued transaction to confirm the new state. The threshold update is the exception: it stores organization settings synchronously and returns the same single-resource envelope as the threshold read, with no transaction to poll.

Read runway history

The history endpoint returns dated runway snapshots so you can chart how the gas treasury trends rather than reading a single instant. Each record captures the balances, the trailing seven-day native burn, and the runway estimate at that point.

curl --request GET \
  "$DALP_API_URL/api/v2/system/refund-splitter/history?days=30" \
  --header "X-Api-Key: $DALP_API_TOKEN"

Use days to bound the window from 1 to 365, defaulting to 30. The window also caps the page size, so a narrow window returns a correspondingly small page. Records sort newest first by default; sort and paginate with the standard collection parameters.

Example response:

{
  "data": [
    {
      "snapshotAt": "2026-06-20T00:00:00.000Z",
      "snapshotAtBlock": "21500000",
      "paymasterDeposit": "1200000000000000000",
      "bundlerBalance": "800000000000000000",
      "refundSplitterBalance": "50000000000000000",
      "burn7dWei": "300000000000000000",
      "runwayDays": "42"
    }
  ],
  "meta": {
    "total": 1
  },
  "links": {
    "self": "/v2/system/refund-splitter/history?days=30&sort=-snapshotAt&page[offset]=0&page[limit]=30",
    "first": "/v2/system/refund-splitter/history?days=30&sort=-snapshotAt&page[offset]=0&page[limit]=30",
    "prev": null,
    "next": null,
    "last": "/v2/system/refund-splitter/history?days=30&sort=-snapshotAt&page[offset]=0&page[limit]=30"
  }
}

The list envelope always returns the full pagination link set. prev is null on the first page and next is null on the last page; self, first, and last are always present.

Each record includes:

Manage runway thresholds

Thresholds drive runway alerting. They define the runway-days levels at which monitoring should warn and at which monitoring should escalate to critical. Read the current values before changing them.

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

{
  "data": {
    "warnDays": 14,
    "criticalDays": 7
  },
  "links": {
    "self": "/v2/system/refund-splitter/thresholds"
  }
}

Update them with a PUT. Both values are positive integers, and criticalDays must be lower than warnDays so the critical level fires after the warning level as runway shrinks. A request that violates that order returns DALP-0651.

curl --request PUT \
  "$DALP_API_URL/api/v2/system/refund-splitter/thresholds" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "warnDays": 14,
    "criticalDays": 7
  }'

The threshold update stores the values for the organization and returns them in the same envelope. It does not submit on-chain work.

Set the fee split

The fee-split allocation sets the bundler's share of each refund while sponsorship is enabled. The remainder flows back into the gas treasury, so a lower bps refills the treasury faster. Send bps as an integer from 0 through 10000. A value outside that range returns DALP-0650.

curl --request PUT \
  "$DALP_API_URL/api/v2/system/refund-splitter/bps" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "bps": 2500
  }'

Setting the split submits an on-chain update. The response is a queued blockchain mutation, so poll the returned status URL until the transaction reaches its terminal state before treating the new split as active.

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

Set the sponsorship flag

The sponsorship endpoint toggles the on-chain flag that governs whether refunds are split. While the flag is enabled, each refund splits by bps between the bundler and the paymaster deposit. While it is disabled, the full refund goes to the bundler and the treasury is not refilled. Send enabled as a boolean.

curl --request PUT \
  "$DALP_API_URL/api/v2/system/refund-splitter/sponsorship" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "enabled": true
  }'

Like the fee-split update, this submits on-chain work and returns a queued blockchain mutation to poll. The treasury must be installed for the organization, or the request returns DALP-0648.

Recover stranded balances

Recovery endpoints pull funds off the splitter contract to an address you control, for the case where a balance lands on the splitter and should be moved. Send amount as a positive wei-denominated integer string. DALP rejects zero, negative, non-numeric, and scientific-notation values.

Recover a native balance:

curl --request POST \
  "$DALP_API_URL/api/v2/system/refund-splitter/recover-native" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "0x2222222222222222222222222222222222222222",
    "amount": "1000000000000000000"
  }'

Recover an ERC20 balance by adding the token address:

curl --request POST \
  "$DALP_API_URL/api/v2/system/refund-splitter/recover-erc20" \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "0x3333333333333333333333333333333333333333",
    "to": "0x2222222222222222222222222222222222222222",
    "amount": "1000000000000000000"
  }'

Both recoveries submit on-chain work and return a queued blockchain mutation. Poll the returned status URL before treating the funds as moved.

Errors

Access and permissions

The API follows the same treasury role boundaries as the Console. Reads are available to operator and audit roles; configuration changes require an operator role with treasury authority; balance recovery is the narrowest.

• Read status, history, and thresholds: Admin, System manager, Auditor, or Gas manager.
• Set the fee split, sponsorship flag, or thresholds: Admin, System manager, or Gas manager.
• Recover native or ERC20 balances: Admin or System manager.

User-session mutations queue on-chain work, so they also need wallet verification. API-key sessions skip wallet verification.