Codex

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:

Header: Include x-api-key: YOUR_API_KEY in your request headers.
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

Parameter	Required	Description
`apiKey` / `x-api-key`	Yes	Your 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:

Validate credentials: Send a GET request to the Codex HTTP validation endpoint using your preferred authentication method.
Establish WebSocket connection: Connect to the WSS endpoint using the graphql-transport-ws subprotocol.
Initialize session: Send a connection_init payload message containing your token authorization.
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.
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"
  }
}

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

Each response returned over the Codex WebSocket is billed at a flat rate:

3,500 CU per response returned

Websockets

Endpoints

Authentication

Parameters

Validate connection

Option 1: Header authentication

Option 2: URL authentication

Workflow

Protocol payloads

Initialize session

Unsubscribe

Connection heartbeat

Server ping

Client pong

Pricing

Resources

​Endpoints

​Authentication

​Parameters

​Validate connection

​Option 1: Header authentication

​Option 2: URL authentication

​Workflow

​Protocol payloads

​Initialize session

​Subscribe to streams

​Unsubscribe

​Connection heartbeat

​Server ping

​Client pong

​Pricing

​Resources

Endpoints

Authentication

Parameters

Validate connection

Option 1: Header authentication

Option 2: URL authentication

Workflow

Protocol payloads

Initialize session

Subscribe to streams

Unsubscribe

Connection heartbeat

Server ping

Client pong

Pricing

Resources