​

Authentication for GraphQL Subscriptions

This document provides a comprehensive overview of the authentication process for GraphQL subscriptions on the GoldRush Streaming API. It covers the rationale for authentication, how to obtain and use an API key, client-side implementation examples, server-side validation, error handling, and frequently asked questions.

​

Why is Authentication Required?

Authentication is essential to ensure that only authorized users can access premium or rate-limited real-time data streams. All clients must present a valid GoldRush API key to interact with the GraphQL subscription endpoints.

​

1. Obtaining a GoldRush API Key

To begin, register for an API key at GoldRush API Dashboard. This key will be required for all authenticated requests to the streaming API.

​

2. Supplying the API Key from the Client

​

Using a GraphQL WebSocket Client

When establishing a WebSocket connection, the API key must be included in the connection_init payload. The graphql-ws library is recommended for this purpose. Below is an example implementation in JavaScript:

import { createClient } from "graphql-ws";

const client = createClient({
  url: "wss://gr-staging.streaming.covalenthq.com/graphql",
  connectionParams: {
    GOLDRUSH_API_KEY: "YOUR_API_KEY_HERE", // Replace with your GoldRush API key
  },
});

(async () => {
  await client.subscribe(
    {
      query: `subscription { newPairs { ...fields } }`,
    },
    {
      next: (data) => console.log("Received data:", data),
      error: (err) => console.error("Subscription error:", err),
      complete: () => console.log("Subscription complete"),
    }
  );
})();

Note: The API key must be provided as GOLDRUSH_API_KEY within the connectionParams object.

​

Using websocat for Manual WebSocket Testing

For manual testing or debugging, websocat can be used to interact with the WebSocket endpoint directly from the command line.

Step 1: Initiate the WebSocket Connection

websocat -H="Sec-WebSocket-Protocol: graphql-transport-ws" wss://gr-staging.streaming.covalenthq.com/graphql

Step 2: Send the Connection Initialization Payload

Send the following JSON as your first message, replacing <YOUR_API_KEY> with your actual API key:

{
    "type": "connection_init",
    "payload": { "GOLDRUSH_API_KEY": "<YOUR_API_KEY>" }
}

Wait for a connection_ack response from the server before proceeding.

Step 3: Submit a Subscription Query

You may now send a subscription query, for example:

{
    "id": "74bb224c-22c6-4a0f-ad85-d43a8c4e49ce",
    "type": "subscribe",
    "payload": {
        "query": "subscription {newPairs(chain_name: BASE_MAINNET) { chain_name protocol protocol_version event_name tx_hash block_signed_at pair_address pair_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } base_token_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } quote_token_metadata { contract_name contract_address contract_decimals contract_ticker_symbol } deployer_address quote_rate quote_rate_usd liquidity market_cap supply prices { last_5m last_1hr last_6hr last_24hr } swaps { last_5m last_1hr last_6hr last_24hr }}}"
    }
}

If authentication is successful, you will begin receiving real-time data for your subscription.

​

3. Server-Side Authentication Process

• The server does not validate the API key at the time of WebSocket connection establishment.
• Instead, authentication is enforced at the start of each GraphQL subscription resolver.
• If the API key is missing or invalid, the subscription will immediately terminate with an error message.

​

4. Error Handling

If authentication fails, the client will receive a GraphQL error with one of the following codes:

• MISSING_TOKEN: No API key was provided in the connection_init payload.
• INVALID_TOKEN: The provided API key is malformed or invalid.
• AUTH_SYSTEM_ERROR: An internal server error occurred during authentication.

Example Error Response:

{
  "errors": [
    {
      "message": "Authentication required. Please provide a valid API key in the connection_init payload under 'GOLDRUSH_API_KEY' or 'Authorization' key.",
      "extensions": {
        "code": "MISSING_TOKEN"
      }
    }
  ]
}

​

5. Frequently Asked Questions (FAQ)

• What is the client experience if the key is invalid?
  • The client will always receive a connection_ack response, even if the API key is invalid. Authentication errors are only reported when a subscription is initiated.
• Where is the API key expected?
  • The API key is expected in the payload of the connection_init message with the key GOLDRUSH_API_KEY.
• What API key formats are supported?
  • cqt_wF[26 base58 chars] or cqt_rQ[26 base58 chars]