📘
Don't have an API Key? Get one now!

Getting Started

The first step is to get an API key at app.noves.fi.

Note that Streams endpoints are only available to paid users.

Creating a Subscription

A subscription consists of one or more "accounts", where each account consists of a single address and one or more chains in which the address will be tracked.

When you create a new subscription, you'll get back an object that includes the subscriptionId, and a WebSocket URL you can use to connect and start receiving the stream.

Connecting to the Stream

At the moment, our primary delivery method for the stream is WebSocket. The WebSocket URL that gets generated will include an apiKey query parameter which must be passed for the connection to be authenticated.

As an example, here's a sample implementation in Python of how to connect to the stream:

import asyncio
import json
import websockets
from datetime import datetime

SUBSCRIPTION_ID = ""
API_KEY = ""

url =  f"ws://tx-subscriptions.noves.fi/ws/streams/{SUBSCRIPTION_ID}=?apiKey={API_KEY}"

async def connect_and_listen():
    """Connect to websocket and listen for messages"""
    # Build the websocket URL
    ws_url = provided_url

    print(f"Connecting to {ws_url}...")

    try:
        # Connect to the websocket
        async with websockets.connect(ws_url) as websocket:
            print("Connected!")
            connection_time = datetime.now()

            # Set up the ping task to keep connection alive
            ping_task = asyncio.create_task(send_pings(websocket))

            try:
                # Listen for messages
                async for message in websocket:
                    try:
                        # Try to parse as JSON
                        data = json.loads(message)
                        with open("transactions.json", "a") as f:
                            f.write(json.dumps(data) + "\n")
                        print(f"Received: {json.dumps(data, indent=2)}")
                    except json.JSONDecodeError:
                        # Handle plain text messages
                        print(f"Received (text): {message}")
            except websockets.exceptions.ConnectionClosed as e:
                print(f"Connection closed: {e.code} {e.reason}")
            finally:
                # Clean up ping task
                ping_task.cancel()
                print(f"Connection duration: {datetime.now() - connection_time}")
    except Exception as e:
        print(f"Error connecting: {str(e)}")


async def send_pings(websocket):
    """Send periodic pings to keep the connection alive"""
    while True:
        await asyncio.sleep(30)
        print("Sending ping...")
        await websocket.send(json.dumps({"type": "ping"}))


if __name__ == "__main__":
    print("Starting websocket client...")
    asyncio.run(connect_and_listen())

If the connection is lost or reset, once you connect back the stream will automatically send you any messages you might have missed while the connection was lost.

Note that when you create a stream, it will start listening for transactions from that point onwards.

If you wish to perform a backfill, you may use the txs jobs endpoints for EVM or SVM.

Managing your Subscription

You may get all the details of your subscription by using the GET endpoint and you may also cancel it at any point by using the DELETE endpoint.