--- updatedAt: 2026-04-26T18:58:54.000Z agentTools: projectIndex: https://docs.kyan.blue/llms.txt --- # Send heartbeat ping (dead man's switch) Send a heartbeat ping to keep your orders alive. If no heartbeat is received within the configured `timeout` period, all open orders for the maker are automatically cancelled. This acts as a **dead man's switch** for automated trading systems: if your bot crashes or loses connectivity, your orders are cancelled to prevent stale orders sitting on the book. **How it works:** 1. Call `POST /heartbeat` with your desired `timeout` (in seconds) 2. The server records the heartbeat configuration and last ping time 3. Continue calling periodically (before the timeout expires) 4. If a ping is missed beyond the timeout, all your open orders are cancelled **Authentication Options:** - **Signature**: Include `signature` and `signature_deadline` fields (uses EIP-712 `HeartbeatType`) - **One-click session**: Include `x-one-click` header with session hash (no signature needed) **Replay Protection:** When using signatures, the `signature_deadline` must be **strictly greater** than the last accepted deadline for this maker (deadline monotonicity). This prevents replay attacks without requiring per-call nonce storage. Deadlines are also bounded to at most 30 seconds in the future. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Premia V4 Public API", "description": "Public API for the Premia V4 platform providing traders and developers with programmatic access to options and perpetual futures trading.\nThis comprehensive API enables you to access market data, manage accounts, execute trades, and analyze portfolio risk with appropriate authentication.\n\n## Key Identifier Types\nThe API uses two primary identifier types throughout the trading system:\n- **order_id**: Unique identifier for individual limit orders. Generated as a 32-character hexadecimal string when a limit order is posted to the orderbook. Used for order management operations such as cancellation and status tracking.\n- **trade_id**: Unique identifier for executed trades. Generated as a 32-character hexadecimal string when a market order is filled against limit orders. Used for trade history tracking and settlement records.\n**Relationship**: Multiple trades can reference the same order_id when a single limit order is filled across multiple market orders (partial fills). Each trade execution generates a unique trade_id.\n\nThis document is organized following standard categories to help you integrate with the platform:\n1. Authentication/Session Management - API authentication methods and one-click trading sessions\n2. Market Data - Access real-time information about available instruments and market state\n3. Trading - Execute trades, place orders, and manage your positions \n4. Block RFQ - Request for Quote functionality for larger or custom trades\n5. Wallet - Deposit, withdraw, and transfer funds\n6. Account Management - Manage your trading account and view risk metrics\n", "version": "1.0.0", "contact": { "name": "Premia API Team", "url": "https://premia.io" }, "license": { "name": "Proprietary", "url": "https://premia.io/license" } }, "servers": [ { "url": "https://sandbox.kyan.sh", "description": "Sandbox server (REST API)" }, { "url": "https://staging.kyan.sh", "description": "Staging server (REST API)" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Trading", "description": "Endpoints for executing trades, placing orders, and managing positions" } ], "externalDocs": { "description": "Complete API Documentation", "url": "https://docs.kyan.blue/reference" }, "paths": { "/heartbeat": { "post": { "tags": [ "Trading" ], "summary": "Send heartbeat ping (dead man's switch)", "description": "Send a heartbeat ping to keep your orders alive. If no heartbeat is received within the configured `timeout` period, all open orders for the maker are automatically cancelled.\n\nThis acts as a **dead man's switch** for automated trading systems: if your bot crashes or loses connectivity, your orders are cancelled to prevent stale orders sitting on the book.\n\n**How it works:**\n1. Call `POST /heartbeat` with your desired `timeout` (in seconds)\n2. The server records the heartbeat configuration and last ping time\n3. Continue calling periodically (before the timeout expires)\n4. If a ping is missed beyond the timeout, all your open orders are cancelled\n\n**Authentication Options:**\n- **Signature**: Include `signature` and `signature_deadline` fields (uses EIP-712 `HeartbeatType`)\n- **One-click session**: Include `x-one-click` header with session hash (no signature needed)\n\n**Replay Protection:**\nWhen using signatures, the `signature_deadline` must be **strictly greater** than the last accepted deadline for this maker (deadline monotonicity). This prevents replay attacks without requiring per-call nonce storage. Deadlines are also bounded to at most 30 seconds in the future.\n", "operationId": "postHeartbeat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "maker", "timeout" ], "properties": { "maker": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "The maker address whose orders are protected by this heartbeat", "example": "0x1234567890123456789012345678901234567890" }, "timeout": { "type": "integer", "minimum": 5, "maximum": 300, "description": "Heartbeat timeout in seconds (5–300). If no heartbeat ping is received within this period, all open orders for the maker are automatically cancelled.\n", "example": 60 }, "signature": { "type": "string", "description": "EIP-712 signature of the HeartbeatType message. Required when not using one-click sessions.\n", "example": "0x..." }, "signature_deadline": { "type": "integer", "description": "Signature expiry timestamp (Unix seconds). Must be strictly greater than the last accepted deadline for this maker and at most 30 seconds in the future.\n", "example": 1704067260 } } }, "examples": { "withSignature": { "summary": "Heartbeat with EIP-712 signature", "value": { "maker": "0x1234567890123456789012345678901234567890", "timeout": 60, "signature": "0xabcdef...", "signature_deadline": 1704067260 } }, "withOneClick": { "summary": "Heartbeat with one-click session (no signature)", "value": { "maker": "0x1234567890123456789012345678901234567890", "timeout": 30 } } } } } }, "responses": { "200": { "description": "Heartbeat recorded successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" } } } } } }, "400": { "description": "Invalid request (validation error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "401": { "description": "Unauthorized - invalid signature, invalid or expired deadline (SIGNATURE_DEADLINE_INVALID), stale deadline (SIGNATURE_DEADLINE_STALE), or one-click session address mismatch (ONE_CT_USER_MISMATCH).\n\nWhen the error is `SIGNATURE_DEADLINE_INVALID`, the response includes timestamp fields to help diagnose clock skew: `serverTime` (current server Unix timestamp in seconds), `minTimestamp` and `maxTimestamp` (the acceptable deadline window), and `givenTimestamp` (the deadline value provided by the client).\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardError" }, { "type": "object", "properties": { "serverTime": { "type": "integer", "description": "Current server Unix timestamp in seconds (present for SIGNATURE_DEADLINE_INVALID)", "example": 1704067200 }, "minTimestamp": { "type": "integer", "description": "Minimum acceptable deadline in Unix seconds (present for SIGNATURE_DEADLINE_INVALID)", "example": 1704067200 }, "maxTimestamp": { "type": "integer", "description": "Maximum acceptable deadline in Unix seconds (present for SIGNATURE_DEADLINE_INVALID)", "example": 1704067230 }, "givenTimestamp": { "type": "integer", "description": "The deadline value provided by the client (present for SIGNATURE_DEADLINE_INVALID)", "example": 1704067100 } } } ] } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-apikey", "description": "API key for authentication. Generate and manage your own at https://app.kyan.blue/portfolio/api" } }, "schemas": { "StandardError": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code or message. Common error codes include:\n- `MIN_INCREMENT_PRICE_VIOLATION` - Order price is not divisible by the minimum price increment for the base asset\n- `MIN_SIZE_VIOLATION` - Order size is below the minimum requirement\n- `MIN_INCREMENT_SIZE_VIOLATION` - Order size is not divisible by the minimum size increment\n- `MAX_SLIPPAGE_VIOLATION` - Order price exceeds the maximum allowed slippage from fair value\n- `SIGNATURE_VALIDATION_ERROR` - Invalid or expired signature\n- `SIGNATURE_DEADLINE_INVALID` - Signature deadline is missing, expired, or outside the acceptable window. Response includes `serverTime`, `minTimestamp`, `maxTimestamp`, and `givenTimestamp` fields to help diagnose clock skew issues.\n- `SIGNATURE_DEADLINE_STALE` - Signature deadline is not strictly greater than the last accepted deadline for this maker (replay protection)\n- `ONE_CT_USER_MISMATCH` - One-click trading session was created by a different address than the maker/taker in the request\n- `VALUE_INVALID` - A request field has an invalid value (e.g., timeout out of range, or a legacy perpetual `amount` order submitted without the `price` needed to convert notional to contracts)\n- `INVALID_INSTRUMENT_NAME` - Instrument name format is invalid or instrument not found\n- `RFQ_REQUEST_ALREADY_EXISTS` - An RFQ request with the same identifier already exists (HTTP 409). The response data includes the conflicting `order_id`.\n- `RFQ_RESPONSE_ALREADY_EXISTS` - An RFQ response with the same identifier already exists (HTTP 409). The response data includes the conflicting `response_id`.\n- `RFQ_FILL_TAKER_RISK_FAILED` - Filling the RFQ would breach the taker's margin/risk limits (HTTP 400)\n- `RFQ_FILL_MAKER_RISK_FAILED` - Filling the RFQ would breach the maker's margin/risk limits (HTTP 400)\n", "example": "MIN_INCREMENT_PRICE_VIOLATION" }, "message": { "type": "string", "description": "Human-readable error description with details", "example": "Min price increment requirement violated for ETH_USDC-PERPETUAL. Price: 2500.15, Must be divisible by: 0.1" } }, "required": [ "error" ] } } } } ```