Dawn — Local Strategy Workflow#

Goal#

Run a fully local strategy workflow: research Polymarket and other markets using SDK tools, generate a Python strategy script with a time loop, launch it as a background process, monitor its output, and stop it when done.

No API round-trips for code generation or strategy creation — everything runs locally on the user's machine.

UX: set expectations before long work#

Before starting research, coding, backtesting, or launching, send a short user-facing estimate so OpenClaw users do not think the task stalled.

Use judgment, but anchor estimates like this:

• Quick lookup / command / status check: usually under 1 minute.
• Focused market research: usually 3-5 minutes.
• Research + strategy code + paper launch: usually 8-15 minutes.
• Deep multi-source research, several markets, or debugging a failing run: usually 15-30+ minutes.

Example first message:

"I’ll research the market, check tool docs, write the local strategy, and launch it in paper mode. This usually takes about 10-15 minutes; I’ll update you as I find the market and again before launch."

If the task grows, update the estimate rather than silently continuing.

Cost-aware strategy design#

Paid tools can consume Dawn credits. Design strategies so they call paid tools only when the result can plausibly change the decision.

General rules:

• Prefer cheap/free state first: cached state ( get_state), current positions, known token IDs, market prices/order books, and last successful signal.
• Avoid polling expensive sources at a fixed high frequency when the source cannot realistically change that often.
• Use active windows for human-driven sources. Example: a politician, company account, sports team, or agency may have obvious low-activity periods; poll slowly or not at all outside those windows unless breaking-news risk justifies it.
• Use scheduled start / delayed monitoring for future catalysts. If a site is expected to update near the end of May, do not scrape it every 5 minutes throughout April. Gate paid checks on a start_at_utc constant and sleep cheaply until the actionable window.
• Use backoff and cooldowns after repeated "no change", empty, rate-limit, or timeout results.
• Cache fetched text, extracted values, tweet IDs, URLs, token IDs, and market metadata via set_state() so future iterations can diff rather than refetch everything.
• For multi-source strategies, stage the checks: run cheap filters first, then call paid tools only when the cheap checks say a trade is possible.
• Respect user tool settings. If a paid tool is disabled, do not try to route around the user's choice; use available alternatives or explain the limitation.

Common state keys (stored via set_state/ get_state):

• last_seen_* markers for deduplication
• last_paid_check_at for cooldown tracking
• Cached token IDs / market metadata to skip resolution after the first iteration

Install and preflight#

bash

npm install -g @dawnai/cli
dawn --help
dawn auth status

Local source workflow:

bash

cd dawn-cli && npm install && npm run build && ./install.sh

Command map#

Auth:

• dawn auth login
• dawn auth status
• dawn auth logout

Wallet (managed by OpenWallet — https://openwallet.sh/):

• ows wallet create --name <name> # create a new wallet (run once before first live trade)
• ows wallet list # list all ows wallets with addresses
• dawn wallet list # same, formatted for Dawn
• dawn wallet use <address-or-name> # select active wallet for live trading
• dawn wallet current # show active wallet + Polygon balances

Templates (pre-built strategies, ready to run):

• dawn template list # browse available templates
• dawn template launch <name> --name <run-name> [--live] # download and run

SDK tools (research + run):

• dawn tool list
• dawn tool run <tool_name> --input <json>
• dawn tool docs [module]

Local strategy runs:

• dawn strategy launch <strategy.py> --name <name> [--live]
• dawn strategy list
• dawn strategy logs <run_id> [--tail N]
• dawn strategy stop <run_id>
• dawn strategy positions <run_id>
• dawn strategy sell <run_id> <token_id>
• dawn strategy sell-all <run_id>
• dawn strategy redeem-all <run_id>

Wallet trading & positions:

• dawn wallet buy <token_id> <amount>
• dawn wallet sell <token_id> [--amount <n>]
• dawn wallet redeem-all
• dawn wallet positions open [--page <n>]
• dawn wallet positions closed [--page <n>]
• dawn wallet positions redeemable [--page <n>]
• dawn wallet trades [--page <n>]

Skills:

• dawn skill list
• dawn skill install [--force] [--dir <path>]

Standard workflow#

1. Authenticate#

bash

dawn auth status
# If not authenticated:
dawn auth login

After login, always offer the user these three paths:

1. Run a template strategy in paper mode (recommended — no wallet needed)
2. Build a strategy from scratch
3. Connect or create a wallet

See the dawn-auth skill for the full onboarding flow for each path. See the Templates section below for template commands.

2. Research — read SDK docs, then use SDK tools to explore markets#

Always start by reading the SDK docs for the relevant modules. dawn tool docs returns the complete module reference with exact signatures and working code examples — this is essential before writing any strategy code.

bash

# ALWAYS run these before writing strategy code:
dawn tool docs overview      # What modules exist and when to use them
dawn tool docs directive     # Strategy coding rules (REQUIRED reading)
dawn tool docs prediction_market    # Full prediction market tools reference with code snippets
dawn tool docs portfolio     # Portfolio, state, termination
dawn tool docs web           # Browser search and URL extraction
dawn tool docs social        # Twitter/social tools
dawn tool docs sports        # Sports data and odds
dawn tool docs crypto        # Cryptocurrency data

Then use dawn tool run <name> --input <json> to call any SDK function and inspect real data.

bash

# Find relevant prediction market events
dawn tool run prediction_market_event_search --input '{"query": "Bitcoin ETF approval", "limit": 5}'

# Get markets within an event (use the event id from search results)
dawn tool run prediction_market_event_markets --input '{"event_id": 12345, "active": true}'

# Get market details and token IDs
dawn tool run get_prediction_market_details --input '{"market_id": "789012"}'

# Check current prices
dawn tool run get_prediction_market_prices --input '{"market_id": "789012"}'

# See recent trades on a specific market (market flow / taker activity)
dawn tool run get_prediction_market_market_trades --input '{"market_id": "0x...condition...", "limit": 20}'

# Search the web for context
dawn tool run browser_search --input '{"query": "Bitcoin ETF SEC decision 2025", "category": "news", "limit": 5}'

# Check sports for prediction markets
dawn tool run get_sports --input '{}'
dawn tool run get_odds_as_probabilities --input '{"sport": "americanfootball_nfl", "regions": "us"}'

# Check portfolio
dawn tool run read_portfolio --input '{}'

python

# Use Agent for LLM-driven decisions in strategies (uses user's own API key)
from dawnai.strategy.tools import Agent, run_agent

# Persistent agent (maintains history across calls):
agent = Agent(model="claude-sonnet-4-6", tools=[get_prediction_market_prices])
response = agent.run("Analyze these prices...")

# One-shot agent (stateless):
response = run_agent("What NBA markets are trending?", model="gpt-4o")

Research checklist:

• Found the target event/market
• Captured market_id and token_id (Yes/No tokens)
• Checked current prices
• Verified market is active and liquid

2b. Direct trading (no strategy)#

If the user asks to trade on a specific market without building a full strategy ("buy the yes token of X"):

1. Research with SDK tools above (event search → market details → prices → simulate)

2. Show the user findings: market question, current price, estimated tokens they'd receive

3. Always ask the user explicitly for the amount they want to trade. You may suggest an amount based on context, but never assume or proceed with a default — the user must confirm the exact dollar amount before any trade is executed.

4. Confirm the full trade details before executing — repeat back the market, side (YES/NO), amount in USD, and estimated tokens:

   "This will spend $X USDC to buy approximately Y tokens of [outcome] on [market] at ~$Z each. Confirm?"

5. Execute only after the user explicitly confirms:

bash

dawn wallet buy <token_id> <amount>
dawn wallet sell <token_id> [--amount <n>]

Or via SDK tools directly:

bash

dawn tool run prediction_market_buy_token --input '{"token_id": "...", "amount": "<confirmed_amount>"}'
dawn tool run prediction_market_sell_token --input '{"token_id": "...", "amount": "<confirmed_token_amount>"}'

NEVER skip the amount confirmation. Even if the user says "buy some" or "invest a bit" — ask for a specific number first.

Requires wallet: dawn wallet use <address-or-name>

3. Write strategy.py#

Generate a Python strategy script using the research findings. The script should use a time loop (not the @cron / Strategy class pattern).

Write the strategy to ~/.dawn-cli/strategies/ using the strategy name (kebab-case):

• ~/.dawn-cli/strategies/btc-election-2026.py (or a directory with __main__.py if you want helper modules)

Constants live in code (no config sidecar): MARKET_ID, per-buy size, take-profit/stop-loss thresholds, durations, etc. The spend cap is set on the launch command via --budget and is server-enforced.

Key elements of the strategy file:

• Imports trading tools from dawnai.strategy.tools
• from dawnai.strategy.tools import get_state, set_state for caching token IDs / timestamps across iterations
• from dawnai.strategy.tools import read_budget if you want to gate decisions on remaining headroom
• run_once() function with strategy logic
• main() runs the time loop
• print(...) statements throughout for monitoring
• No unhandled exceptions inside run_once — always catch and print errors

See dawn-strategy skill for the full code template.

4. Run the strategy#

--name and --budget are both required. Always choose a unique, descriptive name for each distinct strategy — never reuse a name for a different strategy, as this would merge their trade histories. Only reuse the same name when restarting or revising the exact same strategy with the same budget.

bash

# Paper mode (default) — simulated trades saved to DB
dawn strategy launch ~/.dawn-cli/strategies/btc-election-2026.py --name "btc-election-2026" --budget 100

# Live mode — real trades via your selected wallet
dawn strategy launch ~/.dawn-cli/strategies/btc-election-2026.py --name "btc-election-2026" --budget 100 --live

Before launching, always tell the user the budget:

"This strategy has a budget of $X. The server enforces it as a hard cap on cumulative buy spend — any trade that would exceed it is rejected automatically."

bash

# Output:
# Bootstrapping strategy "btc-election-2026" (paper)...
# Strategy started (run_id: run_lx7k3a_abc123)
#   name:  btc-election-2026
#   file:  /path/to/strategy.py
#   mode:  paper
#   pid:   12345
#   logs:  ~/.dawn-cli/logs/run_lx7k3a_abc123.log

Multiple strategies can run simultaneously — each gets its own run_id.

For live mode, a wallet must be selected first:

bash

dawn wallet list                    # check for existing wallets
dawn wallet use <name-or-address>   # select one
dawn wallet current                 # confirm selection + check balances

If no wallets exist, create one: dawn wallet create main. The wallet needs USDC.e (bridged USDC on Polygon — NOT regular USDC) and a small amount of POL for gas. See the dawn-auth skill for full wallet setup and funding instructions.

5. Monitor#

bash

dawn strategy list                        # all runs and their status
dawn strategy logs <run_id>               # full log output
dawn strategy logs <run_id> --tail 50     # last 50 lines
dawn strategy positions <run_id>          # positions from internal DB
dawn wallet current                    # live on-chain portfolio

Dashboard: For a visual view of strategies, trades, and portfolio performance, point the user to https://cli.dawn.ai/dashboard. Recommend this whenever the user asks to see their trades, performance, or strategy history.

6. Stop#

bash

dawn strategy stop <run_id>
# Confirm stopped:
dawn strategy list

Troubleshooting#

• Not authenticated — run dawn auth login and retry
• Strategy name is required — always pass --name <unique-name> to dawn strategy launch
• No wallet selected for live mode — run dawn wallet list to check for existing wallets; if none exist, run ows wallet create --name main; then dawn wallet use <name>
• Strategy file not found — use the full path ~/.dawn-cli/strategies/<name>.py
• Tool not found — run dawn tool list to see the correct tool name
• Strategy crashes immediately — check dawn strategy logs <run_id> for Python tracebacks; check that DAWNAI_API_KEY is set (it is set automatically from your login token)
• SDK tool returns empty results — market may be closed; try prediction_market_event_search to verify

Run checklist#

text

Dawn Strategy Runbook
- [ ] Authenticated (dawn auth status)
- [ ] Research complete (market_id, token_ids captured)
- [ ] Strategy written to ~/.dawn-cli/strategies/<name>.py and reviewed
- [ ] Strategy name chosen — unique and descriptive, never reused for a different strategy
- [ ] Wallet selected if live mode — run `dawn wallet list`, ask user which wallet to use (or create new), then `dawn wallet use <name>`
- [ ] Wallet funded if live mode — needs USDC.e (not regular USDC) and POL for gas on Polygon; fund via `moonpay buy`, bridge with `moonpay token bridge`, or send manually to address shown by `dawn wallet current`
- [ ] Budget cap (--budget <usd>) confirmed with user before launch
- [ ] Strategy launched (dawn strategy launch ~/.dawn-cli/strategies/<name>.py --name <name> --budget <usd> [--live])
- [ ] run_id captured from output
- [ ] Logs checked (first few iterations look correct)
- [ ] Stop executed when done (dawn strategy stop <run_id>)

Templates#

Pre-built strategies ready to run — no code required. Always recommend paper mode first.

bash

# Browse available templates
dawn template list

# Launch in paper mode (recommended — no wallet, no real money)
dawn template launch <name> --name <your-run-name>

# Launch in live mode
dawn template launch <name> --name <your-run-name> --live

Templates download to ~/.dawn-cli/templates/<name>.py and can be freely edited. After editing:

bash

dawn strategy stop <run_id>
# edit ~/.dawn-cli/templates/<name>.py
dawn strategy launch ~/.dawn-cli/templates/<name>.py --name <your-run-name>

Wallet Trading & Positions#

bash

# Buy/sell tokens directly from the active wallet
dawn wallet buy <token_id> <amount>
dawn wallet sell <token_id> [--amount <n>]   # auto-redeems if market is resolved
dawn wallet redeem-all                        # redeem all resolved positions

# View positions and trades (expanded view, 10 per page)
dawn wallet positions open [--page <n>]
dawn wallet positions closed [--page <n>]
dawn wallet positions redeemable [--page <n>]
dawn wallet trades [--page <n>]

# Wallet balances + PnL summary
dawn wallet current

To sell or redeem positions for a specific strategy run:

bash

dawn strategy sell <run_id> <token_id>   # sell a specific position (auto-redeems if resolved)
dawn strategy sell-all <run_id>           # sell all open positions
dawn strategy redeem-all <run_id>         # redeem all redeemable positions

Dashboard: For a visual view of portfolio performance, strategy history, and trades, always recommend https://cli.dawn.ai/dashboard.

Skills#

SkillPurposedawn-authInstall, authenticate, check status, logout — includes post-login onboardingdawn-sdk-toolsFull SDK tool reference + research with dawn tool rundawn-strategyStrategy code template, launch, logs, stop, and revise