API reference¶

Reference documentation for the Photon HTTP API.

Base URL¶

https://photon.example.com

All REST endpoints are relative to this base URL. Real-time transaction updates are delivered over a separate WebSocket endpoint — see Connect to the WebSocket.

Authentication¶

Method	Header	Where it works
API key	`api-key: YOUR_API_KEY`	All authenticated endpoints.
Wallet JWT	`Authorization: Bearer <JWT>`	The register endpoints (Register webhooks, Register WebSocket credential) accept a JWT as an alternative to the API key.

Get an API key by following Get API access. A wallet JWT is issued by the wallet-login flow: Start wallet login then Verify wallet login.

A handful of endpoints — such as Health and the wallet-login pair — require no credentials. Each endpoint page states its exact auth requirement.

Auth failures use these error codes:

Situation	HTTP status	Code
Missing credentials on an endpoint that requires them	401	`AUTH_001`
`api-key` header present but the key is invalid or revoked	401	`AUTH_002`
Invalid or malformed JWT	401	`AUTH_004`
Expired JWT	401	`AUTH_005`

Response envelope¶

Every response is wrapped in the same envelope. Success:

{
  "success": true,
  "data": { "txId": "68fa3450539a3c9d28bbca33" },
  "timestamp": "2026-07-29T09:14:03.512Z"
}

Error:

{
  "success": false,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid API key provided",
    "category": "AUTH",
    "traceId": "a4f2c9e1d7b83a50"
  },
  "timestamp": "2026-07-29T09:14:03.512Z"
}

data is endpoint-specific; its shape is documented on each endpoint page.
timestamp is ISO-8601 UTC with millisecond precision (for example 2025-10-24T12:34:56.789Z).
error.details (an object with extra context) and error.traceId appear inside error when available.

The full table of error codes, categories, and HTTP statuses is on the Error codes page.

Rate limiting¶

Requests are rate limited per API key over a sliding one-minute window of 300 requests. When you exceed the limit, Photon responds with HTTP 429 and error code RESOURCE_003 (Resource limit exceeded). Back off and retry after a short delay; spreading bursts across the minute avoids the limit entirely.

Endpoints¶

Each endpoint page below is interactive — you can inspect the request and response schemas and send test requests directly from the page.

Endpoint	Description
Submit a transaction	Submit a gas-sponsored transaction for relaying.
Submit and wait	Submit a transaction and wait for a terminal status in a single call.
Submit a signed transaction	Relay a transaction you have already signed.
Estimate transaction cost	Get a USD cost quote before submitting.
Get transaction status	Fetch the full record for a submitted transaction.
Get account information	Retrieve your account details.
List supported chains	Chains currently available for relaying.
Health	Service liveness check.
Start wallet login	Request a nonce to sign with your wallet.
Verify wallet login	Exchange the signed nonce for a JWT.
Register webhooks	Register URLs that receive transaction status updates.
Register WebSocket credential	Issue a WebSocket token and connection URL.
Connect to the WebSocket	Wire protocol for real-time transaction updates.