Introduction

An introductory summary of the Flipster API, outlining its purpose and key features.

Overview

The Flipster API provides programmatic access for all users to integrate advanced trading capabilities directly into their own applications or services.

Through our API service, you can manage accounts, retrieve real-time market data, and execute trading operations with secure authentication.

Host

All API requests should be made to the following host:

https://trading-api.flipster.io

This is the official production host for all live trading operations.

Make sure to use HTTPS for all communications to ensure data integrity and security.

⚙️ Note: Sandbox and staging environments for testing and development will be introduced in future updates. Please refer to the developer portal for announcements when they become available.

Supported Trading Modes

The Flipster API currently supports a variety of trading configurations to suit different strategies:

  • Trading Mode: Supports One-way trading. Multi-position mode will be added in a future update.

  • Margin Mode: Both Isolated and Cross Margin are available.

  • Order Types: Supports Market and Stop-Market (Price Trigger) orders. Limit orders and Time Trigger orders are planned for future support.

  • Market Type: Compatible with both Spot and Perpetual (Perp) markets.

Future updates will continue expanding trading flexibility and feature coverage.

API Naming Standard

To ensure consistency, readability, and scalability across all API endpoints, Flipster adopts a clear and structured naming convention for resources and actions. This standard allows developers to easily understand the purpose and hierarchy of each endpoint, regardless of module or service.

  • Base Path

All API routes start with a versioned base path:

/api/v1/

This versioning allows backward compatibility and smooth migration when the API evolves.

  • API Categories:

The Flipster API is organized into four main categories, each serving a distinct purpose. This modular design helps developers quickly locate endpoints relevant to their use cases.

trade

Allows users to perform trading actions such as placing, modifying, or canceling orders. It also supports position management, leverage adjustments, and margin operations. All trade endpoints require secure authentication and permissioned API keys.

market

Delivers real-time market data such as tickers, order books, and historical candlestick (kline) information. These endpoints enable developers to build trading dashboards or analytic systems based on live market conditions.

account

Offers authenticated access to user-specific information, including account summary, balances, and positions. API keys with read permission are required to query these endpoints.

public

Provides open access to general information such as server time and system status. These endpoints do not require authentication and are ideal for initial connectivity checks or public data retrieval.

Each category serves a distinct role within the trading ecosystem, ensuring clarity, security, and scalability across integrations.

HMAC-Based Authentication

To protect request integrity and prevent replay attacks, all authenticated requests must be signed using HMAC in addition to providing an API key. This ensures that each request is verifiably created by the key holder and has not been altered in transit.

What this means for you

  • HMAC is required for private endpoints: your client signs each request with your API secret.

  • Tamper-proof requests: the signature covers critical parts of the request so any modification will invalidate it.

  • Replay protection: timestamps (and optionally nonces) ensure a captured request cannot be reused.

  • Simple rollout: the HMAC layer complements the existing API key header and permission scopes (read, trade).

Minimal header contract

Include the following headers with private requests:

  • api-key: Your issued API key.

  • api-signature: The HMAC signature for the request.

  • api-expires: A Unix timestamp (in seconds) indicating when the request will expire. Requests past this time will be rejected.

Use the server time endpoint to keep your clock in sync and avoid timestamp drift.

Scope & compatibility

  • HMAC signing applies to all private REST endpoints and should be used for WebSocket authentication where applicable.

  • Implementation details (canonical string, hash algorithm, encoding, nonce usage, error codes) are documented on the HMAC Signing Guide page.

Rate Limiting & System Stability

To maintain fair access and protect the stability of the Flipster trading infrastructure, all API requests are subject to rate limits.

These limits prevent system overload, ensure consistent latency, and guarantee a reliable trading experience for all users.

Rate Limiting Policy

  • Each API key is assigned a request-per-second (RPS) and request-per-minute (RPM) quota.

  • When the rate limit is reached, the system temporarily throttles or rejects new requests with a 429 Too Many Requests error.

  • Limits may vary by endpoint type (public, market, trade, account) depending on the expected traffic and data sensitivity.

  • You can safely retry requests after the Retry-After header duration provided in the response.

Adaptive Delay for System Stability

To maintain consistent system performance during periods of high load, Flipster introduces automatic processing delays between certain API operations — particularly for trading and position updates.

  • A short delay (in milliseconds) may be applied after each order or margin-related request.

  • This ensures that the system can process requests sequentially and safely, minimizing concurrency conflicts or order queuing issues.

  • The delay mechanism is adaptive and scales dynamically based on current system traffic.

Note: These built-in delays are intentional and part of Flipster’s internal load-balancing strategy. They do not indicate performance degradation, but rather safeguard system reliability during burst activity.

Last updated