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 Component | Details |
|---|---|
| Trading Pairs | BTC_USDC, ETH_USDC |
| Base Tokens | BTC, ETH |
| Quote Token | USDC (6 decimal precision) |
Note on ARB:
ARB_USDC/ARBappears in some schema enums and historical references but is not currently active — orders cannot be placed against ARB markets. Only BTC and ETH are tradable.
Instrument Naming Format
| Instrument Type | Format | Example | Notes |
|---|---|---|---|
| Options | {PAIR}-{MATURITY}-{STRIKE}-{TYPE} | BTC_USDC-31OCT25-106000-C | TYPE: 'C' for call, 'P' for put |
| Perpetuals | {PAIR}-PERPETUAL | BTC_USDC-PERPETUAL | - |
Fee Structure
Introductory Period — Execution Fees WaivedKyan is in early release. During this period:
- Maker and taker fees are 0% across all markets and instruments, regardless of the standard schedule below.
- Systemic risk, liquidation, and settlement fees still apply as listed in the tables below.
The standard maker/taker schedule will apply when the introductory period ends; this page will be updated before that change takes effect.
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 Type | BTC_USDC | ETH_USDC |
|---|---|---|
| Maker Fee | 0% (0 bps) | 0% (0 bps) |
| Taker Fee | 0.08% (8 bps) | 0.08% (8 bps) |
| Liquidation Fee | 0.04% (4 bps) | 0.04% (4 bps) |
Options
| Fee Type | BTC_USDC | ETH_USDC |
|---|---|---|
| Maker Fee | 0.04% (4 bps) of index × contracts | 0.04% (4 bps) of index × contracts |
| Taker Fee | 0.04% (4 bps) of index × contracts | 0.04% (4 bps) of index × contracts |
| Liquidation Fee | 0.08% (8 bps) of index × contracts | 0.08% (8 bps) of index × contracts |
| Maximum Fee Cap | 12.5% of option premium (applies to trading & liquidation) | 12.5% of option premium (applies to trading & liquidation) |
Universal Fees
| Fee Type | All Instruments |
|---|---|
| Systemic Risk Fee | 0.0025% (0.25 bps) |
| Settlement Fee | 1.5 bps of delivery price (weekly/monthly options only — daily options exempt), capped at 12.5% of intrinsic value |
Notes:
- Perpetual fees are calculated on the notional value (amount × price)
- Options trading and liquidation fees are calculated on index price × contracts × fee rate, capped at 12.5% of option premium to prevent excessive charges on low-premium trades
- Systemic risk fee is applied to all trades
- Liquidation fees apply when positions are forcibly closed due to insufficient margin
- Settlement fee applies only to options at weekly/monthly expirations; daily-expiry options are exempt
Size Denomination
| Instrument Type | Denomination | Example |
|---|---|---|
| Options | Contracts | 1 contract = 1 unit of the base asset |
| Perpetuals | Dollar-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.
For detailed calculations, fallback logic, and settlement mechanics, see the Funding Rate Specification.
Funding Rate Calculation
Premium Index = (Perpetual Price - Index Price) / Index Price
Funding Rate = clamp(Premium Index × 0.9, -1.0%, +1.0%)
Settlement Process
| Parameter | Details |
|---|---|
| Frequency | Hourly settlements (00:00, 01:00, 02:00, etc. UTC) |
| Payment Formula | Position Size × Time-Weighted Average Rate |
| Direction | Long 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
| Parameter | Details |
|---|---|
| Primary Collateral | USDC |
| Calculation Method | Determined 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 Type | Count | Details |
|---|---|---|
| Daily | 2 | Short-term options |
| Weekly | 3 | Medium-term options |
| Monthly | 2 | Longer-term options |
| Strike Prices | Variable | Range based on current market prices |
| API Access | Available | Retrieve via API endpoints |
Note: New strikes and expirations are set (or updated) every day at 08:00 UTC.
ARB (Arbitrum) Token Naming Convention
Not currently active: ARB markets are not tradable today. The decimal-strike convention below is retained for reference and applies to any future market that requires fractional strikes.
| Symbol Format | Strike Value | Description |
|---|---|---|
1d250 | 1.25 | Decimal point represented by 'd' |
0d500 | 0.5 | Decimal strikes for fractional values |
Expiration
| Parameter | Details |
|---|---|
| Date Format | DDMMMYY (e.g., "31OCT25" for October 31, 2025) |
| Expiration Time | 8:00 AM UTC on the expiration date |
| Frequency | Weekly, monthly, and quarterly expirations |
| Settlement Price | Last index price |
| Settlement Currency | USDC |
| PnL Calculation | Realized PnL calculated and settled in USDC |
Mark Price
| Component | Details |
|---|---|
| Implied Volatility Feeds | Block Scholes with SVI volatility surface |
| Price Feeds | Chainlink price feeds for underlying assets |
| Volatility Surface | Stochastic Volatility Inspired (SVI) model parameters |
| Index Price Updates | Continuous updates |
| Volatility Updates | Real-time publishing |
| Mark Price Access | Real-time via WebSocket feeds |
| Liquidation Trigger | When equity falls below maintenance margin |
| Risk Monitoring | Real-time via WebSocket account_liquidation channel |
Risk
| Type | Description | Details |
|---|---|---|
| Initial Margin (IM) | Required to open new positions | Higher than maintenance margin requirements |
| Maintenance Margin (MM) | Minimum equity to maintain positions | Set at 1.2× the base requirement; liquidation triggered if equity falls below |
| Margin Ratios | IM/MM calibration | Based on asset volatility and market conditions; calibrated per asset class |
| Risk Matrix | Portfolio risk calculation | Comprehensive matrix using stress scenarios including price movements and volatility shifts |
| Delta Risk | Directional exposure risk | Additional margin requirements for large directional exposures; scales with delta exposure relative to market liquidity |
| Roll Risk | Near-expiry options risk | Additional risk charge for portfolios with near-expiry options to prevent manipulation around expiration events |
| Risk Model Parameters | Model calibration | Similar to industry-standard models (reference: Deribit); calibrated on historical data with different parameter sets for different asset classes |
API Key
| Parameter | Details |
|---|---|
| Purpose | Authenticated access to Kyan's REST and WebSocket APIs |
| Management | Managed through Unkey (enterprise key management service) |
| Required For | All trading operations and account-specific data access |
| How to Obtain | Contact Premia team via email, Discord, or premia.io |
Authentication
| Method | Details |
|---|---|
| REST API Header | Include API key in the x-apikey header |
| WebSocket | Provide API key in the initial auth message |
| Request Signing | Trading endpoints require EIP-712 signature |
| One-Click Trading | Establish 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 8 different signature types, each designed for specific operations:
For complete examples and implementation details for all signature types, see the EIP-712 Signatures Guide.
Overview of Signature Types
| Signature Type | Purpose | Usage |
|---|---|---|
| UserLimitOrder | Sign individual limit orders | Most common - used for placing buy/sell orders |
| UserMarketOrder | Sign market orders with limit protection | Market orders with slippage protection |
| UserComboOrder | Sign combo trades (multi-leg) | Complex strategies like spreads |
| CancelOrdersType | Cancel specific orders | Cancel selected orders by ID |
| CancelAllOrdersType | Cancel all orders | Emergency cancel all functionality |
| FillRFQType | Fill RFQ responses | Participate in Request for Quote trades |
| OneClickSignature | Create trading sessions | Avoid signing each individual order |
| HeartbeatType | Dead man's switch heartbeat | Auto-cancel orders if heartbeat stops |
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 8 signature types, see the EIP-712 Signatures Guide
Choosing Your Authentication Method
| Method | Best For | Pros | Cons |
|---|---|---|---|
| Individual Signatures | Occasional trading, maximum security | Full control, no session management | Must sign each operation |
| One-Click Sessions | Active trading, automated systems | Convenient, faster execution | Session management required |
Rate Limits
Rate limits are per-owner (keyed by x-owner-id, fallback to API key, then IP) with 1-second fixed windows. Market makers receive 5x the base limits.
Orderbook Service:
| Endpoint Category | Regular | Market Maker |
|---|---|---|
| Read | 15 req/s | 75 req/s |
| Trading | 10 req/s | 50 req/s |
| RFQ | 10 req/s | 50 req/s |
Sequencer Service:
| Endpoint Category | Regular | Market Maker |
|---|---|---|
| Read | 15 req/s | 75 req/s |
| Write | 3 req/s | 15 req/s |
| Create Safe | 1 req/s | 5 req/s |
Response Headers: Every response includes ratelimit-policy, ratelimit-limit, ratelimit-remaining, and ratelimit-reset headers.
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.
| Parameter | Details |
|---|---|
| Method | GET |
| Path | /account_state/{account} |
| Authentication | API key required (x-apikey header) |
| Signature | Not required |
| Rate Limit | Sequencer read tier (15 req/s regular, 75 req/s market maker) |
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
| Field | Description |
|---|---|
| pair | Trading pair symbol (e.g., "ETH_USDC") |
| timestamp | Unix timestamp when account state was calculated |
| margin_account | Margin account ID |
| equity | Current account equity |
| im | Initial margin requirement |
| mm | Maintenance margin requirement |
| matrix_risk | Portfolio risk matrix component |
| delta_risk | Delta risk component |
| roll_risk | Roll risk component |
| unrealised_pnl | Unrealized profit and loss |
| portfolio_greeks | Portfolio-level Greeks (delta, gamma, vega, theta, rho) |
| positions | Array of detailed positions with mark prices and Greeks |
| positions.instrument_type | Position instrument type ("option" or "perp") |
| positions.mark_price | Current mark price of the position |
| positions.position_greeks | Position-level Greeks for risk calculations |
This endpoint is particularly useful for:
- Building trading dashboards
- Portfolio monitoring applications
- Risk management systems
- Account health checks
Updated 6 days ago
