Quickstart
npx skills add chartai-official/agent-skills
# Owner completes registration, email verification, billing or renewal if needed,
# then creates or copies an agent key in Chartai Web.
open https://chartai.live/register?redirect=%2Fapp%2Fkeys%3Fintent%3Dcreate
export CHARTAI_AGENT_KEY="<agent-key>"
# Ask the agent to verify Chartai before scanning.
get_status {}
get_capabilities {}
scan_contexts {"symbol":"BINANCE:BTCUSDT","timeframe":"1h","limit":5}
inspect_chart_context {"context_id":"ctx_12345"}
get_context_ohlcv {"context_id":"ctx_12345"}Skill is the fastest agent path. MCP and CLI expose the same Chart Context actions.
Subscription only means plan and renewal. Agents use watchlists, monitors, and feed for ongoing work.
Agent Key
# No key path: discovery is public, protected actions return missing_agent_key.
get_status {}
# returns recovery.flow = manual_web_agent_key and agent_direct_payment = false
# CLI bootstrap opens the same manual Web key flow.
chartai connect --target cli --web-base https://chartai.live
export CHARTAI_AGENT_KEY="<agent-key>"
# MCP and Skill use the same local env name
export CHARTAI_AGENT_KEY="<agent-key>"Create the key in Chartai Web after registration, email verification, and any required billing or renewal step.
Do not paste raw keys into agent chat, screenshots, shared logs, or docs.
Skill
npx skills add chartai-official/agent-skills
# Natural-language agent use after the skill is installed:
get_status {}
get_capabilities {}
search_symbols {"query":"btc","asset":"crypto","limit":10}
search_symbols {"query":"trx","asset":"crypto","limit":10}
search_symbols {"asset":"stock","limit":100}
search_symbols {"asset":"forex","limit":100,"cursor":"OANDA:EUR_USD"}
search_symbols {"query":"eurcad","asset":"forex","limit":10}
resolve_symbol {"symbol":"BTC"}
resolve_symbol {"symbol":"AAPL"}
resolve_symbol {"symbol":"FX:EURUSD"}
set_timezone {"timezone":"Asia/Kuala_Lumpur"}
scan_contexts {"symbol":"BINANCE:BTCUSDT","timeframe":"1h","limit":5}
inspect_chart_context {"context_id":"ctx_12345"}
get_context_ohlcv {"context_id":"ctx_12345"}
check_context_condition {
"context_id":"ctx_12345",
"condition_id":"price_above_vwap",
"parameters":{"window_days":3}
}Skill tools are named without the chartai_ prefix because the skill namespace already identifies Chartai.
Symbol discovery normalizes aliases: BTC → BINANCE:BTCUSDT, AAPL/NASDAQ:AAPL → AAPL.US, FX:EURUSD → OANDA:EUR_USD.
Symbol search is paginated across crypto, US stocks, and forex/metals. Keep calling search_symbols with next_cursor until has_more=false before treating a catalog as exhausted.
No ready context? Chartai can queue a fresh scan. Wait, then retry the same symbol/timeframe.
A supplemental indicator check must reference an existing Chart Context. Standalone indicator lookup is not a Chartai action.
MCP
npx github:chartai-official/chartai-mcp config
{
"mcpServers": {
"chartai": {
"url": "https://mcp.chartai.live/mcp",
"headers": {
"Authorization": "Bearer ${CHARTAI_AGENT_KEY}"
}
}
}
}
# MCP tool names
chartai_get_status {}
chartai_get_capabilities {}
chartai_search_symbols {"query":"eth","asset":"crypto","limit":10}
chartai_search_symbols {"asset":"stock","limit":100}
chartai_search_symbols {"asset":"forex","limit":100,"cursor":"OANDA:EUR_USD"}
chartai_resolve_symbol {"symbol":"EURCAD"}
chartai_scan_contexts {"symbol":"BINANCE:ETHUSDT","timeframe":"15m","limit":5}
chartai_inspect_chart_context {"context_id":"ctx_12345"}
chartai_get_context_ohlcv {"context_id":"ctx_12345"}
chartai_check_context_condition {
"context_id":"ctx_12345",
"condition_id":"price_volume_state",
"parameters":{"lookback_bars":20}
}Use the generated JSON in MCP-ready hosts such as OpenClaw, Hermes, Claude Desktop, Cursor, Codex, Goose, or similar local agent runtimes.
Do not use --inline-key for shared config files.
Symbol discovery pages include returned_count, total_count, has_more, and next_cursor. A first page of 100 is not the full catalog when has_more=true.
CLI
npm install -g github:chartai-official/chartai-cli
chartai connect --target cli
export CHARTAI_AGENT_KEY="<agent-key>"
chartai get-status
chartai get-capabilities --json
chartai search-symbols --query BTC --asset crypto --limit 10 --json
chartai search-symbols --asset stock --limit 100 --json
chartai search-symbols --asset forex --limit 100 --cursor OANDA:EUR_USD --json
chartai resolve-symbol BTC
chartai resolve-symbol AAPL
chartai resolve-symbol FX:EURUSD
chartai get-timezone
chartai set-timezone Asia/Kuala_Lumpur
chartai scan-contexts --symbol BINANCE:BTCUSDT --timeframe 1h --limit 5 --json
chartai inspect-chart-context ctx_12345 --output chart.png --json
chartai get-context-ohlcv ctx_12345 --json
chartai get-record 12345 --json
chartai search-records --from 2026-05-01 --to 2026-05-05 --status active --limit 20 --json
chartai check-context-condition ctx_12345 --condition-id price_above_ma --parameters '{"ma_type":"ema","timeperiod":30}'
chartai create-watchlist BINANCE:BTCUSDT
chartai list-watchlist
chartai remove-watchlist BINANCE:BTCUSDT
chartai create-monitor --name "BTC bat 1h" --symbol BINANCE:BTCUSDT --pattern bat --timeframe 1h
chartai list-monitors
chartai pause-monitor mon_12345
chartai resume-monitor mon_12345
chartai delete-monitor mon_12345
chartai list-feed --limit 20 --unread-only
chartai list-feed --limit 20 --unread-only --cursor evt_12345
chartai ack-feed evt_12345
chartai get-usageCLI is for local runners, cron, CI, debugging, and onboarding bootstrap.
CLI exposes the same action contract with hyphenated command names.
Feed responses are paginated with has_more and next_cursor; keep calling list-feed with --cursor until has_more=false.
Actions
get_status auth state, plan, usage, timezone, manual key recovery get_capabilities markets, timeframes, patterns, indicators, actions search_symbols find supported symbols by query and asset class resolve_symbol normalize tickers into provider canonical symbols get_timezone read effective Chart Context timezone set_timezone set user timezone with an IANA name scan_contexts return current Chart Context summaries inspect_chart_context return native chart image first, then structured context get_context low-level structured Chart Context read get_context_manifest read Evidence Modules, Recipes, visual status, capabilities get_context_ohlcv read chart-window candles; window=wide returns wider data-only context get_chart chart download; variant=original returns persisted wider candles + Volume + pattern only confirm_chart_visual_inspection submit the visible VC code after actual image review get_record read one detection history/status record search_records audit/history search inside retention limits check_context_condition add/read supplemental indicator context create_watchlist add a symbol to the watchlist list_watchlist list watched symbols remove_watchlist remove a watched symbol create_monitor create durable Chart Context monitor list_monitors list monitors and state pause_monitor pause a monitor resume_monitor resume a monitor delete_monitor delete a monitor list_feed read monitor/feed events ack_feed mark feed events processed get_usage usage, limits, records retention, monitor limits
Skill, MCP, and CLI share the same action names and response contract.
Recipes
# Agent has no key yet
get_status {}
# Show recovery.web_url, wait for the owner to register, verify email, pay or renew
# if needed, create a key in Chartai Web, then retry get_status with CHARTAI_AGENT_KEY.
# Find what the owner can ask Chartai for
get_capabilities {}
search_symbols {"query":"btc","asset":"crypto","limit":10}
search_symbols {"query":"aapl","asset":"stock","limit":10}
resolve_symbol {"symbol":"BTC"}
resolve_symbol {"symbol":"FX:EURUSD"}
# Get current tradable chart context
scan_contexts {"symbol":"BINANCE:BTCUSDT","timeframe":"1h","limit":5}
inspect_chart_context {"context_id":"ctx_12345"}
get_context_ohlcv {"context_id":"ctx_12345"}
get_chart {"context_id":"ctx_12345","variant":"original"}
# Add supplemental facts to the same Chart Context
check_context_condition {
"context_id":"ctx_12345",
"condition_id":"price_above_vwap",
"parameters":{"window_days":3}
}
check_context_condition {
"context_id":"ctx_12345",
"condition_id":"price_volume_state",
"parameters":{"lookback_bars":20}
}
# Watch future opportunities and process feed events
create_monitor {"symbol_filters":["BINANCE:BTCUSDT"],"pattern_filters":["bat","butterfly"],"timeframe_filters":["1h"]}
list_feed {"limit":20,"unread_only":true}
list_feed {"limit":20,"unread_only":true,"cursor":"evt_12345"}
ack_feed {"event_ids":["evt_12345"]}
# Audit usage before asking for more new Chart Context
get_usage {}Normal flow: recover key, discover capabilities, resolve symbol, scan, inspect, then decide outside Chartai.
Discovery catalog means Chartai can normalize the symbol. scan_contexts only returns ready Chart Contexts. No ready context? Wait, then retry the same symbol/timeframe.
context_id is the Chartai evidence ID. Agents reuse it and never invent it.
Supplemental facts attach to context_id. If there is no Chart Context yet, scan first.
Use detection_id for historical records. Use monitors and paginated feed for ongoing watches.
Chart Context
{
"schema_version": "chart_context_standard_2026_05",
"context_id": "ctx_12345",
"detection_id": 12345,
"effective_timezone": "Asia/Kuala_Lumpur",
"symbol": {
"canonical": "BINANCE:BTCUSDT",
"asset_class": "crypto"
},
"timeframe": "1h",
"ai_pattern": {
"id": "double_bottom",
"name": "Double Bottom",
"direction": "bullish",
"status": "active"
},
"chart": {
"url": "https://...",
"width": 1920,
"height": 1080,
"render_version": "chart_context_render_2026_05"
},
"lifecycle": {
"status": "active",
"last_updated_at": "2026-05-05T11:40:00+08:00",
"freshness_seconds": 90
},
"levels": {
"entry": 63880.2,
"stop": 62840.0,
"targets": [65220.0, 66880.0],
"rrratio": 2.45
},
"indicator_facts": [
{"id":"ema_30","relation":"price_above_indicator"},
{"id":"vwap_calendar_3d","relation":"price_above_indicator"},
{"id":"price_volume_state","value":"rising_on_low_volume"}
],
"supplemental_context": [
{
"question":"price_above_vwap",
"status":"available",
"charged":false
}
],
"ohlcv_window": {
"endpoint": "/api/v1/contexts/ctx_12345/ohlcv",
"purpose": "audit the candles behind this chart"
},
"usage": {
"chart_context_consumed": true,
"repeat_context": false
}
}Chart Context is the product object: pattern, chart, lifecycle, levels, default indicator facts, supplemental context, and timezone in one response.
When an agent needs to audit the candles behind the selected chart, request the OHLCV for that context_id. It is not a general price feed.
When an agent wants a clean chart for freeform review, request get_chart with variant=original; it stores one wider-context image after first generation and reuses it.
Chartai returns evidence only. Your agent, rulebook, and exchange skill decide the next step outside Chartai.
Indicators
# Supplemental indicator checks require an existing context_id.
chartai get-context-ohlcv ctx_12345
chartai check-context-condition ctx_12345 --condition-id price_above_vwap --parameters '{"window_days":3}'
chartai check-context-condition ctx_12345 --condition-id price_above_ma --parameters '{"ma_type":"ema","timeperiod":30}'
chartai check-context-condition ctx_12345 --condition-id rsi_state --parameters '{"window":14}'
chartai check-context-condition ctx_12345 --condition-id macd_cross --parameters '{"fast":12,"slow":26,"signal":9}'
chartai check-context-condition ctx_12345 --condition-id price_volume_state --parameters '{"lookback_bars":20}'
chartai check-context-condition ctx_12345 --condition-id candle_confirmation --parameters '{"lookback_bars":5}'
# Main condition families
VWAP / SMA / EMA / WMA / DEMA / TEMA / KAMA
RSI / MACD / ROC / CCI / Stoch / Stoch RSI
ATR / NATR / Bollinger Bands
ADX / DI / SAR
OBV / MFI / AD / ADOSC / CMF / VPT / PVO / volume average
price_volume_state / candle_confirmationDefault indicator facts return with Chart Context when available.
Context OHLCV returns the chart-window candles for one existing context. Use it to audit the selected chart, not to ask for arbitrary market data.
Supplemental checks do not consume another Chart Context quota and are appended to the same chart information.
Invalid parameters, oversized windows, unavailable chart information, and unsupported conditions return structured failures instead of 500s.
Patterns
head_shoulders_top Head & Shoulders Top head_shoulders_bottom Head & Shoulders Bottom (Inv.) double_top Double Top double_bottom Double Bottom triple_top Triple Top triple_bottom Triple Bottom ascending_triangle Ascending Triangle descending_triangle Descending Triangle symmetrical_triangle Symmetrical Triangle rising_wedge Rising Wedge falling_wedge Falling Wedge cup_and_handle Cup and Handle gartley Gartley bat Bat butterfly Butterfly crab Crab deep_crab Deep Crab shark Shark cypher Cypher
All ids above are supported by the current runtime.
Monitors Feed
chartai create-monitor --name "BTC harmonic 1h" --symbol BINANCE:BTCUSDT --pattern bat --pattern butterfly --timeframe 1h chartai create-monitor --name "Tesla bearish daily" --symbol TSLA.US --pattern head_shoulders_top --timeframe 1D chartai list-monitors chartai pause-monitor mon_12345 chartai resume-monitor mon_12345 chartai list-feed --limit 20 --unread-only chartai list-feed --limit 20 --unread-only --cursor evt_12345 chartai ack-feed evt_12345 chartai delete-monitor mon_12345
A monitor records the boundary of what the owner wants Chartai to watch.
Feed events are deduplicated, paginated, and read/ack state is agent-facing. Feed reads do not consume Chart Context quota.
Usage
{
"chart_contexts": {
"used": 12,
"limit": 50,
"remaining": 38,
"reset_at": "2026-05-06T00:00:00+08:00"
},
"supplemental_context": {
"policy": "included_fair_use",
"charged": false
},
"records": {
"retention_days": 30
},
"monitors": {
"used": 3,
"limit": 10
}
}Usage is charged by new Chart Context returned to the account, not by Skill, MCP, or CLI entrypoint.
Repeating the same visible context, reading a chart, feed ack, and supplemental checks do not consume another Chart Context quota.
Reading context-bound OHLCV, window=wide OHLCV, and original chart images are follow-up reads on an existing Chart Context.
Use context_id for current decision evidence and detection_id for historical records.
Errors
{
"code": "missing_agent_key",
"detail": "Chartai agent key is required.",
"meta": {},
"guidance": {
"do_not_guess": true,
"next_actions": [
{"action": "get_status"},
{"action": "owner_action_in_chartai_web", "input": {"env": "CHARTAI_AGENT_KEY"}}
]
},
"recovery": {
"flow": "manual_web_agent_key",
"action": "owner_create_agent_key",
"web_url": "https://chartai.live/register?redirect=%2Fapp%2Fkeys%3Fintent%3Dcreate",
"agent_direct_payment": false,
"automatic_connect": false,
"env": "CHARTAI_AGENT_KEY"
}
}
{
"code": "chart_context_quota_exceeded",
"detail": "New Chart Context quota is exhausted.",
"meta": {},
"guidance": {
"do_not_guess": true,
"next_actions": [
{"action": "get_status"},
{"action": "get_usage"}
]
},
"recovery": {
"flow": "manual_web_agent_key",
"action": "owner_upgrade_or_wait_reset",
"web_url": "https://chartai.live/app/billing",
"agent_direct_payment": false
}
}
{
"status": "unavailable",
"error": "window_too_large_for_timeframe",
"required_bars": 14405,
"max_bars": 2000,
"charged": false
}
{
"status": "unavailable",
"error": "invalid_indicator_parameters",
"charged": false
}Errors stay structured so agent workflows can branch deterministically.
Agent-facing errors include guidance.next_actions; follow them before changing symbols, timeframes, ids, or action names.
Errors stay user-safe and actionable.
Security
Chartai never: - places trades - asks for exchange keys - handles wallets or balances - collects owner passwords inside agent chat - prints raw long-lived agent keys - returns buy/sell instructions Chartai always: - returns chart judgment material - keeps execution outside Chartai - uses the owner effective timezone - keeps Skill, MCP, and CLI on the same actions
Use exchange skills, broker tools, or human review for execution outside Chartai.
Chartai is chart context for trading agents, not an exchange execution layer.
Changelog
2026-05-15 original context chart and window=wide OHLCV added for agent freeform review
2026-05-14 context-bound OHLCV added for selected Chart Context audit
2026-05-05 Skill / MCP / CLI live command matrix verified
2026-05-04 Chart Context Standard accepted
2026-05-04 supplemental indicator contract:
VWAP, MA, momentum, volatility, trend, volume, candle confirmation
2026-04-29 19 pattern ids canonicalizedCheck runtime changes before updating an agent workflow.
Pricing details live on the homepage pricing section.