Realtime Websocket Events [BETA]

Overview

Reservoir web socket service is a Pusher protocol based service which utilizes Pusher channels in order to enable developers to receive events as they occur, without the need to continuously poll for updates.

Subscribing to a channel gives means that you can listen for any events that occur in that channel (or listen to a specific event).

Supported channels:

  • "top-bids"

    • Events:
      • "new-top-bid"*:
        • Payload:
          • {
              "event": "new-top-bid",
              "channel": "top-bids",
              "data": {
                "order": {
                  "id": "0xa8b2151fa2711a20f2f502cf0d62f771e94a0daf2a7fb021955f412330228d85",
                  "maker": "0xdb66e3b63bbfc795d4233a82cfe68a1387b11f18",
                  "createdAt": "2023-01-24T17:33:34.738Z",
                  "validFrom": 1674581551,
                  "validUntil": 1674840810,
                  "source": {
                    "id": "0x3169aeb16feeae4dc16fd13473fbb9072c372021",
                    "domain": "dev.reservoir.market",
                    "name": "Reservoir Market",
                    "icon": "https://www.reservoir.market/reservoir.svg"
                  },
                  "price": {
                    "currency": {
                      "contract": "0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6",
                      "name": "Wrapped Ether",
                      "symbol": "WETH",
                      "decimals": 18
                    },
                    "amount": {
                      "raw": "10000000000000000",
                      "decimal": 0.01,
                      "usd": null,
                      "native": 0.01
                    },
                    "netAmount": {
                      "raw": "10000000000000000",
                      "decimal": 0.01,
                      "usd": null,
                      "native": 0.01
                    }
                  },
                  "priceNormalized": {
                    "currency": {
                      "contract": "0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6",
                      "name": "Wrapped Ether",
                      "symbol": "WETH",
                      "decimals": 18
                    },
                    "amount": {
                      "raw": "10000000000000000",
                      "decimal": 0.01,
                      "usd": null,
                      "native": 0.01
                    },
                    "netAmount": {
                      "raw": "10000000000000000",
                      "decimal": 0.01,
                      "usd": null,
                      "native": 0.01
                    }
                  },
                  "criteria": {
                    "kind": "token",
                    "data": {
                      "token": {
                        "tokenId": "302"
                      }
                    }
                  }
                },
                "owners": [
                  "0xdabc74ac2b155f0f2e7cee39301f7554aa3e45cf"
                ]
              }
            }
            
  • Potentially, you can receive multiple "new-top-bid" events with the same order id (but with unique owners in each event). This can happen when the number of owners is very large so we avoid sending a very big payload by sending multiple events

Authentication

Authentication with the Websocket Service uses the same API key as our other APIs and does not affect the rate limits on your API key tier.

Connecting

  • Pusher App Key: yajqimyMarlhmnV1a3

  • Websocket Endpoint: wss://websocket.reservoir.tools

  • Authentication Endpoint: https://api.reservoir.tools/websocket/user-auth

  • Client Example:

    • const PusherJS = require('pusher-js');
      
      let client = new PusherJS('yajqimyMarlhmnV1a3', {
          wsHost: 'websocket.reservoir.tools',
          forceTLS: true,
          encrypted: true,
          disableStats: true,
          enabledTransports: ['ws', 'wss'],
          userAuthentication: { endpoint: "https://api.reservoir.tools/websocket/user-auth", params: { api_key: 'YOUR API KEY' }},
      });
      
      // This is needed in order to authenticate your api key.
      pusher.signin();
      
      client.subscribe('top-bids').bind('new-top-bid', (message) => {
          alert(`${message.sender} says: ${message.content}`);
      });