Create a subscription

Create your first on-demand subscription to an agent.

Important

Please set up the Ocelloids Client Library before proceeding with these examples

In Ocelloids, you subscribe to agent-specific APIs and events through webhooks and WebSockets. For more details, check the Subscription schema

In this guide, you will learn how to create subscriptions to track events across the XCM journey. For this purpose, we will subscribe to the XCM Streams API

On-demand WebSocket Subscription

Create a file named xcm-watcher.ts.

xcm-watcher.ts

import { OcelloidsClient, xcm } from "@sodazone/ocelloids-client";

const agent = new OcelloidsClient({
  apiKey: process.env.OC_API_KEY
}).agent<xcm.XcmInputs>("xcm");

// Subscribe on-demand
const reply = await agent.subscribe<xcm.XcmMessagePayload>({
  origins: ["urn:ocn:polkadot:2034"],
  destinations: [
    "urn:ocn:polkadot:0",
    "urn:ocn:polkadot:1000"
  ],
  senders: "*",
  events: "*"
}, 
// Stream handlers
{
  onMessage: (msg) => console.log(msg.metadata, msg.payload),
  onAuthError: console.error,
  onError: console.error,
  onClose: (error) => console.error(error.reason),
},
// On-demand subscription handlers (optional)
{
  onSubscriptionError: console.error,
  onSubscriptionCreated: console.log,
  onError: console.error,
});

On-demand XCM tracking

Run the script.

OC_API_KEY=<YOUR_API_KEY> bun run xcm-watcher.ts

🌈 Congratulations!

You have now successfully set up your client, created an on-demand data stream.

Long-lived Persistent Subscription

Create a file named xcm-persistent.ts.

xcm-persistent.ts

import { OcelloidsClient, xcm } from "@sodazone/ocelloids-client";

const agent = new OcelloidsClient({
  apiKey: process.env.OC_API_KEY
}).agent<xcm.XcmInputs>("xcm");

// The subscription unique identifier
const subscriptionId = `my-subscription-${random}`;

// Create a subscription with support for WebSockets and webhooks
const reply = await agent.createSubscription({
  id: subscriptionId,
  args: {
    origins: ["urn:ocn:polkadot:2034"],
    senders: "*",
    events: "*",
    destinations: [
      "urn:ocn:polkadot:0",
      "urn:ocn:polkadot:1000"
    ],
  },
  channels: [
    {
      // Enables webhook notifications
      type: "webhook",
      url: "https://some.webhook"
     },
    {
      // Enables WebSocket access
      type: "websocket"
    }
  ]
});
 
// subscribe to the previously created subscription
const ws = await xcmAgent.subscribe<xcm.XcmMessagePayload>(
 subscriptionId,
 {
  onMessage: msg => {
    if(xcm.isXcmReceived(msg)) {
      console.log("RECV", msg.subscriptionId);
    } else if(xcm.isXcmSent(msg)) {
      console.log("SENT", msg.subscriptionId)
    }
    console.log(msg);
  },
  onError: error => console.log(error),
  onClose: event => console.log(event.reason)
});

Long-lived XCM tracking

Run the script.

OC_API_KEY=<YOUR_API_KEY> bun run xcm-watcher-persistent.ts

🌈 Congratulations!

You have now successfully created a long-lived subscription with webhook and WebSocket channels.

Historical Replay with XCM Agent

You can configure subscriptions to include historical data, allowing you to replay past events from a specified timeframe.

Here is an example of how to subscribe to real-time XCM messages, while including historical data from the previous 2 hours:

xcm-replay-and-follow.ts

import { createXcmAgent } from "@sodazone/ocelloids-client";

const agent = createXcmAgent({
  httpUrl: process.env.OC_HTTP_URL,
  wsUrl: process.env.OC_WS_URL,
  apiKey: process.env.OC_API_KEY,
});

agent.subscribe(
  {
    destinations: "*",
    origins: "*",
    history: {
      // Replay data from the previous 2 hours
      // and then follow the stream
      timeframe: "previous_2_hours",
    },
  },
  {
    onMessage: (msg) => {
      console.log(msg);
    },
  },
);

Stream with replay