WebSocket API

This section provides detailed documentation for the SEDA FAST WebSocket API.

Base URLs

SEDA Fast WebSockets are available on the following networks:

• Testnet: wss://fast-ws.testnet.seda.xyz/ws/v1

• Mainnet: wss://fast-ws.mainnet.seda.xyz/ws/v1

Authentication

Establishing a WebSocket connection requires authentication using a bearer token in the Authorization header:

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.

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.

Messages

Message method	Description
feed.execute	Executes a single Oracle Program request (one-shot execution)
feed.start	Starts a continous feed that executes periodically
feed.stop	Stops a running feed
feed.result	Server-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 notifications.

Params

• execute (object, required) — Same shape as 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

  • 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": "<message>" } 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

Reason	Code
Parse error: invalid JSON	32700
Invalid Request: missing or invalid jsonrpc	32600
Invalid params: method specific validation failed	32602
Server error: unexpected error	36000

Use parameter "includeDebugInfo": true in feed.execute or feed.start to get stdout/stderr for debugging failed executions.