From 1488f52a5938bb2cfa54f761f9a7e8c79b613bec Mon Sep 17 00:00:00 2001 From: 0X-SquidSol Date: Thu, 9 Apr 2026 11:54:58 -0400 Subject: [PATCH] docs: add missing OpenAPI spec entries for historySince, ADL rankings, and chart MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three fully implemented endpoints were absent from openapi.yaml: - GET /funding/{slab}/historySince — funding history with required `since` param - GET /api/adl/rankings — ADL trigger state and ranked profitable positions - GET /chart/{mint} — OHLCV candlestick data via GeckoTerminal Adds path entries with accurate parameters, response schemas, status codes, and custom headers (X-Cache for ADL). Also adds corresponding component schemas: AdlRankingsResponse, AdlRankedPosition, ChartResponse, OhlcvCandle. Co-Authored-By: Claude Opus 4.6 (1M context) --- openapi.yaml | 255 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 9fc22e8..a32b081 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -56,6 +56,10 @@ tags: description: Oracle price resolution - name: Stats description: Platform-wide statistics + - name: ADL + description: Auto-deleveraging rankings and trigger state + - name: Chart + description: OHLCV candlestick chart data - name: WebSocket description: WebSocket metrics and real-time data streaming @@ -500,6 +504,157 @@ paths: '500': $ref: '#/components/responses/InternalServerError' + /funding/{slab}/historySince: + get: + tags: + - Funding + summary: Get funding history since a timestamp + description: | + Returns funding rate history starting from a required `since` timestamp. + Similar to /funding/{slab}/history but with a mandatory start time. + operationId: getMarketFundingHistorySince + parameters: + - $ref: '#/components/parameters/SlabAddress' + - name: since + in: query + required: true + description: | + Start timestamp — ISO 8601 string or Unix epoch (seconds or milliseconds). + Must resolve to a year between 2020 and 2100. + schema: + type: string + - name: limit + in: query + description: Maximum number of records to return (max 500) + schema: + type: integer + default: 100 + minimum: 1 + maximum: 500 + responses: + '200': + description: Successfully retrieved funding history + content: + application/json: + schema: + type: object + properties: + slabAddress: + type: string + since: + type: string + format: date-time + description: Validated ISO 8601 start timestamp + count: + type: integer + history: + type: array + items: + $ref: '#/components/schemas/FundingHistoryEntry' + '400': + $ref: '#/components/responses/BadRequest' + '500': + $ref: '#/components/responses/InternalServerError' + + /api/adl/rankings: + get: + tags: + - ADL + summary: Get ADL trigger state and rankings + description: | + Fetches on-chain slab data, checks ADL (Auto-Deleveraging) trigger conditions, + and returns a ranked list of profitable positions eligible for auto-deleveraging. + This is a read-only endpoint — it does NOT dispatch any on-chain transactions. + Results are cached in-memory for 15 seconds. + operationId: getAdlRankings + parameters: + - name: slab + in: query + required: true + description: Market slab address (Solana public key) + schema: + type: string + pattern: '^[1-9A-HJ-NP-Za-km-z]{32,44}$' + responses: + '200': + description: ADL trigger state and ranked positions + headers: + X-Cache: + schema: + type: string + enum: [HIT, MISS] + description: Whether the response was served from the 15s in-memory cache + content: + application/json: + schema: + $ref: '#/components/schemas/AdlRankingsResponse' + '400': + $ref: '#/components/responses/BadRequest' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' + '504': + description: Upstream Solana RPC timeout + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + example: + error: Upstream RPC timeout + slab: "ABC123..." + + /chart/{mint}: + get: + tags: + - Chart + summary: Get OHLCV candle data + description: | + Returns OHLCV candlestick data for a Solana SPL token by mint address. + Data is sourced from GeckoTerminal. Responses are cached in-memory for 60 seconds. + Returns an empty candles array (not an error) when no DEX pool is found. + operationId: getChart + parameters: + - name: mint + in: path + required: true + description: Solana SPL token mint address + schema: + type: string + pattern: '^[1-9A-HJ-NP-Za-km-z]{32,44}$' + - name: timeframe + in: query + description: Candle timeframe + schema: + type: string + enum: [minute, hour, day] + default: hour + - name: aggregate + in: query + description: | + Candle aggregation factor. Allowed values depend on timeframe: + minute: 1, 5, 15 (default 5); hour: 1, 4, 12 (default 1); day: 1 (default 1). + Default varies by timeframe — omit to use the timeframe-specific default. + schema: + type: integer + - name: limit + in: query + description: Number of candles to return (max 500) + schema: + type: integer + default: 168 + minimum: 1 + maximum: 500 + responses: + '200': + description: OHLCV candle data + content: + application/json: + schema: + $ref: '#/components/schemas/ChartResponse' + '400': + $ref: '#/components/responses/BadRequest' + /open-interest/{slab}: get: tags: @@ -1036,6 +1191,106 @@ components: type: integer description: Total number of trades in last 24 hours + AdlRankingsResponse: + type: object + properties: + slabAddress: + type: string + pnlPosTot: + type: string + description: Total positive PnL across all positions (bigint as string) + maxPnlCap: + type: string + description: Maximum PnL cap from market config (bigint as string) + insuranceFundBalance: + type: string + description: Insurance fund balance (bigint as string) + insuranceFundFeeRevenue: + type: string + description: Insurance fund fee revenue (bigint as string) + insuranceUtilizationBps: + type: integer + minimum: 0 + maximum: 10000 + description: Insurance utilization in basis points + capExceeded: + type: boolean + description: Whether total positive PnL exceeds the max PnL cap + insuranceDepleted: + type: boolean + description: Whether the insurance fund is depleted + utilizationTriggered: + type: boolean + description: Whether insurance utilization exceeds the threshold + adlNeeded: + type: boolean + description: Whether auto-deleveraging is needed (capExceeded OR utilizationTriggered) + excess: + type: string + description: Amount by which PnL exceeds cap (bigint as string, "0" if no excess) + rankings: + type: array + description: Ranked profitable positions (empty when adlNeeded is false) + items: + $ref: '#/components/schemas/AdlRankedPosition' + + AdlRankedPosition: + type: object + properties: + rank: + type: integer + minimum: 1 + description: Position rank (1 = highest PnL%) + idx: + type: integer + description: Account index in slab + pnlAbs: + type: string + description: Absolute PnL (bigint as string) + capital: + type: string + description: Position capital (bigint as string) + pnlPctMillionths: + type: string + description: PnL percentage scaled by 1,000,000 (bigint as string) + + ChartResponse: + type: object + properties: + candles: + type: array + items: + $ref: '#/components/schemas/OhlcvCandle' + poolAddress: + type: string + nullable: true + description: GeckoTerminal DEX pool address (null if no pool found) + cached: + type: boolean + description: Whether the response was served from cache + + OhlcvCandle: + type: object + properties: + timestamp: + type: integer + description: Unix timestamp in milliseconds + open: + type: number + format: double + high: + type: number + format: double + low: + type: number + format: double + close: + type: number + format: double + volume: + type: number + format: double + Error: type: object required: