Decker

Official8 toolsLive

by gigshow · Python

Deterministic market-state engine for trading agents — state, gate, coordinates, with receipts.

Topics

aicryptotelegram-bottradingtrading-botdeckerharnessopenclawbinancedeckeraihyperliquidpolymarket-trade-bot

Captured live from the server via tools/list.

decker.get_signals

Active trading signals for the current user (with Skill Overlay applied), in customer-facing shape: coordinates (entry/target/stop), decision (ENTER/WAIT/SKIP), action_gate posture (GO/WATCH/HOLD — a stance, not an order command), progress, MTF verdict, and a plain-language summary_ko line. risk_reward_ratio is computed on the DISPLAYED coordinates (after overlay). Signals are retained rather than cut when they age (turn-retention policy) — read freshness_state (open|aged) / age_bars / freshness_sec before treating an old PENDING row as current. Filtered by symbols / min_progress / action_gate. Before placing any order through any execution tool, check the intent with decker.validate_intent.

Parameters5

symbols	array	optional	Symbol filter (e.g. ['BTCUSDT','ETHUSDT']). Omit for all.
min_progress	number	optional	Minimum progress_pct (0-100).
action_gate	string	optional	Engine action gate filter (3-layer grammar: gate = transition posture, not an order command). Rows where the engine emitted no gate for this bar (effective_action_gate null, e.g. KRX daily) are excluded when this filter is set.
timeframe	string	optional	Signal horizon filter (30m=scalp, 1h=swing, 4h/8h/1d=position). The same symbol can hold OPPOSITE directions on different horizons — omit to get the latest active signal regardless of horizon (its timeframe field says which one you got).
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "symbols": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Symbol filter (e.g. ['BTCUSDT','ETHUSDT']). Omit for all."
    },
    "min_progress": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Minimum progress_pct (0-100)."
    },
    "action_gate": {
      "type": "string",
      "enum": [
        "GO",
        "WATCH",
        "HOLD"
      ],
      "description": "Engine action gate filter (3-layer grammar: gate = transition posture, not an order command). Rows where the engine emitted no gate for this bar (effective_action_gate null, e.g. KRX daily) are excluded when this filter is set."
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "30m",
        "1h",
        "4h",
        "8h",
        "1d"
      ],
      "description": "Signal horizon filter (30m=scalp, 1h=swing, 4h/8h/1d=position). The same symbol can hold OPPOSITE directions on different horizons — omit to get the latest active signal regardless of horizon (its timeframe field says which one you got)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  }
}

decker.get_reading

AI-synthesized market reading for a symbol/timeframe, in customer-facing language: current state description, directional bias scores, bidirectional break targets, MTF verdict per timeframe, and an execution hint (stance + long/short setups). Engine-native raw fields are NOT exposed here — use the REST raw contract (GET /public/reading) or decker.get_market_state for those.

Parameters3

symbol	string	required	e.g. BTCUSDT
tf	string	optional
include_tfs	string	optional	Comma-separated additional TFs (e.g. '1h,4h,1d').

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "e.g. BTCUSDT"
    },
    "tf": {
      "type": "string",
      "enum": [
        "15m",
        "30m",
        "1h",
        "4h",
        "8h",
        "1d",
        "1w"
      ],
      "default": "4h"
    },
    "include_tfs": {
      "type": "string",
      "description": "Comma-separated additional TFs (e.g. '1h,4h,1d')."
    }
  },
  "required": [
    "symbol"
  ]
}

decker.get_view

The engine's VIEW for a symbol — the same composed card the daily briefing sends (single composer, verbatim): overall verdict, big/main timeframe alignment, the current game narrative in plain language, coordinates (baseline ref_price / target / invalidation), 'at this price, this view', and recent self-scoring verdicts (receipts). layer=STATE_VIEW: a market-state reading, NOT a trade instruction. Prefer this over get_market_state when you want the interpreted view instead of raw engine fields. Before placing any order through any execution tool, check the intent with decker.validate_intent.

Parameters2

symbol	string	required	e.g. BTCUSDT, XYZ_GOLDUSD (crypto + HL TradFi synthetics; KRX daily lineage not yet covered by view v1)
tf	string	optional	Optional view timeframe — the grounded narrative is composed on this TF's bar (e.g. '1h' when the user asks about the 1-hour picture). Omit for the engine's default action TF (usually 4h, same as the daily briefing card).

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "e.g. BTCUSDT, XYZ_GOLDUSD (crypto + HL TradFi synthetics; KRX daily lineage not yet covered by view v1)"
    },
    "tf": {
      "type": "string",
      "enum": [
        "30m",
        "1h",
        "4h",
        "8h",
        "1d"
      ],
      "description": "Optional view timeframe — the grounded narrative is composed on this TF's bar (e.g. '1h' when the user asks about the 1-hour picture). Omit for the engine's default action TF (usually 4h, same as the daily briefing card)."
    }
  },
  "required": [
    "symbol"
  ]
}

decker.get_market_state

Market State v0 — current engine structural state for a symbol/timeframe (latest evaluated bar, persisted engine emit read as-is, zero recompute). DOMAIN FRAME (why this engine exists): the market is read as a TARGET GAME — every coordinate comes from a *verified anchor* (a past level where a triggered move actually succeeded). The `game` block tells you the context that matters: game.status = forming_target (new anchor set, awaiting test) | testing_target (price is testing whether the declared target holds) | direction_resolved (game decided, price traveling); game.target = WHO is being judged (anchor id/phase/band); game.progress_dest = where price goes if the move proceeds (the opposing verified anchor to conquer); game.reverse_dest = where it goes if the move fails (the opposite house — also the stop logic's home); game.why_gate = full gate derivation chain; game.zt_regime = output canonicality (restored = deterministic delta lineage). action_gate alone (GO/WATCH/HOLD) is only a posture — the game context is the information. RAW CONTRACT: fields are engine-native vocabulary (c_state, hold_reason, R_* risk enums …), NOT customer-facing prose — for a human-language view use decker.get_view (with tf) or decker.get_reading. layer=STATE: this is a market-state reading, NOT a trade instruction. Absent fields are null (engine did not emit that axis — no filling). Before placing any order through any execution tool, check the intent with decker.validate_intent.

Parameters2

symbol	string	required	e.g. BTCUSDT
timeframe	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "e.g. BTCUSDT"
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "30m",
        "1h",
        "4h",
        "8h",
        "1d"
      ]
    }
  },
  "required": [
    "symbol",
    "timeframe"
  ]
}

decker.get_state_timeline

Market State v0 — per-bar state timeline for a symbol/timeframe (same schema as decker.get_market_state, except each item carries a SLIM `game` tag {status, target_id, zt_regime, provenance} instead of the full game block — read status transitions across bars to see how the target game unfolded (forming → testing → resolved/failed); ascending by bar_ts). Bars the engine did not emit are simply absent (honest gaps, no filling).

Parameters4

symbol	string	required	e.g. BTCUSDT
timeframe	string	required
since	string	optional	ISO8601 lower bound on bar_ts (exclusive). Optional.
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "e.g. BTCUSDT"
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "30m",
        "1h",
        "4h",
        "8h",
        "1d"
      ]
    },
    "since": {
      "type": "string",
      "description": "ISO8601 lower bound on bar_ts (exclusive). Optional."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "default": 100
    }
  },
  "required": [
    "symbol",
    "timeframe"
  ]
}

decker.get_user_skills

Trading skill catalog + currently active overlay for this user. Returns 3 base skills (conservative_v0/standard_v0/aggressive_v0) and the user's selected one.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

decker.set_skill_overlay

Change active trading skill overlay for this user. Immediately affects all subsequent get_signals calls and downstream channels.

Parameters1

skill_id

string

required

trading_skills.id (e.g. 'aggressive_v0').

Raw schema

{
  "type": "object",
  "properties": {
    "skill_id": {
      "type": "string",
      "description": "trading_skills.id (e.g. 'aggressive_v0')."
    }
  },
  "required": [
    "skill_id"
  ]
}

decker.validate_intent

Pre-trade gate check for a proposed order intent. Call this BEFORE placing any order through any execution tool (e.g. a broker MCP's review→place flow). Checks the intent (symbol + side) against Decker's deterministic market state: engine action_gate (GO/WATCH/HOLD — a transition posture, not an order command), current structural state, and the active signal's direction / invalidation (stop) coordinates. Returns a stance reading, NOT an approval or rejection: the vocabulary is the engine gate as-is plus a mechanical side_alignment (aligned/opposed vs the active signal's direction). covered=false means the engine does not emit state for this symbol — treat as unknown, not as HOLD. The order decision and responsibility remain with the calling agent/user. Every check is persisted to an auditable decision ledger (check_id).

Parameters4

symbol	string	required	e.g. BTCUSDT, SILVER, 테슬라 — aliases resolve to the engine symbol (XYZ_SILVERUSD, XYZ_TSLAUSD, …).
side	string	required	Proposed order direction (buy/long = +, sell/short = -).
order_type	string	optional	Optional, informational (market/limit/…) — recorded in the ledger, does not change the state verdict.
timeframe	string	optional	Gate horizon. Omit = the active signal's timeframe if one exists, else the engine's default action TF (4h).

Raw schema

{
  "type": "object",
  "properties": {
    "symbol": {
      "type": "string",
      "description": "e.g. BTCUSDT, SILVER, 테슬라 — aliases resolve to the engine symbol (XYZ_SILVERUSD, XYZ_TSLAUSD, …)."
    },
    "side": {
      "type": "string",
      "enum": [
        "buy",
        "long",
        "sell",
        "short"
      ],
      "description": "Proposed order direction (buy/long = +, sell/short = -)."
    },
    "order_type": {
      "type": "string",
      "description": "Optional, informational (market/limit/…) — recorded in the ledger, does not change the state verdict."
    },
    "timeframe": {
      "type": "string",
      "enum": [
        "30m",
        "1h",
        "4h",
        "8h",
        "1d"
      ],
      "description": "Gate horizon. Omit = the active signal's timeframe if one exists, else the engine's default action TF (4h)."
    }
  },
  "required": [
    "symbol",
    "side"
  ]
}

README.md14 KBView on GitHub

DeckerClaw Decker AI

The deterministic market-state layer your trading agents call.

Rules trade, LLMs explain. Live, non-custodial, with receipts.

Open the app · Telegram bot · Kakao channel · API docs

Decker AI — the live market-state cockpit across crypto and Korean equities (KOSPI 200)

What you get

Signals you can act on, with context. Not "BUY" — GO / WATCH / HOLD + progress_pct (0–100% lifecycle) + entry / stop / target.
It explains itself. Every signal has a structural cause (multi-timeframe alignment, state machine phase) that an LLM translates into plain language.
Same engine, two markets. Crypto (24/7) + Korean equities (KOSPI + KOSDAQ, Beta).
Use it your way. Web app, Telegram, Kakao channel, REST API, or MCP server inside Claude / Cursor.

"Where are we in the current structural cycle — and what's the next optimal move?"

Get started in 60 seconds

Path	Best for	Start
📱 Web app	Most people — full dashboard, mock trading, KRX watchlist	decker-ai.com — sign up free
🤖 Telegram bot	Quick signal checks on your phone	@deckerclawbot — `/start`
💛 Kakao channel	한국 사용자, KRX 시그널 알림	pf.kakao.com/_RxlxjVX
🧠 MCP server	Claude / Cursor / Codex users	decker-ai.com/mcp — 2-min setup
🛠 REST API	Developers building bots & apps	DEVELOPER_README.md

Free tier is generous (30 calls/day on the API; Web + Telegram included). During Beta, signed-up users get PRO access for free.

See it in action

Start here — 30 seconds. No signup, no key.

bash

curl -s https://api.decker-ai.com/api/v1/public/demo | jq .

MCP demo — curl the public demo, then an agent calls the deterministic get_view tool

▶️ Play — MCP demo (48s) · Then one MCP line gives any agent the same read — zero LLM in the signal path.

The engine room — live FSM, MTF alignment, R:R

The live cockpit — full universe grid with per-symbol state and AI reading

▶️ Play — the live cockpit (16s) · Every signal traces to a structural cause: progress_pct + operation_gate + entry / stop / target.

Signal → execution, non-custodial

Hyperliquid — state, signal-engine coordinates, and a non-custodial order

▶️ Play — non-custodial execution (16s) · Click Order · wallet-sign · custody 0. Decker relays your signature only (revocable agent wallet, EIP-712). For information only — not investment advice.

Read it daily — and we score our own calls

The web briefing hub — per-symbol view with baseline, target, and invalidation The daily briefing on Telegram — picks and subscribe

▶️ Play: web hub (10s) · Telegram (6s)

Every morning (08:00 KST): the engine's view per symbol — baseline, what winning and losing look like, and a pick you can answer. Evening: the same view scored against what actually happened — hits and misses alike, on the record. We stamp our wrong calls too.

Web hub: decker-ai.com/briefing · Subscribe: @deckerclawbot → /briefing

Korean equities (KRX) — Beta, free

Korean equities — today's hot market and portfolio actions on KOSPI

▶️ Play — KRX (16s) · Same deterministic engine on KOSPI + KOSDAQ. Portfolio states — ADD / HOLD / REDUCE / EXIT, not buy/sell. Daily closing-bell checkup at 16:30 KST · @krxdeckerbot.

Three things that make it different

1. progress_pct — every signal has a lifecycle. A signal at 25% progress is a different trade than the same signal at 80%. Most tools just say "BUY"; Decker tells you where in the move you are.

code

Entry                                                           Target
  0%──────────33%──────────50%──────────67%──────────83%────────100%
 Wait       Entry        Active       Late TP      Final TP     Exit

2. GO / WATCH / HOLD — three gates, not binary.

Gate	Meaning
GO	Structure confirmed — entry conditions met
WATCH	Signal forming — monitor, no entry yet
HOLD	Active position — no new entry signal

WATCH is the gate most tools skip. It's why users enter too early.

3. Deterministic + traceable. LLM explains, doesn't decide.

	Typical AI signal	Decker
Source	ML / LLM price prediction	Deterministic state machine
Output	BUY / SELL	`progress_pct` + `operation_gate` + ranked choices
LLM role	Makes the call	Explains the structural state
Auditability	❌ Black box	✅ Every signal has a `trace_id`
Cost per signal	High	$0 on the rules path
Reproducibility	❌	✅ Same input → same output, always

Pricing

Tier	Price	Daily API limit	MCP	Auto-trade
FREE	$0 forever	30 calls/day	read-only (1d cache)	❌
PRO	$20 / mo · 7-day trial	10,000 / day	full (7 tools)	virtual + real
ENTERPRISE	Contact us	100,000+ / day · custom	full + per-org skill catalog	+ custom integration

Beta (now): all authenticated users get PRO for free via BETA_TIER_OVERRIDE=PRO. No payment required.

Web sign-up and Telegram bot are always free for the basics.

For developers

Building a bot, app, or agent on top of Decker? Everything you need — REST endpoints, MCP server (Claude / Cursor / Codex), Python SDK, OpenClaw skill, self-host — lives in one place:

→ DEVELOPER_README.md

bash

# 60-second smoke test (no auth needed)
curl https://api.decker-ai.com/api/v1/public/demo

bash

# With an API key (decker-ai.com → Settings → API Keys, or Telegram /apikey)
curl "https://api.decker-ai.com/api/v1/public/signals/BTCUSDT/latest?timeframe=1h" \
  -H "X-API-Key: dk_live_xxx"

Prefer a runnable file? → examples/quickstart.py — zero dependencies (stdlib only), no key, prints the composed view + receipts in one run. Wrapping Decker for an agent crew: examples/langgraph_decker_tool.py. More in examples/.

The demo returns the composed view — the same card our daily briefing sends:

json

{ "layer": "STATE_VIEW", "symbol": "BTCUSDT", "ref_price": 63650.0,
  "lines": ["■ BTC — 층간 힘겨루기: 주 판 아래쪽 · 지금 판 위쪽", "…"],
  "wait_target": "...", "invalidation": "...",
  "verdict_recent": [{"briefing_date": "2026-07-05", "slot": "morning", "verdict": "hit"}],
  "provenance": { "composer": "briefing_story.compose_card" } }

Add to Claude Desktop / Cursor (MCP): guided 2-minute setup with per-client config → decker-ai.com/mcp.

Cursor (~/.cursor/mcp.json) takes a remote server directly:

json

{
  "mcpServers": {
    "decker": {
      "url": "https://api.decker-ai.com/api/v1/mcp/sse",
      "headers": { "X-API-Key": "dk_live_YOUR_KEY" }
    }
  }
}

Claude Desktop / Codex reach it through the mcp-remote bridge (needs Node/npx) — see decker-ai.com/mcp or DEVELOPER_README.md (endpoints · auth · rate limits · MCP 7 tools · SDK · OpenClaw · self-host).

Running a multi-agent crew (TradingAgents / LangGraph / AutoGen)? Give your analysts one deterministic market-state instrument — with receipts — instead of re-deriving structure per prompt: → docs/integrations/multi-agent-frameworks.md

How the engine works (one diagram)

code

Raw OHLCV candles
  ↓  Sequence Labeler  →  every candle gets a role (anchor / test / signal)
  ↓  State Machine     →  C_SET → B_FORMING → B_SET → A_FORMING → W_PENDING
  ↓  Operation Gate    →  GO · WATCH · HOLD
  ↓  RULES Engine      →  9-layer YAML rulebook → strategy + ranked choices
  ↓  AI Consultation   →  LLM translates structural state → plain language
  ↓
"67% progress. B-leg confirmed. Recommended: 30% partial TP or hold to target."

No price prediction. No black box. Every output traces to a formal structural cause.

Deep dives: Sequence Engine · Labeling Algorithm · Market State Theory

Supported symbols

Crypto (GA): BTCUSDT · ETHUSDT · SOLUSDT · BNBUSDT · XRPUSDT · DOGEUSDT — timeframes 30m, 1h, 4h, 1d.

KRX (Beta, free): KOSPI 948 + KOSDAQ 1,822 = 2,770 tickers. Universe = top 200 by trading value ∪ user watchlist ∪ momentum spike ∪ volume spike. Timeframe 1d only (1w expanding). Daily evaluation at 16:30 KST.

KRX details: docs/krx/KRX_BUSINESS_MODEL_AND_ROADMAP_2026-05-09.md.

Performance

We don't publish a headline win rate. Backtest numbers without method and sample size are marketing, not evidence — and easy to cherry-pick.

What we stand on instead:

Deterministic & reproducible. Same input → same output, always. The rules path has zero LLM in it, so a signal is not a model's opinion — it's a formal structural verdict you can re-derive.
Auditable. Every read carries its provenance (composer + the versioned rulebook contract) and traces back to the exact engine emit. The full RULES.yaml is open, so you can re-derive any verdict yourself.
Scored in public, daily. The morning briefing's view is graded against what actually happened that evening — hits and misses alike, on the record. → decker-ai.com/briefing · a GitHub Action stamps the daily scorecard straight into this repo: TRACK_RECORD.md

Method and rulebook are open: Model & Algorithm · Operation Rules (YAML) · Signal Performance.

For information only. Not investment advice.

Docs


DEVELOPER_README.md	API · MCP · SDK · OpenClaw · self-host — start here if you're building
Developer API Guide	Auth · rate limits · FAQ (long form)
Architecture	Pipeline, state engine, modules
Model & Algorithm	How the signal engine works
Operation Rules	Open YAML rulebook (v2.4.7+)
Article Series (1–15)	Deep dives on Medium
Roadmap	What's next
llms.txt	LLM / AI agent discovery manifest

Links


Web app	https://decker-ai.com
API docs	https://api.decker-ai.com/docs
Telegram bot (crypto)	https://t.me/deckerclawbot
Telegram bot (KRX)	https://t.me/krxdeckerbot
Kakao channel	https://pf.kakao.com/_RxlxjVX
X / Twitter	https://x.com/blockoceandev

This repository is the public hub for Decker AI — SDK, samples, rulebook, architecture docs, OpenClaw skill packages. Production application code runs in a private monorepo. All listed endpoints, channels, and the web app are live.

Built by gigshow (Dohyung Kim · 김도형) — founder. Open to investor / partnership conversations.

Install

Tools (8)

decker.get_signalsdecker.get_readingdecker.get_viewdecker.get_market_statedecker.get_state_timelinedecker.get_user_skillsdecker.set_skill_overlaydecker.validate_intent

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.decker-ai.com/api/v1/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "decker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.decker-ai.com/api/v1/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.