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 Monitor agent.

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({
  origin: "urn:ocn:polkadot:2004",
  destinations: [
    "urn:ocn:polkadot:0",
    "urn:ocn:polkadot:1000",
    "urn:ocn:polkadot:2000",
    "urn:ocn:polkadot:2034",
    "urn:ocn:polkadot:2104"
  ],
  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-watcher-persistent.ts.

xcm-watcher-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: {
    origin: "urn:ocn:polkadot:2004",
    senders: "*",
    events: "*",
    destinations: [
      "urn:ocn:polkadot:0",
      "urn:ocn:polkadot:1000",
      "urn:ocn:polkadot:2000",
      "urn:ocn:polkadot:2034",
      "urn:ocn:polkadot:2104"
    ],
  },
  channels: [
    {
      // Enables webhook notifications
      type: "webhook",
      url: "https://some.webhook"
     },
    {
      // Enables WebSocket access
      type: "websocket"
    }
  ]
});
 
// subscribe to the previously created subscription
const ws = agent.subscribe(
 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.