> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniblock.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Connect to Codex GraphQL subscription streams through Uniblock WebSockets.

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

| 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

<Note>
  Header authentication is recommended to avoid exposing your API key in server
  logs or URLs.
</Note>

```bash theme={null}
curl --location 'https://websocket.uniblock.dev/codex/validate' \
  --header 'x-api-key: YOUR_API_KEY'
```

### Option 2: URL authentication

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "type": "pong"
}
```

## Pricing

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

* `3,500 CU` per response returned

## Resources

* [Codex Documentation](https://docs.codex.io/)
* [Codex Subscriptions](https://docs.codex.io/concepts/subscriptions#custom)