Sponsoring

The Paymaster supports 2 types of transaction execution

• Gasless transaction: Users pay gas fees in any token you choose to support.
• Gasfree transaction: You (the integrator) pay the gas fees on behalf of the users.

Gasfree transactions are also referred to as "sponsored transactions" and can operate in 3 different modes:

Modes

None

Sponsoring is disabled. All transactions must be paid by the user.

{
  "sponsoring": {
      "mode": "none"
  }
}

Self

You pay the gas fees for all transactions. Sponsorship is secured via an API key.

• An optional sponsor_metadata field can be used to attach custom felt values to the emitted SponsoredTransaction event. These values are only used for on-chain identification purposes (e.g., analytics, tracking) and do not affect execution.

{
  "sponsoring": {
    "mode": "self",
		"api_key": "paymaster_6bb5fde8-d937-4e64-a61c-62b9a05dd4bc",
    "sponsor_metadata": [] // Optional
  }
}

Webhook

You pay the gas fees, but validation is handled externally via a webhook.

• When a sponsored transaction is submitted, the Paymaster sends a POST request to the endpoint:
  POST <endpoint>
• The request include the X-PAYMASTER-API-KEY header for the authentication.
• The response must include:
  • is_valid: whether the API key is authorized
  • sponsor_metadata: a list of felt values to include in the SponsoredTransaction event
  • validity_duration: in seconds — the Paymaster will cache the result and skip validation for subsequent requests with the same API key during that period

{
  "sponsoring": {
    "mode": "webhook",
    "endpoint": "https://myapi.com/my-validation-endpoint",
    "headers": {
			"X-PAYMASTER-API-KEY": "<secret>",
      "some-custom-header": "header-value"
    }
  }
}

Expected webhook response example:

{
  "is_valid": true,
  "sponsor_metadata": ["0x123...", "0x456..."],
  "validity_duration": 300
}

Sponsoring Configuration Schema