Usage webhooks

Privy publishes a webhook each time it records a metered usage charge. Each event carries the amount and the wallet action that incurred it, so an app can attribute costs to users and flows without waiting for the monthly invoice.

Only accounts on postpaid billing receive these events. Contact [email protected] to enable postpaid billing for an account.

Event types

Event name	Type	Action
Gas sponsorship charge recorded	`usage.gas_sponsorship.recorded`	Privy recorded a charge for sponsored network gas.
Cross-chain swap charge recorded	`usage.cross_chain_fee.recorded`	Privy recorded a charge for a cross-chain transfer or swap.

Subscribing

In the Privy Dashboard, go to the Configuration > Webhooks page and select the events under Usage charges. Both events require the wallet API to be enabled for the app, since usage arises from wallet action traffic.

See the webhooks overview for registering an endpoint and verifying payload signatures.

Payload

Both events share the same payload.

string

The event type — either usage.gas_sponsorship.recorded or usage.cross_chain_fee.recorded.

string

The ID of the wallet action that incurred the charge. Use this to look up the action and reconcile the charge.

'wallet-action-transfer' | 'wallet-action-swap'

The type of wallet action that incurred the charge.

string

The charge amount in USD, as a decimal string with six decimal places (e.g. "0.004213"). A charge smaller than a cent keeps its exact value rather than rounding, so charges total accurately across a billing period.

number

When Privy recorded the charge, in milliseconds since the Unix epoch.

Examples

{
  "type": "usage.gas_sponsorship.recorded",
  "source_id": "wa_9f3c...7b",
  "source_type": "wallet-action-swap",
  "amount_usd": "0.004213",
  "recorded_at": 1722787200000
}

{
  "type": "usage.cross_chain_fee.recorded",
  "source_id": "wa_9f3c...7b",
  "source_type": "wallet-action-swap",
  "amount_usd": "0.750000",
  "recorded_at": 1722787200000
}

Reconciling charges

One wallet action can emit two charges of different types. A sponsored cross-chain transfer reports its gas and its routing cost as separate events, both carrying the same source_id. Delivery is at least once, so the same event may also arrive more than once. The payload carries no idempotency key, so use the svix-id header to identify a redelivery.

See webhook delivery for the retry schedule.

API reference

Gas sponsorship charge recorded

Full schema for usage.gas_sponsorship.recorded.

Cross-chain swap charge recorded

Full schema for usage.cross_chain_fee.recorded.

Gas management

Usage and billing

Event types

Subscribing

Payload

Examples

Reconciling charges

API reference

Gas sponsorship charge recorded

Cross-chain swap charge recorded

​Event types

​Subscribing

​Payload

​Examples

​Reconciling charges

​API reference

Gas sponsorship charge recorded

Cross-chain swap charge recorded

Event types

Subscribing

Payload

Examples

Reconciling charges

API reference