> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Perp Chart Image
> Render a candlestick chart image for a perpetual market from OHLC candles plus header/footer metadata and optional overlay lines (stop-loss, take-profit, liquidation). The candle shape is identical to the /2/perp/ohlcv-history response, so its output can be passed straight in.
### Query Details
Send OHLC candles together with the header and footer blocks shown around the chart, and the rendered chart is returned in `data`. This is a synchronous proxy: one request in, one rendered chart out — nothing is stored.
* Candles use the same `t / o / h / l / c` shape as `GET /2/perp/ohlcv-history` — feed that endpoint's output directly.
* `t` is UNIX **milliseconds**.
* `priceChange` is a percentage (e.g. `-6.31` means `-6.31%`), not a ratio.
* Send candles ordered oldest → newest.
* All top-level fields except `lines` are required. Within `lines`, each of `stopLoss` / `takeProfit` / `liquidation` is independently optional — send only the levels you have.
### Request Body
| Field | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------- |
| candles | array | Yes | OHLC series (`{t, o, h, l, c}`), oldest-to-newest. Min 1 candle. |
| width | integer | Yes | Output image width in pixels. Positive integer. |
| height | integer | Yes | Output image height in pixels. Positive integer. |
| name | string | Yes | Chart title / pair label shown on the chart (e.g. `FLUID/USD`). |
| lines | object | No | Overlay lines: `stopLoss`, `takeProfit`, `liquidation` (all optional). |
| headerData | object | Yes | Header block (see below). |
| footerData | object | Yes | Footer block (see below). |
`headerData`:
| Field | Type | Description |
| ------------- | ------ | --------------------------------------------------------------- |
| pair | string | Trading pair label (e.g. `FLUID/USD`). |
| leverage | number | Position leverage multiplier. |
| currentPrice | number | Current mark/last price. |
| priceChange | number | Price change for the window, as a percentage (may be negative). |
| openInterestL | object | Long-side open interest: `{ value, total }`. |
| openInterestS | object | Short-side open interest: `{ value, total }`. |
| holdingL | number | Long holding amount. |
| holdingS | number | Short holding amount. |
`footerData`:
| Field | Type | Description |
| --------- | ------ | ---------------------- |
| high24h | number | 24-hour high price. |
| low24h | number | 24-hour low price. |
| volume24h | number | 24-hour traded volume. |
### Response
| Field | Type | Description |
| ----- | ------ | ------------------------------------------------------------------------------- |
| data | string | The rendered chart, passed through verbatim. Treat as an opaque string payload. |
Example of the rendered chart returned for the request below:
### Usage Example
```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/perp/chart" \
-H "Content-Type: application/json" \
-d '{
"candles": [
{ "t": 1780860000000, "o": 1.0615964, "h": 1.0656162, "l": 1.0506006, "c": 1.0605862 },
{ "t": 1780861800000, "o": 1.0605862, "h": 1.0655736, "l": 1.0525683, "c": 1.0630746 }
],
"width": 1024,
"height": 850,
"name": "FLUID/USD",
"lines": { "stopLoss": 1.28768, "takeProfit": 0.73582, "liquidation": 1.42315 },
"headerData": {
"pair": "FLUID/USD",
"leverage": 3,
"currentPrice": 1.103729,
"priceChange": -6.305772495755514,
"openInterestL": { "value": 0, "total": 250000 },
"openInterestS": { "value": 30.000026, "total": 249969.999974 },
"holdingL": 0.00251711712,
"holdingS": 0.00251711712
},
"footerData": { "high24h": 1.2151002, "low24h": 1.0799406, "volume24h": 2001.2866550754236 }
}'
```
### Errors
| Status | When | `message` |
| ------ | -------------------------------------------------------------------------- | -------------------------------- |
| 400 | Body failed validation (missing/invalid fields, empty candles, wrong keys) | `zod validation failed` |
| 502 | Upstream chart generator failed or was unreachable | `upstream chart generator error` |
| 500 | Unexpected internal error | `failed to generate chart` |
## OpenAPI
````yaml POST /2/perp/chart
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Usage
description: Per-key API and WebSocket usage history
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V2 - Prediction Markets
description: >-
Polymarket markets/events, wallet positions, and the full execution stack
(auth, order build/submit/cancel, approvals, pUSD wrap/unwrap, deploy,
deposit/withdraw, redeem). Alpha — see /api/2/pm/*.
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/perp/chart:
post:
tags:
- V2 - Perps
summary: Generate perp chart image
description: >-
Render a candlestick chart image for a perpetual market. Send OHLC
candles (same t/o/h/l/c shape as /2/perp/ohlcv-history) plus
header/footer metadata and optional overlay lines; the rendered chart is
returned in `data`. Synchronous — one request in, one rendered chart
out.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- candles
- width
- height
- name
- headerData
- footerData
properties:
candles:
type: array
description: >-
OHLC series, oldest-to-newest by `t`. Same shape as the
/2/perp/ohlcv-history response, so its output can be passed
in directly. Must contain at least one candle.
minItems: 1
items:
type: object
required:
- t
- o
- h
- l
- c
properties:
t:
type: number
description: Candle open time, UNIX epoch in milliseconds.
o:
type: number
description: Opening price.
h:
type: number
description: Highest price in the interval.
l:
type: number
description: Lowest price in the interval.
c:
type: number
description: Closing price.
width:
type: integer
description: Output image width in pixels. Positive integer.
height:
type: integer
description: Output image height in pixels. Positive integer.
name:
type: string
description: >-
Chart title / pair label shown on the chart (e.g.
FLUID/USD).
lines:
type: object
description: >-
Optional horizontal overlay lines. Each level is
independently optional — send only the ones you have.
properties:
stopLoss:
type: number
description: Stop-loss price level.
takeProfit:
type: number
description: Take-profit price level.
liquidation:
type: number
description: Liquidation price level.
headerData:
type: object
description: Header block shown above the chart.
required:
- pair
- leverage
- currentPrice
- priceChange
- openInterestL
- openInterestS
- holdingL
- holdingS
properties:
pair:
type: string
description: Trading pair label (e.g. FLUID/USD).
leverage:
type: number
description: Position leverage multiplier.
currentPrice:
type: number
description: Current mark/last price.
priceChange:
type: number
description: >-
Price change for the displayed window, as a percentage
(may be negative).
openInterestL:
type: object
description: Long-side open interest.
required:
- value
- total
properties:
value:
type: number
description: Filled/used portion.
total:
type: number
description: Total capacity.
openInterestS:
type: object
description: Short-side open interest.
required:
- value
- total
properties:
value:
type: number
description: Filled/used portion.
total:
type: number
description: Total capacity.
holdingL:
type: number
description: Long holding amount.
holdingS:
type: number
description: Short holding amount.
footerData:
type: object
description: Footer block shown below the chart.
required:
- high24h
- low24h
- volume24h
properties:
high24h:
type: number
description: 24-hour high price.
low24h:
type: number
description: 24-hour low price.
volume24h:
type: number
description: 24-hour traded volume.
example:
candles:
- t: 1780860000000
o: 1.0615964
h: 1.0656162
l: 1.0506006
c: 1.0605862
- t: 1780861800000
o: 1.0605862
h: 1.0655736
l: 1.0525683
c: 1.0630746
- t: 1780863600000
o: 1.0630746
h: 1.0695774
l: 1.0630746
c: 1.0655949
width: 1024
height: 850
name: FLUID/USD
lines:
stopLoss: 1.2876838333333334
takeProfit: 0.7358193333333334
liquidation: 1.4231453021582852
headerData:
pair: FLUID/USD
leverage: 3
currentPrice: 1.103729
priceChange: -6.305772495755514
openInterestL:
value: 0
total: 250000
openInterestS:
value: 30.000026
total: 249969.999974
holdingL: 0.00251711712
holdingS: 0.00251711712
footerData:
high24h: 1.2151002
low24h: 1.0799406
volume24h: 2001.2866550754236
responses:
'200':
description: Rendered chart
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: string
description: >-
The rendered chart returned by the renderer, passed
through verbatim. Treat as an opaque string payload.
'400':
description: >-
Request body failed validation (missing/invalid fields, empty
candles, wrong candle keys).
'500':
description: Unexpected internal error.
'502':
description: Upstream chart generator failed or was unreachable.
````