Decker AI Strategy Builder

Crypto market state engine. Not "buy/sell" — structural context.

Signal → State → Strategy. Every output is traceable, reproducible, $0-LLM-cost on the rules path.

📖 API Docs · 🤖 Telegram Bot · 📦 Python SDK · 🗺 Roadmap

---

Start here

You are	Best path
Crypto trader — want signals on your phone	Telegram Bot → type /btc
Developer — building a bot, app, or script	3-step quickstart below
AI agent builder — adding Decker as a skill	OpenClaw skills
Self-host / deploy your own	turnkey/ — Railway one-click

---

⚡ Try it right now (no sign-up)

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

Returns live BTCUSDT 1h signal — no API key needed.

---

⚡ Quickstart (3 steps)

Step 1 — Get your API key (30 seconds)

1. Open Telegram → @deckerclawbot
2. Send /start
3. Send /apikey → receive dk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Lost your key? Run /apikey reset in the bot — revokes and reissues.

Step 2 — First call

curl "https://api.decker-ai.com/api/v1/public/signals/BTCUSDT/latest?timeframe=1h" \
  -H "X-API-Key: dk_live_xxx"

{
  "symbol": "BTCUSDT",
  "timeframe": "1h",
  "direction": "long",
  "entry_price": 94200.0,
  "target_price": 97500.0,
  "stop_loss": 92800.0,
  "progress_pct": 67.3,
  "operation_gate": "GO",
  "generated_at": "2026-04-23T05:00:00Z"
}

Step 3 — Python SDK (optional)

git clone https://github.com/gigshow/decker-ai-strategy-builder.git
pip install -e decker-ai-strategy-builder/sdk/python/

pip install decker-client (PyPI) — 배포 준비 중.

from decker_client import Client

with Client(api_key="dk_live_xxx") as client:
    sig = client.signals.get_latest("BTCUSDT", timeframe="1h")
    print(f"{sig.direction} | entry={sig.entry_price} | progress={sig.progress_pct}%")

    narr = client.signals.get_narrative("BTCUSDT", "4h")
    print(narr.text)

pip install decker-client (PyPI) is planned — not yet published. Use the local install above until then.
Full SDK docs: sdk/python/README.md

---

What is Decker?

Most signal tools ask: "Up or down?"
Decker asks: "Where are we in the current structural cycle — and what's the next optimal move?"

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  (not binary — three modes)
  ↓  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.

---

The progress_pct System

Every signal has a lifecycle — from formation (0%) to target (100%).

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

Example: progress_pct = 67%

[████████████████████████████████████████████░░░░░░░░░░░░░░░░░░░] 67%

Typical tool: BUY
Decker:       BUY + 67% progress
              → "The move is real, but 2/3 of the range is already done.
                 Consider partial entry or wait for a pullback."

progress_pct	Stage	Recommended posture
0–32%	Early	Wait or prepare entry
33–66%	Active	Entry window, manage risk
67–89%	Late	Partial take-profit, reduce size
90–100%	At target	Prepare full exit

---

GO · WATCH · HOLD

Unlike binary BUY/SELL signals, Decker has three operation gates:

Gate	Meaning	What to do
GO	Structure confirmed, entry conditions met	Enter (if within progress window)
WATCH	Signal forming, not yet confirmed	Monitor — no entry yet
HOLD	Active position, no new entry signal	Hold current position

WATCH ≠ SELL. It means "the engine is observing — not ready to signal an entry yet."
This is the gate that most signal tools skip. It's why users enter too early.

---

What Makes Decker Different

	Typical AI Signal	Decker
Signal 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
LLM cost per signal	High (every call)	$0 on the rules path
Reproducibility	❌	✅ Same input → same output, always

---

API Reference

Full OpenAPI spec at api.decker-ai.com/docs.

Supported symbols: BTCUSDT, ETHUSDT, SOLUSDT, BNBUSDT, XRPUSDT, DOGEUSDT
Supported timeframes: 30m, 1h, 4h, 1d

Symbols or timeframes outside this list return 404. More symbols expanding.

Public endpoints (require X-API-Key header)

Method	Path	Description
POST	/api/v1/public/auth/verify	Verify API key + get tier
GET	/api/v1/public/health	Liveness check (no auth)
GET	/api/v1/public/signals/{symbol}/latest	Latest signal (direction, entry, target, stop, progress)
GET	/api/v1/public/signals/{symbol}/narrative	LLM structural narrative

Auth

X-API-Key: dk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are issued via Telegram /apikey — not from the web UI. See DEVELOPER_API_GUIDE.md.

Rate Limits

Tier	Daily limit
FREE	100 req/day
BASIC	10,000 req/day
PREMIUM	100,000 req/day

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Exceeded → HTTP 429 + Retry-After.

---

Python SDK

The SDK is included in this repository at sdk/python/.

git clone https://github.com/gigshow/decker-ai-strategy-builder.git
pip install -e decker-ai-strategy-builder/sdk/python/

from decker_client import Client, RateLimitError, AuthError, NotFoundError

with Client(api_key="dk_live_xxx") as client:
    # Latest signal
    sig = client.signals.get_latest("BTCUSDT", timeframe="1h")
    print(f"{sig.direction} | entry={sig.entry_price} | target={sig.target_price}")
    print(f"progress: {sig.progress_pct}% | gate: {sig.operation_gate}")

    # Narrative
    narr = client.signals.get_narrative("BTCUSDT", "4h")
    print(narr.text)

    # Rate limit info
    rl = client.last_rate_limit
    print(f"{rl.remaining}/{rl.limit} remaining today")

Error handling:

try:
    sig = client.signals.get_latest("BTCUSDT")
except AuthError:
    print("Invalid API key — run /apikey reset in Telegram")
except NotFoundError:
    print("No active signal for this symbol/timeframe")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after}s")

pip install decker-client (PyPI) is planned — not yet published.
Full SDK reference: sdk/python/README.md · Developer API Guide

---

Performance

Backtest results, rules-path evaluation. Past performance does not guarantee future results.

Metric	Result	Condition
Win Rate	61–75%	Ranging market
Win Rate	70%+	Trending market
Avg Profit	4–10%	Per signal
Avg Loss	1–2%	Tight stop-loss
Max Drawdown	< 9%	Capital preservation
Signal Frequency	1–3 / day	Per symbol

Details: Signal Performance

---

Three Ways to Use Decker

Path	Who	How
A. Telegram Bot	Traders	@deckerclawbot → natural language
B. REST API	Any language	X-API-Key header → api.decker-ai.com/docs
C. Python SDK	Python devs	git clone + pip install -e sdk/python/
D. OpenClaw skill	AI agent devs	Add Decker skill → web_fetch → API responses
E. Self-host	Self-hosters	turnkey/ — Railway one-click

---

Docs

Document
Developer API Guide	Auth · Rate Limits · SDK · FAQ — start here if you're building
Quick Start	3-step guide for each path
API Guide	Full endpoint reference
Architecture	Pipeline, state engine, modules
Model & Algorithm	How the signal engine works
Operation Rules	Open YAML rulebook (v2.4.7+)
Signal Performance	Backtest & live metrics
Article Series (1–15)	Deep dives
Roadmap	What's next
llms.txt	LLM/AI agent discovery manifest

Concepts: Sequence Engine · Labeling Algorithm · Market State Theory

---

Article Series

Part 1 — Foundations (1–10): State Engine, signal lifecycle, YAML rulebook, multi-TF alignment, $0-LLM-cost architecture.

Part 2 — Context Engine (11–15): How markets speak in sequences, session state machine, GO/WATCH/HOLD gate, AI as explainer vs decision-maker.

→ Read the full series

---

Links

Service	https://decker-ai.com
API Docs	https://api.decker-ai.com/docs
Telegram bot	https://t.me/deckerclawbot
Kakao channel	https://pf.kakao.com/_RxlxjVX

---

This repository is the public documentation, SDK, samples, and community hub for Decker AI.
Production application code runs in a private monorepo.
Available here: Python SDK · API samples · RULES.yaml · Architecture docs · Article series