Quick Start

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.

Socket.IO
HTTP

npm install socket.io-client

pip install python-socketio

No installation required. Use the built-in fetch (Node.js 18+ / browsers) or requests in Python:

pip install requests

Connecting to the API

Socket.IO
HTTP

Socket.IO opens a persistent connection and authenticates once during the handshake.

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);
});

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}
)

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).

const CHAINWORKS_API_URL = "https://api.chainworks.co";
const CHAINWORKS_API_AUTH_TOKEN = "your-auth-token";

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:

Socket.IO
HTTP

// 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);
  }
});

@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"
})

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);
}

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

{
  "success": true,
  "result": {
    // Response data specific to the endpoint
  }
}

Error Response

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

Next Steps

Authentication - Learn about token authentication
EVM Endpoints - Explore Ethereum, Base, and BSC endpoints
SVM Endpoints - Explore Solana endpoints
Playground - Test the API interactively

Getting Started

SVM (Solana)

EVM Chains

Reference

Prerequisites

Choosing a Transport

Installation

Connecting to the API

Your First Request

Response Format

Success Response

Error Response

Next Steps

​Prerequisites

​Choosing a Transport

​Installation

​Connecting to the API

​Your First Request

​Response Format

​Success Response

​Error Response

​Next Steps

Prerequisites

Choosing a Transport

Installation

Connecting to the API

Your First Request

Response Format

Success Response

Error Response

Next Steps