Gas and Webhooks

Signalite actions are HyperEVM transactions. A user wallet needs native HYPE for approvals, deposits, redeems, claims, and cancels. For authenticated Partner Actions, Signalite checks gas before returning wallet signature steps. If the wallet is below the configured HYPE threshold and production gas sponsorship is enabled, Signalite sends the configured HYPE amount first. Partners should not ask users to source HYPE manually in the normal deposit flow.

Gas status

Use the versioned gas endpoint when rendering diagnostics or custom wallet flows:

import { summarizeGasReadiness } from "@arc/shlp-sdk";

const gas = await shlp.getGasStatus(userAddress);
const readiness = summarizeGasReadiness(gas);

if (!readiness.canAskForSignature) {
  showGasRequired(readiness.message);
}

Raw HTTP:

GET /api/v1/gas/status?address=0x...

Gas top-up

The public top-up endpoint is a legacy diagnostics endpoint. Production partner integrations should rely on authenticated Partner Actions, which invoke the server-side gas sponsor internally.

const result = await shlp.requestGasTopUp(userAddress);

Raw HTTP:

POST /api/v1/gas/top-up
Content-Type: application/json

{ "address": "0x..." }

faucetEnabled=false is expected for production partner launch. Launch readiness depends on the server-side GAS_SPONSOR_* configuration used by Partner Actions, not the public faucet toggle.

Configure webhooks

Partner webhooks are authenticated with the same server-side partner API key.

const webhook = await shlp.upsertPartnerWebhook({
  url: "https://partner.example.com/webhooks/signalite",
  events: ["partner_action.created", "partner_action.submitted"],
  enabled: true,
  rotateSecret: true,
});

storeSecret(webhook.signingSecret);

The signing secret is returned only when the webhook is created or rotated.

Events

Currently emitted:

Event	Meaning
`partner_action.created`	Signalite created a persisted Partner Action
`partner_action.submitted`	Partner attached a submitted transaction hash

Reserved lifecycle events in the API contract:

partner_action.failed
partner_action.claimable
partner_action.claimed
partner_action.cancelled

Delivery headers

X-Signalite-Event: partner_action.created
X-Signalite-Delivery: <delivery_id>
X-Signalite-Timestamp: <unix_seconds>
X-Signalite-Signature: v1=<hmac_sha256>

Verify X-Signalite-Signature on your backend with the SDK helper:

import { verifySignaliteWebhook } from "@arc/shlp-sdk/webhooks";

const result = verifySignaliteWebhook({
  signingSecret: process.env.SIGNALITE_WEBHOOK_SECRET!,
  timestamp: request.headers.get("x-signalite-timestamp")!,
  signature: request.headers.get("x-signalite-signature")!,
  rawBody,
});

if (!result.ok) {
  throw new Error(`invalid Signalite webhook: ${result.reason}`);
}

Use the exact raw request body bytes/string. Do not parse and re-stringify the JSON before verification.

Retry behavior

Signalite records webhook deliveries and retries failed/pending deliveries through:

POST /api/cron/webhooks
Authorization: Bearer <cron_secret>

Partners should still support polling GET /api/v1/partner/actions/{id} because webhook delivery can be delayed or fail after maximum attempts.

Start

Build flows

SDK

Operations

Gas status

Gas top-up

Configure webhooks

Events

Delivery headers

Retry behavior

​Gas status

​Gas top-up

​Configure webhooks

​Events

​Delivery headers

​Retry behavior

Gas status

Gas top-up

Configure webhooks

Events

Delivery headers

Retry behavior