Photon overview

Photon is a transaction relaying service. You describe the transaction you want on chain — the target address, the calldata, the chain — and Photon executes it for you: it signs with its own relayer key, broadcasts it, pays the gas in the chain's native token, and charges your account a USD amount instead. Your users never need to hold ETH or SOL for gas, and your backend never needs to manage a hot wallet.

On Hyperliquid, Photon is the relay layer for both layers of the network: relay ordinary transactions to HyperEVM, forward and agent-sign gasless HyperCore actions and orders, and issue gasless smart accounts whose sponsored operations drive HyperCore via CoreWriter. See Hyperliquid on Edith for the full surface.

What Photon takes off your plate

A production relaying pipeline is mostly plumbing, and Photon owns all of it:

• Signing and broadcasting. The relayer key that signs and the account that pays gas belong to Photon. You submit intent; Photon turns it into a valid on-chain transaction.
• Nonce management. Concurrent submissions from many clients are serialized onto relayer nonces correctly, so nothing gets stuck behind a gap.
• Fee estimation and bumping. Photon prices each transaction for current network conditions. You can pin gas parameters (gasPrice, or the maxFeePerGas/maxPriorityFeePerGas pair) but you rarely need to.
• Retries. Transient failures — an RPC timeout, a dropped transaction — move the transaction into a retry state with backoff rather than failing it outright. The retries count on the record tells you how many attempts it took.
• Notifications. Rather than polling, you can receive a status payload on a webhook or over a WebSocket each time a transaction changes state.

The async model

Submission and execution are decoupled. POST /api/submit-tx validates the request, reserves the estimated cost against your balance, durably queues the transaction, and returns 201 with a txId — typically in milliseconds. A relay worker then picks the transaction up, executes it, and records the outcome. You observe that outcome by polling GET /api/tx, or by receiving a notification.

When you want a single blocking call instead, POST /api/submit-tx-sync wraps the same queue and holds the connection open until the transaction reaches a terminal state or a timeout you control. Under the hood there is one model; sync is a convenience view over it. See Core concepts for when to choose which.

The status lifecycle

Every transaction moves through a small, explicit state machine, visible in the status field:

NOT_PICKED_UP ──► PENDING ──► EXECUTED
                   │    ▲
                   │    └─── NEEDS_TO_BE_RETRIED
                   │              (backoff, then re-claimed)
                   └───────► FAILED

• NOT_PICKED_UP — accepted and queued; no worker has claimed it yet.
• PENDING — a relay worker is actively executing it.
• EXECUTED — confirmed on chain; executionTxHash, costUSD, and latency are set.
• NEEDS_TO_BE_RETRIED — a recoverable failure occurred; the transaction waits out a backoff, then returns to PENDING for another attempt.
• FAILED — terminal failure; the record carries the error, and revert details are available on request.

EXECUTED and FAILED are the only terminal states.

Prepaid USD accounting

Photon abstracts gas away financially as well as operationally. Your account holds a prepaid USD balance. At submission, the estimated cost (estimatedCostUSD) is reserved from your availableBalance and held as pendingBalance; when the transaction executes, the actual cost — reported as costUSD on the record — is what you're charged, and isAccountCharged confirms the debit. Per-transaction and daily spending limits, plus an optional maxUSD cap per submission, keep the spend bounded; Core concepts covers the details.

Where to go next

• Why Photon? — the problems sponsorship actually solves, and when not to use it.
• Quickstart — relay your first sponsored transaction.
• Supported networks — chains, ids, and per-chain features.