Usage webhooks

Privy publishes webhooks for sponsored fee charges. Each event carries the amount and the wallet action that incurred it, so an app can attribute costs to users.

Swap provider fee events are available for prepaid and postpaid accounts. Prepaid accounts receive an event after the charge is deducted from their credits. Gas sponsorship events currently support postpaid accounts. Support for prepaid accounts is coming soon.

Event types

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

Subscribing

Swap provider fee charges use the usage.swap_provider_fee.recorded event type. 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.swap_provider_fee.recorded.

string

A unique identifier for the usage event. Use it to deduplicate charge events.

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",
  "event_id": "insert-gas-charge-event-id",
  "source_id": "wa_9f3c...7b",
  "source_type": "wallet-action-swap",
  "amount_usd": "0.004213",
  "recorded_at": 1722787200000
}

{
  "type": "usage.swap_provider_fee.recorded",
  "event_id": "insert-swap-provider-sponsorship-event-id",
  "source_id": "wa_9f3c...7b",
  "source_type": "wallet-action-swap",
  "amount_usd": "0.750000",
  "recorded_at": 1722787200000
}

Reconciling charges

A sponsored cross-chain transfer can report gas and routing costs as separate events. Both carry the same source_id, with different event types and event_id values. Delivery is at least once, so the same event may arrive more than once. Use event_id to deduplicate charges and the svix-id header to identify a webhook redelivery.

See webhook delivery for the retry schedule.

API reference

Gas sponsorship charge recorded

Full schema for usage.gas_sponsorship.recorded.

Swap provider fee charge recorded

Full schema for usage.swap_provider_fee.recorded.

Gas management

Usage and billing

Event types

Subscribing

Payload

Examples

Reconciling charges

API reference

Gas sponsorship charge recorded

Swap provider fee charge recorded

​Event types

​Subscribing

​Payload

​Examples

​Reconciling charges

​API reference

Gas sponsorship charge recorded

Swap provider fee charge recorded

Event types

Subscribing

Payload

Examples

Reconciling charges

API reference