> For the complete documentation index, see [llms.txt](https://docs.cielo.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cielo.finance/api-reference/websocket.md).

# WebSocket

Real-time stream of the same transactions as the feed, filtered by wallet, list, chain or transaction type.

## WebSocket Connection

> This endpoint sets up a WebSocket connection to receive updates on new transactions.\
> \
> Once connected, the client can send command messages to the WebSocket in the following formats:\
> \### Subscribe to a feed:\
> Refer to the \`FeedSubscribeCommand\` schema for the command structure.\
> \#### Subscribe to all feed events:\
> \`\`\`json\
> {\
> &#x20; "type": "subscribe\_feed",\
> }\
> \`\`\`\
> \#### Subscribe to feed with filters. Filters tx\_types, chains, tokens, min\_usd\_value, new\_trade are optional:\
> \`\`\`json\
> {\
> &#x20; "type": "subscribe\_feed",\
> &#x20; "filter": {\
> &#x20;     "tx\_types": \["transfer", "swap"],\
> &#x20;     "chains": \["eth", "bsc"],\
> &#x20;     "tokens": \["0x1234", "0x5678"],\
> &#x20;     "min\_usd\_value": 1000,\
> &#x20;     "new\_trade": true\
> &#x20; }\
> }\
> \`\`\`\
> \#### Subscribe to feed for an new trades:\
> \`\`\`json\
> {\
> &#x20; "type": "subscribe\_feed",\
> &#x20; "filter": {\
> &#x20;     "new\_trade": true\
> &#x20; }\
> }\
> \`\`\`\
> \### Subscribe to feed for a certain list:\
> \`\`\`json\
> {\
> &#x20; "type": "subscribe\_feed",\
> &#x20; "list\_id": 12345\
> }\
> \`\`\`\
> \### Unsubscribe from a feed:\
> Refer to the \`FeedUnsubscribeCommand\` schema for the command structure.\
> \`\`\`json\
> {\
> &#x20; "type": "unsubscribe\_feed"\
> }\
> \`\`\`\
> \### Subscribe to a wallet:\
> Refer to the \`WalletSubscribeCommand\` schema for the command structure.\
> \#### Subscribe to all wallet events:\
> \`\`\`json\
> {\
> &#x20;     "type": "subscribe\_wallet",\
> &#x20;     "wallet": "wallet-address",\
> }\
> \`\`\`\
> \#### Subscribe to wallet events with filters. Filters tx\_types, chains, tokens, min\_usd\_value, new\_trade are optional:\
> \`\`\`json\
> {\
> &#x20; "type": "subscribe\_wallet",\
> &#x20; "wallet": "wallet-address",\
> &#x20; "filter": {\
> &#x20;     "tx\_types": \["transfer", "swap"],\
> &#x20;     "chains": \["ethereum", "bsc"],\
> &#x20;     "tokens": \["0x1234", "0x5678"],\
> &#x20;     "min\_usd\_value": 1000,\
> &#x20;     "new\_trade": true\
> &#x20; }\
> }\
> \`\`\`\
> \### Unsubscribe from a wallet:\
> Refer to the \`WalletUnsubscribeCommand\` schema for the command structure.\
> \`\`\`json\
> {\
> &#x20; "type": "unsubscribe\_wallet",\
> &#x20; "wallet": "wallet-address"\
> }\
> \`\`\`\
> The server will send back messages in the following schema:\
> \### Websocket Event Message:\
> Refer to the \`WebsocketEvent\` schema for the message structure.\
> \`\`\`json\
> {\
> &#x20; "type": "event\_type",\
> &#x20; "data": {}\
> }\
> \`\`\`\
> \### Supported Chains\
> The \`chains\` filter accepts the same chain identifiers used by the REST API. The authoritative live list is available at \`GET /api/v1/chains\` — any value not in that list will be rejected by the server when the command is validated.\
> \
> \### Pricing Information\
> Every 10 messages sent over the WebSocket connection consume 1 credit.\
> \### Available Plans\
> Available on the following plans:\
> \- Builder\
> \- Architect\
> \- Enterprise<br>

````json
{"openapi":"3.0.0","info":{"title":"Cielo Public API","version":"1.0"},"tags":[{"name":"Web Socket","description":"Real-time stream of the same transactions as the feed, filtered by wallet, list, chain or transaction type."}],"servers":[{"url":"https://api.cielo.finance","description":"Endpoint"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"ErrorResponse":{"type":"object","description":"This object represents a response structure typically used to convey the outcome of a request. It primarily consists of a status indicator and a message, which together provide essential feedback about the request's processing. The status reflects the overall result of the request (such as success, error, etc.), while the message gives a more detailed explanation or the nature of the response, especially useful in cases of errors or exceptions.\n","properties":{"status":{"$ref":"#/components/schemas/ResponseStatus","description":"A reference to the response status object. This status is a key indicator of whether the request was processed successfully or resulted in an error."},"data":{"type":"object","description":"A flexible object intended to hold the actual data payload of the response. The structure of this object can vary depending on the specific endpoint and the nature of the response."},"message":{"type":"string","description":"A descriptive message providing additional details about the response. In case of an error, this message typically contains information useful for understanding the error's cause or nature."}},"required":["status","message"]},"ResponseStatus":{"type":"string","enum":["ok","error","pending"]}}},"paths":{"/api/v1/ws":{"get":{"tags":["Web Socket"],"summary":"WebSocket Connection","description":"This endpoint sets up a WebSocket connection to receive updates on new transactions.\n\nOnce connected, the client can send command messages to the WebSocket in the following formats:\n### Subscribe to a feed:\nRefer to the `FeedSubscribeCommand` schema for the command structure.\n#### Subscribe to all feed events:\n```json\n{\n  \"type\": \"subscribe_feed\",\n}\n```\n#### Subscribe to feed with filters. Filters tx_types, chains, tokens, min_usd_value, new_trade are optional:\n```json\n{\n  \"type\": \"subscribe_feed\",\n  \"filter\": {\n      \"tx_types\": [\"transfer\", \"swap\"],\n      \"chains\": [\"eth\", \"bsc\"],\n      \"tokens\": [\"0x1234\", \"0x5678\"],\n      \"min_usd_value\": 1000,\n      \"new_trade\": true\n  }\n}\n```\n#### Subscribe to feed for an new trades:\n```json\n{\n  \"type\": \"subscribe_feed\",\n  \"filter\": {\n      \"new_trade\": true\n  }\n}\n```\n### Subscribe to feed for a certain list:\n```json\n{\n  \"type\": \"subscribe_feed\",\n  \"list_id\": 12345\n}\n```\n### Unsubscribe from a feed:\nRefer to the `FeedUnsubscribeCommand` schema for the command structure.\n```json\n{\n  \"type\": \"unsubscribe_feed\"\n}\n```\n### Subscribe to a wallet:\nRefer to the `WalletSubscribeCommand` schema for the command structure.\n#### Subscribe to all wallet events:\n```json\n{\n      \"type\": \"subscribe_wallet\",\n      \"wallet\": \"wallet-address\",\n}\n```\n#### Subscribe to wallet events with filters. Filters tx_types, chains, tokens, min_usd_value, new_trade are optional:\n```json\n{\n  \"type\": \"subscribe_wallet\",\n  \"wallet\": \"wallet-address\",\n  \"filter\": {\n      \"tx_types\": [\"transfer\", \"swap\"],\n      \"chains\": [\"ethereum\", \"bsc\"],\n      \"tokens\": [\"0x1234\", \"0x5678\"],\n      \"min_usd_value\": 1000,\n      \"new_trade\": true\n  }\n}\n```\n### Unsubscribe from a wallet:\nRefer to the `WalletUnsubscribeCommand` schema for the command structure.\n```json\n{\n  \"type\": \"unsubscribe_wallet\",\n  \"wallet\": \"wallet-address\"\n}\n```\nThe server will send back messages in the following schema:\n### Websocket Event Message:\nRefer to the `WebsocketEvent` schema for the message structure.\n```json\n{\n  \"type\": \"event_type\",\n  \"data\": {}\n}\n```\n### Supported Chains\nThe `chains` filter accepts the same chain identifiers used by the REST API. The authoritative live list is available at `GET /api/v1/chains` — any value not in that list will be rejected by the server when the command is validated.\n\n### Pricing Information\nEvery 10 messages sent over the WebSocket connection consume 1 credit.\n### Available Plans\nAvailable on the following plans:\n- Builder\n- Architect\n- Enterprise\n","operationId":"getWebSocket","responses":{"101":{"description":"Switching Protocols - The server has switched protocols in response to a client request.","headers":{"Upgrade":{"description":"The protocol to which the server is switching.","schema":{"type":"string","enum":["websocket"],"default":"websocket"}},"Connection":{"description":"Indicates that the server is willing to upgrade the connection.","schema":{"type":"string","enum":["Upgrade"],"default":"Upgrade"}},"Sec-WebSocket-Accept":{"description":"A WebSocket-specific header used in the WebSocket handshake.","schema":{"type":"string"}}}},"403":{"description":"Forbidden - The client does not have access rights to the content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Something went wrong on the server's end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````
