Skip to main content
Codex WebSockets use the graphql-transport-ws subprotocol to deliver real-time data updates. By integrating Codex through Uniblock, you can access low-latency market events and token tracking through a unified interface.

​
Endpoints

To integrate Codex, use the following endpoints for validation and streaming:
  • HTTP (Validation): https://websocket.uniblock.dev/codex/validate
  • WebSocket (WSS): wss://websocket.uniblock.dev/codex

​
Authentication

Uniblock supports two ways to authenticate your Codex WebSocket connection and validation requests:
  1. Header: Include x-api-key: YOUR_API_KEY in your request headers.
  2. URL query parameter: Append apiKey=YOUR_API_KEY to the connection string.
When initiating the WebSocket subprotocol handshake, you must also provide your API key inside the connection_init message payload under the Authorization key.

​
Parameters

ParameterRequiredDescription
apiKey / x-api-keyYesYour unique Uniblock API key.

​
Validate connection

Before establishing a permanent socket, use the validation endpoint to verify your credentials. You can pass the API key in the URL or the header.

​
Option 1: Header authentication

Header authentication is recommended to avoid exposing your API key in server logs or URLs.
curl --location 'https://websocket.uniblock.dev/codex/validate' \
  --header 'x-api-key: YOUR_API_KEY'

​
Option 2: URL authentication

curl --location 'https://websocket.uniblock.dev/codex/validate?apiKey=YOUR_API_KEY'

​
Workflow

To successfully establish and maintain a stream, implement the connection using this operational flow:
  1. Validate credentials: Send a GET request to the Codex HTTP validation endpoint using your preferred authentication method.
  2. Establish WebSocket connection: Connect to the WSS endpoint using the graphql-transport-ws subprotocol.
  3. Initialize session: Send a connection_init payload message containing your token authorization.
  4. Acknowledge and subscribe: Wait for the server to reply with a connection_ack message, then send your GraphQL subscribe payload with a unique tracking identifier in id.
  5. Unsubscribe or complete: When you want to stop receiving updates for a specific stream, send a complete message matching the operational id.

​
Protocol payloads

The Codex GraphQL WebSocket protocol exchanges structured JSON messages. Every payload must include a type property, and streaming operations require an explicit id.

​
Initialize session

Send this message immediately after the WebSocket connection opens to pass credentials and authorize your session. 
{
  "type": "connection_init",
  "payload": {
    "Authorization": "YOUR_API_KEY"
  }
}

​
Subscribe to streams

After receiving the connection_ack message from the server, submit your GraphQL subscription query. Assign a tracking value to the id property to manage this specific stream. 
{
  "id": "my_id",
  "type": "subscribe",
  "payload": {
    "variables": {
      "address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
      "networkId": 56
    },
    "extensions": {},
    "operationName": "onPriceUpdated",
    "query": "subscription($address: String!, $networkId: Int!) { onPriceUpdated(address: $address, networkId: $networkId) { priceUsd timestamp address } }"
  }
}

​
Unsubscribe

To stop a running subscription without tearing down the entire WebSocket connection, send a complete message targeting the original subscription id. 
{
  "id": "my_id",
  "type": "complete"
}

​
Connection heartbeat

Codex requires a continuous handshake sequence to monitor stream viability and keep idle connections open.

​
Server ping

The server issues a periodic ping payload to check client responsiveness. 
{
  "type": "ping"
}

​
Client pong

Your client must immediately listen for this message and reply with a matching pong payload. Failure to respond will result in automated socket termination. 
{
  "type": "pong"
}

​
Pricing

Responses are billed using the shared WebSocket pricing formula:
  • 0.1 CU * 3,500 per response returned