# WebSocket Reference ## Base URLs SEDA Fast WebSockets are available on the following networks: * **Testnet**: * **Mainnet**: ## Authentication Establishing a WebSocket connection requires authentication using a bearer token in the Authorization header: ```jsx Authorization: Bearer YOUR_API_KEY ``` Your API key is provided during onboarding and is specific to your account. Keep it secure and never expose it in client-side code or public repositories. {% hint style="danger" %} After a successful connection and API key verification, the server sends an authorized notification. Clients must wait for this message before sending any JSON-RPC requests. {% endhint %} ## Messages
Message methodDescription
feed.executeExecutes a single Oracle Program request (one-shot execution)
feed.startStarts a continous feed that executes periodically
feed.stopStops a running feed
feed.resultServer-sent message containing feed execution results
## Feeds A feed is the term used to describe a periodically executed Oracle Program with a set of inputs. A client can start feeds with the `feed.start` method. When a feed has started the service will respond with a unique feed ID. Results from the periodic Oracle Program execution are sent back to the client with the feed ID in the body. A client can start multiple feeds that each have their own unique configuration. Each of these feeds will have a unique feed ID, so the client should keep track of the feed IDs in order to link the response with the correct feed. All feeds started by a client are scoped to the connection. If the connection is closed the feeds will be terminated and a client will have to restart the feeds after reconnecting. ## Connection Liveness The SEDA Fast WebSocket service uses the ping/pong keepalive mechanism to determine liveness of the connection. The server will periodically send ping frames to the client to which the client should respond (handled automatically by most WebSocket clients). If the client fails to respond before the next ping frame the connection is closed. ## Message Types All messages are JSON-encoded. One JSON object per WebSocket text frame. ### Client to Server methods Client requests must conform to JSON-RPC 2.0: * `jsonrpc` (string, required) — `"2.0"` * `id` (string, required) — client-provided identifier for correlating responses * `method` (string, required) — `feed.execute` | `feed.start` | `feed.stop` * `params` (object, required) — method-specific parameters #### feed.execute One-off execution of an Oracle Program. **Params** * `execProgramId` (string, required) — Program id (deployed on SEDA chain). * `execInputs` (string, optional) — Inputs to the program; encoding controlled by `inputEncoding`. * `tallyProgramId` (string, optional) — Defaults to `execProgramId` if omitted. * `tallyInputs` (string, optional) * `inputEncoding` (string, optional) — `auto` | `hex` | `utf8` | `base64`. Default behavior: `auto` (e.g. `0x` prefix = hex). * `returnLastResult` (string, optional) — `"true"` | `"false"` — Return last saved result instead of executing. * `returnLastResultMaxAge` (string, optional) — Maximum age in seconds for cached result. * `includeSummary` (string, optional) — `"true"` | `"false"` — Include credit usage / total cost in response. * `includeDebugInfo` (string, optional) — `"true"` | `"false"` — Include stdout/stderr in response. * `injectLastResult` (string, optional) — `success` | `last` | `none` — Inject last result into OP. * `encoding` (string, optional) — `hex` | `base64` | `utf8` | `json` — Encoding of the result. **Example** ``` { "jsonrpc": "2.0", "id": "exec-001", "method": "feed.execute", "params": { "execProgramId": "0x568732e496819819f2effa240614b8ebe53c2492149443578e155a145e0a351e", "execInputs": "0x9b190a0000000000", "inputEncoding": "auto", "encoding": "json" } } ``` **Response**\ JSON-RPC success response with the Fast API execute response body, or JSON-RPC error. #### feed.start Start a recurring feed. Server will periodically call the Fast API execute and push results via [`feed.result`](#feed.result) notifications. **Params** * `execute` (object, required) — Same shape as [`feed.execute`](#feed.execute) params (e.g. `execProgramId`, `execInputs`, `inputEncoding`, `encoding`, etc.). * `periodicityMs` (number, required) — Interval in milliseconds between executions (interpretation depends on `mode`). * `mode` (string, required) — `FIXED` | `SEQUENTIAL` | `PARALLEL`. * `FIXED` This schedules executions at regular, evenly spaced intervals. If the execution takes longer than the `periodicityMs`, the next execution will happen immediately to prevent "pile-ups," ensuring that the schedule remains consistent without overlapping executions. ``` |-----interval-----|-----interval-----|-----interval-----| |---------action--------||action|-----|action|-----------| ``` * `SEQUENTIAL` This schedules executions at a fixed interval, maintaining a consistent delay between executions. The delay starts from the end of the last execution, not from the schedule start time. ``` |---------action--------|-----interval-----|action|-----interval-----|---action---|-----interval-----| ``` * `PARALLEL` This schedules executions at a fixed interval, without maintaining a consistent delay between executions. ``` |---------action--------| |-----interval-----|-----------------action----------------| |-----interval-----|-----interval-----|-------action------| |-----interval-----|-----interval-----|-----interval-----|-action-| ``` **Example** ``` { "jsonrpc": "2.0", "id": "start-001", "method": "feed.start", "params": { "execute": { "execProgramId": "0x568732e496819819f2effa240614b8ebe53c2492149443578e155a145e0a351e", "execInputs": "0x9b190a0000000000", "inputEncoding": "auto", "encoding": "json" }, "periodicityMs": 5000, "mode": "FIXED" } } ``` **Response**\ JSON-RPC success response with `{ "feedId": "unique-id" }`. Subsequent results are pushed as notifications feed.result with `params.feedId` and `params.result` on execution success or `params.error` on execution failure. #### feed.stop Stop an existing feed by id. **Params** * `feedId` (string, required) — The feed id returned from `feed.start`. **Example** ``` { "jsonrpc": "2.0", "id": "stop-001", "method": "feed.stop", "params": { "feedId": "550e8400-e29b-41d4-a716-446655440000" } } ``` **Response**\ JSON-RPC success response with `{ "feedId": "stopped-feed-id" }` on success. If the feed is not found the server responds with JSON-RPC not found error. ### Server to Client messages All responses are JSON-RPC **Successful response** * `jsonrpc`: `"2.0"` * `id`: same as request `id` * `result`: method-specific (e.g. execute payload, `{ feedId }` for start/stop) **Error response** * `jsonrpc`: `"2.0"` * `id`: same as request `id`, or `null` for parse/invalid-request errors * `error`: * For request errors: `{ "code": number, "error": string }` see [error codes](#error-codes) * For execution errors:
``` "error": { "_tag": "FailedExecutionResponse", "data": { // Execution information and logs when includeDebugInfo was specified } } ``` #### authorized Sent once by the server immediately after a successful WebSocket upgrade and auth verification. No `id` (notification). **Params** * `projectId` (string) * `organizationId` (string) * `organizationSlug` (string) * `remainingCreditsSnapshot` (string) * `usedCreditsSnapshot` (string) * `apiKeyId` (string) * `apiKeyExpiresAt` (string | null) — ISO date string or null **Example** ``` { "jsonrpc": "2.0", "method": "authorized", "params": { "projectId": "...", "organizationId": "...", "organizationSlug": "...", "remainingCreditsSnapshot": "...", "usedCreditsSnapshot": "...", "apiKeyId": "...", "apiKeyExpiresAt": "2026-12-31T23:59:59.000Z" } } ``` #### feed.result Pushed by the server for each execution result (or error) of an active feed. No `id` (notification). **Params** * `feedId` (string, required) — The feed that produced this result. * `result` (object, present on success) — The Fast API execute response body for that run. * `error` (object, present on execution failure) — At least `{ "error": "" }` or similar; execution-level failure, not protocol error. **Success example** ``` { "jsonrpc": "2.0", "method": "feed.result", "params": { "feedId": "550e8400-e29b-41d4-a716-446655440000", "result": { "composite_rate": 4724.643, "price": { "mantissa": "4724643", "exponent": -3 }, "timestamp": "2026-01-20T10:40:41.709Z" } } } ``` **Execution error example** ``` { "jsonrpc": "2.0", "method": "feed.result", "params": { "feedId": "550e8400-e29b-41d4-a716-446655440000", "error": { "error": "Request failed with 500" } } } ``` ## Error Codes
ReasonCode
Parse error: invalid JSON32700
Invalid Request: missing or invalid jsonrpc32600
Invalid params: method specific validation failed32602
Server error: unexpected error36000
{% hint style="info" %} Use parameter `"includeDebugInfo": true` in `feed.execute` or `feed.start` to get stdout/stderr for debugging failed executions. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.seda.xyz/home/developer/developer-tools/websocket/websocket-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.