# Gas treasury runway and fee split Source: https://docs.settlemint.com/docs/api-reference/wallets/gas-treasury-runway Read gas treasury balances, runway days, and burn rate, set the fee-split allocation, manage runway warning thresholds, and recover stranded balances through the DALP API. 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](/docs/api-reference/wallets/system-paymasters). The in-house bundler that submits the sponsored operations is documented in [Bundler](/docs/api-reference/wallets/bundler). To poll transaction status after a queued mutation, see [Transaction tracking](/docs/developers/operations/transaction-tracking). ## How the treasury refills [#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 [#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 [#quickstart] Read the current treasury status for the active organization. The status read is the one call most monitoring starts from. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/refund-splitter/status" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` Example response: ```json { "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: ```json { "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 [#endpoints] | Endpoint | Use it for | | ---------------------------------------------------- | -------------------------------------------------------------------------- | | `GET /api/v2/system/refund-splitter/status` | Read current treasury balances, fee split, runway days, and install state. | | `GET /api/v2/system/refund-splitter/history` | Read dated runway snapshots with balances and trailing burn. | | `GET /api/v2/system/refund-splitter/thresholds` | Read the runway warning and critical day thresholds. | | `PUT /api/v2/system/refund-splitter/thresholds` | Set the runway warning and critical day thresholds. | | `PUT /api/v2/system/refund-splitter/bps` | Set the bundler share of each refund in basis points. | | `PUT /api/v2/system/refund-splitter/sponsorship` | Enable or disable the on-chain sponsorship flag. | | `POST /api/v2/system/refund-splitter/recover-native` | Recover a native balance from the splitter contract. | | `POST /api/v2/system/refund-splitter/recover-erc20` | Recover an ERC20 balance from the splitter contract. | 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 [#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. ```bash 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: ```json { "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: | Field | Meaning | | ----------------------- | -------------------------------------------------------------- | | `snapshotAt` | Timestamp the record was taken. | | `snapshotAtBlock` | Block height at that point, as an integer string. | | `paymasterDeposit` | Paymaster EntryPoint deposit, in wei. | | `bundlerBalance` | Bundler native balance, in wei. | | `refundSplitterBalance` | Splitter contract native balance, in wei. | | `burn7dWei` | Native spend across the trailing seven days, in wei. | | `runwayDays` | Estimated runway at that point, as a decimal string or `null`. | ## Manage runway thresholds [#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. ```bash curl --request GET \ "$DALP_API_URL/api/v2/system/refund-splitter/thresholds" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "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`. ```bash 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 [#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`. ```bash 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. ```json { "transactionId": "8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a", "status": "QUEUED", "statusUrl": "/api/v2/transaction-requests/8f1f5e3a-8e39-4c53-9d1a-9a3e0b5f2c7a" } ``` ## Set the sponsorship flag [#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. ```bash 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 [#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: ```bash 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: ```bash 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 [#errors] | Code | Meaning | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `DALP-0648` | The gas treasury must be installed for the organization before this mutation can proceed. | | `DALP-0649` | The live runway status could not be read because a prerequisite or on-chain read failed. Retry once the indexer and RPC provider are healthy. | | `DALP-0650` | The fee-split value is outside the supported 0 to 10000 range. | | `DALP-0651` | The critical threshold is not lower than the warning threshold. | ## Access and permissions [#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.