Home
Documentation
Playground

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