Chainworks
Documentation

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 WebSocket communication

Installation

TypeScript/JavaScript

bash
npm install socket.io-client

Python

bash
pip install python-socketio

Connecting to the API

The Chainworks API uses WebSocket connections via Socket.IO. This provides real-time, bidirectional communication with low latency.

TypeScript

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

Your First Request

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

TypeScript

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

Response Format

All API responses follow a consistent format:

Success Response

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

Error Response

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

Next Steps