Documentation
Trade on KyanKyan Help Centre
Start typing to search…

Authentication

Authentication

All WebSocket connections must be authenticated before accessing any data. Send an AUTH message immediately after connecting.

📘

Learn More: For detailed API key setup and management, see the API Key Guide.

Trading Workflow

  1. Connect to the WebSocket endpoint
  2. Authenticate with your API key
  3. Discover available instruments
  4. Subscribe to market data channels
  5. Monitor your trades and account state

Connection Example

After authenticating, follow these steps to start trading:

1. Authenticate

import WebSocket from 'ws';

const wsUrl = 'wss://staging.kyan.sh/ws';
const API_KEY = 'your-api-key-here';

const authMessage = {
  type: 'auth',
  api_key: API_KEY,
};

const ws = new WebSocket(wsUrl);

ws.onopen = () => {
  ws.send(JSON.stringify(authMessage));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data.toString());

  if (message.type === 'auth' && message.success) {
    console.log('Authenticated! Ready to subscribe to channels.');
  } else if (message.type === 'auth' && !message.success) {
    console.error('Authentication failed:', message.error);
  }
};

2. Market Discovery

After authentication, discover available instruments using get_instruments:

// Get all available instruments for BTC
const message = {
  type: 'get_instruments',
  markets: ['BTC'],
};
ws.send(JSON.stringify(message));

3. Subscribe to Market Data

Subscribe to the channels you need for trading:

// Subscribe to instruments, index prices, and orderbook
const subscribeMessage = {
  type: 'subscribe',
  subscriptions: [
    {
      channel: 'instruments',
      query: { market: 'BTC' },
    },
    {
      channel: 'index_price',
      query: { pair: 'BTC_USDC' },
    },
    {
      channel: 'orderbook_perps',
      query: { pair: 'BTC_USDC' },
    },
  ],
};
ws.send(JSON.stringify(subscribeMessage));

4. Monitor Your Account

Track your trades and account activity:

// Subscribe to your account's trades and transfers
const accountSubscribe = {
  type: 'subscribe',
  subscriptions: [
    {
      channel: 'trade',
      query: { account: 'your-account-address' },
    },
    {
      channel: 'transfer',
      query: { account: 'your-account-address' },
    },
  ],
};
ws.send(JSON.stringify(accountSubscribe));

AUTH

Authenticate your WebSocket connection.

Request:

{
  "type": "auth",
  "api_key": "your-api-key-here",
  "id": "optional-request-id"
}

A valid API key must contain only letters, numbers, or underscores (pattern: ^[a-zA-Z0-9_]+$).

Success Response:

{
  "kind": "response",
  "type": "auth",
  "id": "optional-request-id",
  "timestamp_ms": 1677721600000,
  "success": true
}

Error Responses:

Invalid API key format:

{
  "kind": "response",
  "type": "error",
  "id": "optional-request-id",
  "timestamp_ms": 1677721600000,
  "success": false,
  "error": "invalid auth payload [{\"instancePath\":\"/api_key\",\"schemaPath\":\"#/properties/api_key/pattern\",\"keyword\":\"pattern\",\"params\":{\"pattern\":\"^[a-zA-Z0-9_]+$\"},\"message\":\"must match pattern \\\"^[a-zA-Z0-9_]+$\\\"\"}]"
}

API key not found or invalid:

{
  "kind": "response",
  "type": "auth",
  "id": "optional-request-id",
  "timestamp_ms": 1677721600000,
  "success": false,
  "error": "NOT_FOUND"
}

Other validation errors:

{
  "kind": "response",
  "type": "auth",
  "id": "optional-request-id",
  "timestamp_ms": 1677721600000,
  "success": false,
  "error": "Failed to validate api key"
}

Error Codes:

CodeDescription
NOT_FOUNDAPI key doesn't exist
FORBIDDENAPI key is disabled
KEY_USAGE_EXCEEDEDAPI key has exceeded usage limits
RATELIMITEDToo many requests
Session already authorizedAlready authenticated on this connection

Logout

End your current session.

Request:

{
  "type": "logout"
}

Response:

{
  "kind": "response",
  "type": "logout",
  "id": "optional-request-id",
  "timestamp_ms": 1677721600000,
  "success": true
}

Updated 1 day ago