Getting Started with Kyan

Getting Started with Kyan

This guide provides essential information for getting started with the Kyan platform.

Product Specifications

Available Markets

Market ComponentDetails
Trading PairsBTC_USDC, ETH_USDC, ARB_USDC
Base TokensBTC, ETH, ARB
Quote TokenUSDC (6 decimal precision)

Instrument Naming Format

Instrument TypeFormatExampleNotes
Options{PAIR}-{MATURITY}-{STRIKE}-{TYPE}BTC_USDC-31OCT25-106000-CTYPE: 'C' for call, 'P' for put
Perpetuals{PAIR}-PERPETUALBTC_USDC-PERPETUAL-

Fee Structure

Trading fees are calculated as a percentage of the trade value and depend on the instrument type. All fees are charged in USDC.

Perpetual Futures

Fee TypeBTC_USDCETH_USDCARB_USDC
Maker Fee0% (0 bps)0% (0 bps)0% (0 bps)
Taker Fee0.08% (8 bps)0.08% (8 bps)0.08% (8 bps)
Liquidation Fee0.15% (15 bps)0.15% (15 bps)0.25% (25 bps)

Options

Fee TypeBTC_USDCETH_USDCARB_USDC
Maker Fee0.04% (4 bps)0.04% (4 bps)0.08% (8 bps)
Taker Fee0.04% (4 bps)0.04% (4 bps)0.08% (8 bps)
Liquidation Fee0.19% of index × option price × 25%0.19% of index × option price × 25%0.19% of index × option price × 25%
Maximum Fee Cap12.5% of option premium12.5% of option premium12.5% of option premium

Universal Fees

Fee TypeAll Instruments
Delivery Fee0.02% (2 bps)
Systemic Risk Fee0.0025% (0.25 bps)

Notes:

  • Perpetual fees are calculated on the notional value (amount × price)
  • Options fees are calculated on index price × contracts × fee rate
  • Option fees are capped at 12.5% of the option premium to prevent excessive charges on low-premium trades
  • Options liquidation fee = (Index × 0.19% × Option Price × 25% × Contracts) - Regular trading fee
  • Systemic risk fee is applied to all trades
  • Liquidation fees apply when positions are forcibly closed due to insufficient margin

Size Denomination

Instrument TypeDenominationExample
OptionsContracts1 contract = 1 unit of the base asset
PerpetualsDollar-notional$10,000 instead of 1 BTC

Perpetuals Funding

Kyan implements a continuous funding mechanism to ensure perpetual contract prices converge to their underlying index prices.

Funding Rate Calculation

Premium Index = (Perpetual Price - Index Price) / Index Price
Funding Rate = clamp(Premium Index × 0.9, -1.0%, +1.0%)

Settlement Process

ParameterDetails
FrequencyHourly settlements (00:00, 01:00, 02:00, etc. UTC)
Payment FormulaPosition Size × Time-Weighted Average Rate
DirectionLong positions pay when perpetual price > index price (positive funding)

Payment Direction

When the perpetual price is above the index price (positive funding rate), longpositions pay shorts. When below (negative funding rate), shorts pay longs.

Collateral Requirements

ParameterDetails
Primary CollateralUSDC
Calculation MethodDetermined by the risk model (see Risk section)

Important Note for Arbitrum Sepolia: The mockUSDC token address on Arbitrum Sepolia is 0x07a7D6b723d0aa62cD78da00452Ba3cD3b72C3d7. This is not the actual USDC contract on Sepolia - it's a mock token used for testing purposes.

Available Expirations & Strikes

Expiration TypeCountDetails
Daily2Short-term options
Weekly3Medium-term options
Monthly2Longer-term options
Strike PricesVariableRange based on current market prices
API AccessAvailableRetrieve via API endpoints

Note: New strikes and expirations are set (or updated) every day at 08:00 UTC.

ARB (Arbitrum) Token Naming Convention

Symbol FormatStrike ValueDescription
1d2501.25Decimal point represented by 'd'
0d5000.5Decimal strikes for fractional values

Expiration

ParameterDetails
Date FormatDDMMMYY (e.g., "31OCT25" for October 31, 2025)
Expiration Time8:00 AM UTC on the expiration date
FrequencyWeekly, monthly, and quarterly expirations
Settlement PriceLast index price
Settlement CurrencyUSDC
PnL CalculationRealized PnL calculated and settled in USDC

Mark Price

ComponentDetails
Implied Volatility FeedsBlock Scholes with SVI volatility surface
Price FeedsChainlink price feeds for underlying assets
Volatility SurfaceStochastic Volatility Inspired (SVI) model parameters
Index Price UpdatesContinuous updates
Volatility UpdatesReal-time publishing
Mark Price AccessReal-time via WebSocket feeds
Liquidation TriggerWhen equity falls below maintenance margin
Risk MonitoringReal-time via WebSocket account_liquidation channel

Risk

TypeDescriptionDetails
Initial Margin (IM)Required to open new positionsHigher than maintenance margin requirements
Maintenance Margin (MM)Minimum equity to maintain positionsSet at 1.2× the base requirement; liquidation triggered if equity falls below
Margin RatiosIM/MM calibrationBased on asset volatility and market conditions; BTC & ETH have lower requirements than ARB
Risk MatrixPortfolio risk calculationComprehensive matrix using stress scenarios including price movements and volatility shifts
Delta RiskDirectional exposure riskAdditional margin requirements for large directional exposures; scales with delta exposure relative to market liquidity
Roll RiskNear-expiry options riskAdditional risk charge for portfolios with near-expiry options to prevent manipulation around expiration events
Risk Model ParametersModel calibrationSimilar to industry-standard models (reference: Deribit); calibrated on historical data with different parameter sets for different asset classes

API Key

ParameterDetails
PurposeAuthenticated access to Kyan's REST and WebSocket APIs
ManagementManaged through Unkey (enterprise key management service)
Required ForAll trading operations and account-specific data access
How to ObtainContact Premia team via email, Discord, or premia.io

Authentication

MethodDetails
REST API HeaderInclude API key in the x-apikey header
WebSocketProvide API key in the initial auth message
Request SigningTrading endpoints require EIP-712 signature
One-Click TradingEstablish sessions to avoid signing each transaction

Note on One-Click Trading (1-CT): One-Click Trading sessions are valid for 24 hours. The 24-hour window is automatically refreshed whenever you perform certain actions including: submitting market or limit orders, canceling orders, placing combo trades, and participating in RFQ (Request for Quote)transactions.

EIP-712 Signatures

Kyan uses EIP-712 typed data signatures for secure authentication of trading operations. There are 7 different signature types, each designed for specific operations:

Overview of Signature Types

Signature TypePurposeUsage
UserLimitOrderSign individual limit ordersMost common - used for placing buy/sell orders
UserMarketOrderSign market orders with limit protectionMarket orders with slippage protection
UserComboOrderSign combo trades (multi-leg)Complex strategies like spreads
CancelOrdersTypeCancel specific ordersCancel selected orders by ID
CancelAllOrdersTypeCancel all ordersEmergency cancel all functionality
FillRFQTypeFill RFQ responsesParticipate in Request for Quote trades
OneClickSignatureCreate trading sessionsAvoid signing each individual order

EIP-712 Domain

All signatures use the same domain configuration:

const EIP712Domain = {
  chainId: 421614, // Arbitrum Sepolia (use 42161 for Arbitrum One mainnet)
  name: 'Premia',
  verifyingContract: '0x...', // ClearingHouseProxy address from deployment
  version: '1',
};

Quick Start Example: Limit Orders

The most common signature type is UserLimitOrder. Here's a complete example:

import { parseUnits, zeroAddress } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

// Your order data
const order = {
  instrument_name: 'BTC_USDC-31OCT25-130000-C',
  contracts: 1.5,
  direction: 'buy',
  price: 1000.5,
  post_only: true,
  mmp: false,
  liquidation: false,
  maker: '0xYourAddress',
  taker: null, // Any taker
};

// Calculate deadline (30 seconds from now)
const deadline = Math.floor(Date.now() / 1000) + 30;

// Setup wallet
const account = privateKeyToAccount('0xYourPrivateKey');

// Type definition for limit orders
const UserLimitOrder = [
  { name: 'deadline', type: 'uint256' },
  { name: 'instrumentName', type: 'string' },
  { name: 'size', type: 'uint256' },
  { name: 'price', type: 'uint256' },
  { name: 'taker', type: 'address' },
  { name: 'maker', type: 'address' },
  { name: 'direction', type: 'uint8' },
  { name: 'isLiquidation', type: 'bool' },
  { name: 'isPostOnly', type: 'bool' },
  { name: 'mmp', type: 'bool' },
];

// Sign the typed data
const signature = await account.signTypedData({
  domain: EIP712Domain,
  types: { UserLimitOrder },
  primaryType: 'UserLimitOrder',
  message: {
    deadline,
    instrumentName: order.instrument_name,
    size: parseUnits(order.contracts.toString(), 6), // 6 decimal precision
    price: parseUnits(order.price.toString(), 6),
    taker: order.taker ?? zeroAddress,
    maker: order.maker,
    direction: order.direction === 'buy' ? 0 : 1, // Buy=0, Sell=1
    isLiquidation: order.liquidation,
    isPostOnly: order.post_only,
    mmp: order.mmp,
  },
});

// Submit the order
const response = await fetch('/limit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-apikey': 'your-api-key',
  },
  body: JSON.stringify([
    {
      ...order,
      signature,
      signature_deadline: deadline,
    },
  ]),
});

One-Click Trading Alternative

Instead of signing each order, you can create a session:

// Create a one-click session
const sessionDeadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour

const OneClickSignature = [
  { name: 'deadline', type: 'uint256' },
  { name: 'user', type: 'address' },
  { name: 'bindToIp', type: 'bool' },
];

const sessionSignature = await account.signTypedData({
  domain: EIP712Domain,
  types: { OneClickSignature },
  primaryType: 'OneClickSignature',
  message: {
    deadline: sessionDeadline,
    user: '0xYourAddress',
    bindToIp: true,
  },
});

// Create session
const sessionResponse = await fetch('/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user: '0xYourAddress',
    bind_to_ip: true,
    signature_deadline: sessionDeadline,
    signature: sessionSignature,
  }),
});

const { hash } = await sessionResponse.json();

// Now use session for orders (no signature needed)
const orderResponse = await fetch('/limit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-apikey': 'your-api-key',
    'x-one-click': hash, // Use session instead of signature
  },
  body: JSON.stringify([
    {
      instrument_name: 'BTC_USDC-31OCT25-130000-C',
      contracts: 1.5,
      direction: 'buy',
      price: 1000.5,
      post_only: true,
      mmp: false,
      liquidation: false,
      maker: '0xYourAddress',
      taker: null,
      // No signature or signature_deadline needed!
    },
  ]),
});

Important Implementation Notes

  • Field Precision: All numeric values (size, price) must be converted to 6-decimal precision
  • Direction Mapping: Buy = 0, Sell = 1 in signatures
  • Taker Defaults: If no taker specified, use zeroAddress
  • Deadline Validation: Must be within 30 seconds for most operations
  • Account Support: Works with both EOA wallets and Safe (multisig) wallets

📚 For complete examples of all 7 signature types, see the EIP-712 Signatures Guide

Choosing Your Authentication Method

MethodBest ForProsCons
Individual SignaturesOccasional trading, maximum securityFull control, no session managementMust sign each operation
One-Click SessionsActive trading, automated systemsConvenient, faster executionSession management required

Rate Limits

Endpoint CategoryRate Limit
Market Data20 requests per second
Trading Operations5 requests per second
Account Operations2 requests per second
RFQ Endpoints6 requests per minute

Error Handling: When rate limits are exceeded, requests are rejected with HTTP 429 status code. Implement exponential backoff for retry strategies.

Account Monitoring

Account State Endpoint

The /account_state/{account} endpoint provides comprehensive account information without requiring cryptographic signatures, making it ideal for dashboard applications and account monitoring.

ParameterDetails
MethodGET
Path/account_state/{account}
AuthenticationAPI key required (x-apikey header)
SignatureNot required
Rate LimitAccount Operations category (2 requests per second)

Example Request

curl -X GET "https://staging.kyan.sh/account_state/0x1234567890abcdef1234567890abcdef12345678" \
  -H "x-apikey: your-api-key-here"

Example Response

{
  "margin_accounts": [
    {
      "pair": "ETH_USDC",
      "timestamp": 1677721600000,
      "margin_account": 12345,
      "im": 2000.0,
      "mm": 1500.0,
      "matrix_risk": 1200.0,
      "delta_risk": 800.0,
      "roll_risk": 300.0,
      "unrealised_pnl": 500.0,
      "equity": 10500.0,
      "portfolio_greeks": {
        "delta": 0.45,
        "gamma": 0.0012,
        "vega": 125.3,
        "theta": -45.5,
        "rho": 85.2
      },
      "positions": [
        {
          "instrument_type": "option",
          "instrument": "ETH_USDC-31OCT25-4700-P",
          "size": -2.0,
          "average_price": 65.0,
          "entry_fees": 0.1,
          "mark_price": 67.5,
          "mark_iv": 0.65,
          "mark_interest": 0.05,
          "position_greeks": {
            "delta": -0.35,
            "gamma": 0.0008,
            "theta": -12.5,
            "vega": 45.2,
            "rho": -15.8
          }
        }
      ]
    },
    {
      "pair": "BTC_USDC",
      "timestamp": 1677721580000,
      "margin_account": 12346,
      "im": 5000.0,
      "mm": 3750.0,
      "matrix_risk": 2800.0,
      "delta_risk": 1500.0,
      "roll_risk": 200.0,
      "unrealised_pnl": -250.0,
      "equity": 25000.0,
      "portfolio_greeks": {
        "delta": 0.25,
        "gamma": 0.0005,
        "vega": 85.1,
        "theta": -25.2,
        "rho": 120.5
      },
      "positions": [
        {
          "instrument_type": "perp",
          "instrument": "BTC_USDC-PERPETUAL",
          "size": 0.5,
          "average_price": 45000.0,
          "entry_fees": 18.0,
          "mark_price": 45010.0,
          "current_funding_rate": 0.0001,
          "position_greeks": {
            "delta": 0.5
          }
        }
      ]
    }
  ]
}

Response Fields

FieldDescription
pairTrading pair symbol (e.g., "ETH_USDC")
timestampUnix timestamp when account state was calculated
margin_accountMargin account ID
equityCurrent account equity
imInitial margin requirement
mmMaintenance margin requirement
matrix_riskPortfolio risk matrix component
delta_riskDelta risk component
roll_riskRoll risk component
unrealised_pnlUnrealized profit and loss
portfolio_greeksPortfolio-level Greeks (delta, gamma, vega, theta, rho)
positionsArray of detailed positions with mark prices and Greeks
positions.instrument_typePosition instrument type ("option" or "perp")
positions.mark_priceCurrent mark price of the position
positions.position_greeksPosition-level Greeks for risk calculations

This endpoint is particularly useful for:

  • Building trading dashboards
  • Portfolio monitoring applications
  • Risk management systems
  • Account health checks