> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainworks.co/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.

<Tabs>
  <Tab title="Socket.IO">
    <CodeGroup>
      ```bash TypeScript / JavaScript theme={null}
      npm install socket.io-client
      ```

      ```bash Python theme={null}
      pip install python-socketio
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HTTP">
    No installation required. Use the built-in `fetch` (Node.js 18+ / browsers) or `requests` in Python:

    ```bash theme={null}
    pip install requests
    ```
  </Tab>
</Tabs>

## Connecting to the API

<Tabs>
  <Tab title="Socket.IO">
    Socket.IO opens a persistent connection and authenticates once during the handshake.

    <CodeGroup>
      ```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}
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="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).

    <CodeGroup>
      ```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"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Your First Request

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

<Tabs>
  <Tab title="Socket.IO">
    <CodeGroup>
      ```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"
      })
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HTTP">
    <CodeGroup>
      ```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']}")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 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](/authentication) - Learn about token authentication
* [EVM Endpoints](/evm/overview) - Explore Ethereum, Base, and BSC endpoints
* [SVM Endpoints](/svm/overview) - Explore Solana endpoints
* [Playground](https://chainworks.co/playground) - Test the API interactively