Websocket

For this guide we'll be using JavaScript and the ws library to handle the WebSocket connection.

Connect to SEDA Fast

Once you have your API key you can open a WebSocket connection to SEDA Fast. After establishing the connection, the server sends an authorized message if the API key is valid. You must wait for this message before sending execution or feed requests.

Example code:

const WebSocket = require("ws");

const ws = new WebSocket("wss://fast-ws.mainnet.seda.xyz/ws/v1", {
	headers: { Authorization: `Bearer ${process.env.SEDA_FAST_API_KEY}` },
});

ws.on("open", () => console.log("🔌 Connected"));

ws.on("message", (data) => {
	const msg = JSON.parse(data.toString());

	// Uncomment this line to see the full message
	// console.log("📨", JSON.stringify(msg, null, 2));

	if (msg.method === "authorized") {
		console.log("✅ Authorized");

		// Close the connection after receiving the authorized notification
		ws.close(1000, "closed by client");
	}

	if (msg.error) {
		console.error("❌", msg.error.code, msg.error.message);
	}
});

ws.on("error", (e) => console.error("❌", e));

ws.on("close", (code, reason) => {
	console.log("🔌 Disconnected", code ? `(${code}${reason ? `: ${reason}` : ""})` : "");
});

Executing a Single Request

Once the authorisation works it is time to execute an Oracle Program.

const WebSocket = require("ws");

const executeRequest = {
	jsonrpc: "2.0",
	// For this example we're using a hardcoded request ID
	id: "req-1",
	// The method, either "feed.execute", "feed.start", or "feed.stop"
	method: "feed.execute",
	// The parameters of the request. These are the same as the execute endpoint on the REST API
	params: {
		execProgramId: "0x568732e496819819f2effa240614b8ebe53c2492149443578e155a145e0a351e",
		execInputs: "0x9b190a0000000000",
		inputEncoding: "auto",
		includeDebugInfo: "true",
		injectLastResult: "success",
		encoding: "json",
	},
};

const ws = new WebSocket(WS_URL, {
	headers: { Authorization: `Bearer ${process.env.SEDA_FAST_API_KEY}` },
});

ws.on("open", () => console.log("🔌 Connected"));

ws.on("message", (data) => {
	const msg = JSON.parse(data.toString());

	// Uncomment this line to see the full message
	// console.log("📨", JSON.stringify(msg, null, 2));

	if (msg.method === "authorized") {
		console.log("✅ Authorized");
		// When authorized immediately send an execute request
		ws.send(JSON.stringify(executeRequest));
	}

	// We check for the same ID that we specified in the executeRequest
	if (msg.id === "req-1" && msg.result !== undefined) {
		const exitCode = msg.result.data.dataResult.exitCode;
		console.log("📊 Result:", !exitCode ? "success" : "failed");

		// Close the connection after receiving the result
		ws.close(1000, "closed by client");
	}

	if (msg.error) {
		console.error("❌", msg.error.code, msg.error.message);
	}
});

ws.on("error", (e) => console.error("❌", e));

ws.on("close", (code, reason) => {
	console.log("🔌 Disconnected", code ? `(${code}${reason ? `: ${reason}` : ""})` : "");
});

Understanding the Response

A successful response includes:

{
	"jsonrpc": "2.0",
	"id": "req-1",
	"result": {
		"_tag": "ExecuteResponse",
		"data": {
			"id": "603f6ded-fd32-4881-92af-893bfd73b39d",
			"requestId": "603f6ded-fd32-4881-92af-893bfd73b39d",
			"dataRequest": {
				"consensusFilter": "00",
				"execGasLimit": "300000000000000",
				"execInputs": "9b190a0000000000",
				"execProgramId": "568732e496819819f2effa240614b8ebe53c2492149443578e155a145e0a351e",
				"gasPrice": "0",
				"memo": "",
				"replicationFactor": 1,
				"tallyGasLimit": "50000000000000",
				"tallyInputs": "",
				"tallyProgramId": "568732e496819819f2effa240614b8ebe53c2492149443578e155a145e0a351e",
				"version": "0.0.1"
			},
			"dataResult": {
				"drId": "7f3f862bc15fc136f68df81533b852b01cf533745968f28ea84bdde5bb95c404",
				"gasUsed": "30208555168125",
				"blockHeight": "0",
				"blockTimestamp": "1772030619437",
				"consensus": true,
				"exitCode": 0,
				"version": "0.0.1",
				"result": "0000000000000000000000000003f4dc",
				"paybackAddress": "",
				"sedaPayload": ""
			},
			"signature": "90a1b3827d8c828f8508655aea09dbc6c6c600280e1481fa2698eaaf0e802a182f17ba83418c2133726a51836736956f6fa5d18b5d2287548082951ec967aa9d01",
			"result": "0000000000000000000000000003f4dc",
			"execute": {
				"result": {
					"value": 259292
				},
				"gasUsed": "14244011134375",
				"stdout": "Received input: 661915\nRandom output: 259292\n",
				"stderr": "",
				"exitCode": 0
			},
			"tally": {
				"result": "0000000000000000000000000003f4dc",
				"gasUsed": "15964544033750",
				"stdout": "50\nReveal 0: 259292\n",
				"stderr": "",
				"exitCode": 0
			}
		}
	}
}

Key fields:

• id - The JSON-rpc id of the request.
• result.data.dataRequest - Details of the Oracle Program execution request (program IDs, inputs, gas limits)
• result.data.dataResult.result - The hex-encoded final result from the Oracle Program
• result.data.dataResult.exitCode - 0 indicates success, non-zero indicates an error
• result.data.dataResult.gasUsed - Total gas consumed during execution
• result.data.dataResult.drId - Unique identifier for this data request
• result.data.signature - Cryptographic signature for verification
• result.data.result - Convenient top-level access to the result (same as dataResult.result)

Additional fields may be included in the response depending on the parameters used. The WebSocket API supports the same parameters as the REST API. See the REST API Reference for complete details on all available parameters and response fields.