Query gas spend

Query gas credits charged per transaction and in total across wallets for monitoring sponsorship usage

The following functionality exists for wallets reconstituted server-side. More on Privy architecture here

Your app can see the Privy gas credits charged for sponsored gas in two ways:

• Per transaction: each sponsored transaction and wallet action step reports the gas credits charged for it.
• Across wallets: the GET /v1/apps/gas_spend endpoint totals the gas credits charged across a set of wallets over a given time range.

This is useful for tracking gas credit consumption per wallet, reconciling costs, and building internal usage dashboards.

Per transaction

Sponsored transactions include gas_credits_charged, the gas credits charged as a value and currency pair. The field is returned by:

• Get transaction (GET /v1/transactions/{transaction_id}), and lookups by reference ID.
• Each step of a wallet action, when fetched with ?include=steps.

The field may be null on reads made immediately after confirmation. Its value is always "0" on sponsored testnet transactions.

Response

{
  "id": "6f9cc5aa-dfcf-4bf0-bd50-a43429cf5ee3",
  "wallet_id": "qvdqj2xspqpbf4cosvrcmjd6",
  "caip2": "eip155:4217",
  "transaction_hash": "0x6f95cf5ad71e2e93062926f72a4bb8f23f73d2c0d941ef3a8d52f96baf0b0f72",
  "status": "confirmed",
  "created_at": 1769556582588,
  "sponsored": true,
  "reference_id": null,
  "gas_credits_charged": {
    "value": "0.001543",
    "currency": "usd"
  }
}

Transaction webhooks don’t include gas_credits_charged, and the field on wallet action webhook steps may still be null when the webhook fires. Fetch the transaction or wallet action directly for up-to-date gas data.

Across wallets

The total covers both RPC transactions and wallet actions.

Request

Send a GET request to https://api.privy.io/v1/apps/gas_spend with the following query parameters:

wallet_ids · string[] · required

Array of wallet IDs to query. Must contain between 1 and 100 IDs.

start_timestamp · number · required

Start of the time range in milliseconds (inclusive).

end_timestamp · number · required

End of the time range in milliseconds (exclusive). The range between start_timestamp and end_timestamp must not exceed 30 days.

Response

value · string

Total Privy gas credits charged in USD, as a decimal string (e.g. "12.345678").

currency · string

The currency of the value. Always "usd".

Example

curl --request GET \
  --url 'https://api.privy.io/v1/apps/gas_spend?wallet_ids=wallet-1&wallet_ids=wallet-2&start_timestamp=1712188800000&end_timestamp=1713398400000' \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'privy-app-id: <privy-app-id>'

Response

{
  "value": "12.345678",
  "currency": "usd"
}

Errors

Status	Description
400	Missing or invalid query parameters, or the date range exceeds 30 days
401	Missing or invalid app secret
404	One or more wallet IDs do not belong to the app