Gas health and operations

Gas healthCopy Anchor Link

GET /v1/wallets/{id}/gas returns the wallet's networkId, its latest balance, and its health against the wallet's active policy.

monitoring tells you how fresh that reading is: its status (healthy, degraded, or unknown), when the last successful read happened, and how many reads have failed in a row. A failed or suspect read never marks a wallet healthy and never creates an operation.

Ready to spend gasCopy Anchor Link

ready is stricter than health. It is true only when the wallet has an active policy, monitoring is healthy, and a recent reading is at or above the threshold. Check it before your system sends a transaction that spends the wallet's gas, such as a deposit sweep. When ready is false, readyBlockedBy says why:

NetworksCopy Anchor Link

GET /v1/networks lists the networks this deployment accepts for new wallets: each network's id, name, address family, environment (mainnet or testnet), and native asset (symbol and decimals). Today it lists Base. Register a wallet with one of these IDs as network; a network the list doesn't include is refused, with UNSUPPORTED_NETWORK when it is a network ID GasTanker knows but this deployment doesn't accept. Wallets and gas health readings carry their networkId; an operation's amounts are in its wallet's network.

AmountsCopy Anchor Link

Amounts are exact integer strings in the wallet network's native base units: wei for ETH on Base. The network's nativeAsset.decimals from GET /v1/networks converts them to whole units. Parse them as big integers, never as floating-point numbers. Policy thresholds and targets use the same units as the wallet's balance.

{ "requiredBaseUnits": "45800000000000000" }

Gas operationsCopy Anchor Link

POST /v1/gas/ensure asks GasTanker to check a wallet now.

• If the wallet isn't low, the response is { "status": "healthy", "operation": null } and nothing is recorded.
• If it is low, GasTanker records a gas operation, alerts your team, and returns the operation.
• A wallet has at most one active operation. If one is already active, you get that operation back instead of a new one.

{
  "id": "gasop_01...",
  "walletId": "wal_01...",
  "policyId": "pol_01...",
  "observedBalanceBaseUnits": "4200000000000000",
  "requiredBaseUnits": "45800000000000000",
  "status": "awaiting_source_liquidity"
}

requiredBaseUnits is the policy target minus the observed balance. Read an operation again with GET /v1/gas/operations/{id}.

Lifecycle todayCopy Anchor Link

created → validating → awaiting_source_liquidity → resolved or cancelled

The operation waits at awaiting_source_liquidity: GasTanker has recorded the shortfall and alerted your team, and someone on your team tops the wallet up. Automatic funding is coming soon. When it is enabled for your organization, the same operation continues through funding and confirmation, and your integration doesn't change.

An operation closes in one of two ways:

• resolved: a later reading is back at or above the policy threshold. If the wallet runs low again, GasTanker opens a new operation and alerts your team again.
• cancelled: someone stopped monitoring the wallet in the workspace.

PoliciesCopy Anchor Link

Policies are read-only through the API. Each change in the workspace creates a new, immutable revision, so GET /v1/policies/{id}/revisions is a full history. A policy is active, paused, or superseded; only an active policy is evaluated, and a paused one creates no new operations.

GET /v1/policies returns policies newest first, a page at a time: 100 by default, or set limit from 1 to 500. While the response's nextCursor is not null, pass it as cursor to read the next page:

curl "https://api.gastanker.xyz/v1/policies?limit=100&cursor=$NEXT_CURSOR" -H "X-API-Key: $GASTANKER_API_KEY"

A cursor stays valid as new policies are created, so following nextCursor reads each policy once.