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

# Quick Start

> Install the Socket.IO client, connect to the Chainworks API, and make your first request in TypeScript or Python.

Get up and running with the Chainworks API in just a few minutes.

## Prerequisites

* Node.js 18+ or Python 3.8+
* Chainworks API credentials (API URL and Auth Token)
* Basic understanding of either Socket.IO or HTTP requests

## Choosing a Transport

The Chainworks API exposes the same operations over two transports:

* **Socket.IO** keeps a persistent, bidirectional connection with low latency and real-time push (for example live price updates). Pick this for streaming or high-frequency trading.
* **HTTP** is stateless request and response. Pick this for simple integrations or when you cannot hold an open connection.

The request body and response shape are identical across transports, so the examples below show both. Use the toggle to switch.

## Installation

The Socket.IO transport needs a client library. The HTTP transport works with any HTTP client (the built-in `fetch` in JavaScript, or `requests` in Python), so it needs no SDK.

> [tab] Socket.IO
>
> ```bash TypeScript / JavaScript theme={null}
> npm install socket.io-client
> ```
>
> ```bash Python theme={null}
> pip install python-socketio
> ```

> [tab] HTTP
>
> No installation required. Use the built-in `fetch` (Node.js 18+ / browsers) or `requests` in Python:
>
> ```bash theme={null}
> pip install requests
> ```

## Connecting to the API

> [tab] Socket.IO
>
> Socket.IO opens a persistent connection and authenticates once during the handshake.
>
> ```typescript TypeScript theme={null}
> import { io } from "socket.io-client";
>
> const CHAINWORKS_API_URL = "https://api.chainworks.co";
> const CHAINWORKS_API_AUTH_TOKEN = "your-auth-token";
>
> const socket = io(CHAINWORKS_API_URL, {
>   transports: ["websocket"],
>   auth: {
>     token: CHAINWORKS_API_AUTH_TOKEN,
>   },
> });
>
> socket.on("connect", () => {
>   console.log("Connected to Chainworks API");
> });
>
> socket.on("connect_error", (error) => {
>   console.error("Connection failed:", error.message);
> });
>
> socket.on("disconnect", (reason) => {
>   console.log("Disconnected:", reason);
> });
> ```
>
> ```python Python theme={null}
> import socketio
>
> CHAINWORKS_API_URL = "https://api.chainworks.co"
> CHAINWORKS_API_AUTH_TOKEN = "your-auth-token"
>
> sio = socketio.Client()
>
> @sio.event
> def connect():
>     print("Connected to Chainworks API")
>
> @sio.event
> def connect_error(data):
>     print(f"Connection failed: {data}")
>
> @sio.event
> def disconnect():
>     print("Disconnected")
>
> sio.connect(
>     CHAINWORKS_API_URL,
>     transports=["websocket"],
>     auth={"token": CHAINWORKS_API_AUTH_TOKEN}
> )
> ```

> [tab] HTTP
>
> HTTP has no connection step. Each request is sent to the base URL and carries the auth token in the `Authorization` header (no `Bearer` prefix).
>
> ```typescript TypeScript theme={null}
> const CHAINWORKS_API_URL = "https://api.chainworks.co";
> const CHAINWORKS_API_AUTH_TOKEN = "your-auth-token";
> ```
>
> ```python Python theme={null}
> CHAINWORKS_API_URL = "https://api.chainworks.co"
> CHAINWORKS_API_AUTH_TOKEN = "your-auth-token"
> ```

## Your First Request

Let's get a buy quote for a token on Ethereum:

> [tab] Socket.IO
>
> ```typescript TypeScript theme={null}
> // Request a buy quote
> socket.emit("/evm/buy/quote", {
>   chain: "eth",
>   token: "0x6982508145454Ce325dDbE47a25d4ec3d2311933", // PEPE
>   swapMode: "ExactIn",
>   amountIn: "1000000000000000000", // 1 ETH in wei
>   wallet: "0xYourWalletAddress",
> });
>
> // Listen for the response
> socket.on("/evm/buy/quote", (response) => {
>   if (response.success) {
>     console.log("Price:", response.result.price);
>     console.log("Expected output:", response.result.expectedAmountOut);
>     console.log("Price impact:", response.result.priceImpact);
>   } else {
>     console.error("Error:", response.error.message);
>   }
> });
> ```
>
> ```python Python theme={null}
> @sio.on("/evm/buy/quote")
> def on_quote(response):
>     if response.get("success"):
>         result = response["result"]
>         print(f"Price: {result['price']}")
>         print(f"Expected output: {result['expectedAmountOut']}")
>         print(f"Price impact: {result['priceImpact']}")
>     else:
>         print(f"Error: {response['error']['message']}")
>
> sio.emit("/evm/buy/quote", {
>     "chain": "eth",
>     "token": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
>     "swapMode": "ExactIn",
>     "amountIn": "1000000000000000000",
>     "wallet": "0xYourWalletAddress"
> })
> ```

> [tab] HTTP
>
> ```typescript TypeScript theme={null}
> const res = await fetch(`${CHAINWORKS_API_URL}/evm/buy/quote`, {
>   method: "POST",
>   headers: {
>     "Content-Type": "application/json",
>     Authorization: CHAINWORKS_API_AUTH_TOKEN,
>   },
>   body: JSON.stringify({
>     chain: "eth",
>     token: "0x6982508145454Ce325dDbE47a25d4ec3d2311933", // PEPE
>     swapMode: "ExactIn",
>     amountIn: "1000000000000000000", // 1 ETH in wei
>     wallet: "0xYourWalletAddress",
>   }),
> });
>
> const response = await res.json();
> if (response.success) {
>   console.log("Price:", response.result.price);
>   console.log("Expected output:", response.result.expectedAmountOut);
>   console.log("Price impact:", response.result.priceImpact);
> } else {
>   console.error("Error:", response.error.message);
> }
> ```
>
> ```python Python theme={null}
> import requests
>
> res = requests.post(
>     f"{CHAINWORKS_API_URL}/evm/buy/quote",
>     headers={"Authorization": CHAINWORKS_API_AUTH_TOKEN},
>     json={
>         "chain": "eth",
>         "token": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
>         "swapMode": "ExactIn",
>         "amountIn": "1000000000000000000",
>         "wallet": "0xYourWalletAddress",
>     },
> )
>
> response = res.json()
> if response.get("success"):
>     result = response["result"]
>     print(f"Price: {result['price']}")
>     print(f"Expected output: {result['expectedAmountOut']}")
>     print(f"Price impact: {result['priceImpact']}")
> else:
>     print(f"Error: {response['error']['message']}")
> ```

## Response Format

Both transports return the same response shape:

### Success Response

```json theme={null}
{
  "success": true,
  "result": {
    // Response data specific to the endpoint
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  },
  "partialResult": {
    // Optional helpful data even when request fails
  }
}
```

## Next Steps

* [Authentication](https://docs.chainworks.org/authentication.md) - Learn about token authentication
* [EVM Endpoints](https://docs.chainworks.org/evm/overview.md) - Explore Ethereum, Base, and BSC endpoints
* [SVM Endpoints](https://docs.chainworks.org/svm/overview.md) - Explore Solana endpoints
* [Playground](https://chainworks.co/playground) - Test the API interactively


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.