First Movement

Create and execute your first dry-run movement in QTG

02 - First Movement (Dry-Run)

Experience the full flow in dry-run mode: seed a template -> create a movement -> approve it -> check status. Confirm behavior through the API layer only, without live exchange integration.

Prerequisite: In 01-local-setup.md, the server is running on localhost:8100 with MG_AUTH_ENABLED=false and MG_WORKERS_ENABLED=false.

---

Three Different Decisions

There is no single “approval template”. Moving funds takes three separate decisions, and each one is necessary but none is sufficient on its own:

Decision	Answers	Scope	Who can make it
Allowlist entry	May funds go to this address at all?	(chain_family, address, chain_id?) — no token scope; optional cooling period	admin/operator proposes, a different admin applies
Route template	What shape does the route have (nodes, edges, completion)?	One immutable (template_key, version)	admin/operator proposes, a different admin applies
Movement approval	May this transfer (amount, recipient, plan hash) run?	One movement	operator/admin, per movement

• Registering a template does not approve anything. By default every movement created from it still waits in PENDING_APPROVAL for a human.
• An allowlisted destination only makes a movement eligible to dispatch. It is not an approval. CEX withdrawals also need the destination saved in the exchange’s own withdrawal whitelist.
• Automatic approval is a separate, bounded policy: a Free per-template cap (route_template.auto_approve proposal) or Pro auto_approve_policy proposals scoped to a strategy/client, allowed template versions, and amount caps. Agent-originated movements are never auto-approved.

Registration Ladder

1. Allowlist the destination (and the source, for strict on-chain lanes)   -> configuration proposal
2. (CEX) Save the destination in the exchange's withdrawal whitelist        -> exchange website
3. Register the route template version                                      -> configuration proposal
4. (Optional) Bounded auto-approve policy / trusted EVM target             -> proposal / admin grant
5. Per transfer: create movement -> review Approval Brief -> approve        -> operator
6. Dispatch re-checks plan hash and allowlist before any funds move          -> automatic

Remote configuration writes are proposal-only (maker/checker): POST /v3/plan-templates and the direct allowlist routes return 409 CONFIG_PROPOSAL_REQUIRED. Proposals are created and applied from the dashboard (Governance -> Configuration proposals) when MG_CONFIG_REMOTE_MUTATION_MODE=proposal_only; the applying admin must differ from the proposer. The dry-run below seeds its template and allowlist rows with a dev-only tool instead. See Movement Authorization Model for the full chain.

---

Full Flow

0. Seed allowlist + template   python -m qtg.interfaces.tools.dev_quickstart   (dev-only seed)
1. Inspect the route           GET  /v3/route-catalog
2. Create movement             POST /v3/movements
3. Approve movement            POST /v3/movements/{id}/approve
4. Check status                GET  /v3/movements/{id}

Why is there no POST /v3/plan-templates step? Template and allowlist writes are configuration changes, not transfers, and they are governed: the direct remote routes always return 409 CONFIG_PROPOSAL_REQUIRED. In a real deployment you register them as maker/checker configuration proposals (see Registering templates outside dev below). For this dry-run, a dev-only seed tool writes them straight into your local database.

---

Step 0: Seed the Dev Allowlist and Template

uv run --env-file .env python -m qtg.interfaces.tools.dev_quickstart

The tool is idempotent and seeds only your local database:

• placeholder CEX allowlist rows for upbit and binance
• the dry-run template dev.cex.upbit_to_binance.xrp (v1): withdraw -> withdrawal observe -> deposit observe
• dev HMAC keys you do not need while MG_AUTH_ENABLED=false

Step 1: Inspect the Route

curl -s http://localhost:8100/v3/route-catalog \
  | python -c 'import json,sys; print(json.dumps([r for r in json.load(sys.stdin)["routes"] if r["template_key"]=="dev.cex.upbit_to_binance.xrp"], indent=2))'

Check these fields on the entry:

• version: 1
• graph_shape: "linear" and executable: true
• risk_controls.max_amount - the only binding risk_controls key (enforced fail-closed at dispatch)

What the template body does and does not decide. risk_controls is free-form and only max_amount binds; asset_allowlist is descriptive (hash-pinned, not enforced). The approval_policy block (for example {"mode": "manual_first"}) is stored and returned but no runtime code reads it — it does not select manual or automatic approval. Approval is decided per movement (Step 3) or by a separate auto-approve policy.

Step 2: Create a Movement

Create a movement from the seeded template:

curl -s -X POST http://localhost:8100/v3/movements \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "dev.cex.upbit_to_binance.xrp",
    "template_version": 1,
    "intent": {
      "asset": "XRP",
      "amount": "25",
      "source": "upbit",
      "destination": "binance"
    },
    "input_params": {
      "asset": "XRP",
      "amount": "25",
      "network": "XRP",
      "destination_address": "rBinanceXRP...",
      "destination_tag": "12345"
    },
    "callback": {"url": "http://localhost:9999/callback"}
  }' | python -m json.tool

Check these fields in the response:

• movement_id: UUID - used in later API calls
• request_state: "PENDING_APPROVAL" - waiting for approval
• compiled_plan_hash: "sha256:..." - required for approval

You can create a movement without callback. It still works, but no state-change notifications are sent. The callback URL is a nested field — callback: {"url": "..."}, not a top-level callback_url (a top-level callback_url is silently ignored).

Step 3: Approve the Movement

Send the approval request with compiled_plan_hash:

# Copy movement_id and compiled_plan_hash from the response above
MOVEMENT_ID="<movement_id>"
PLAN_HASH="<compiled_plan_hash>"

curl -s -X POST "http://localhost:8100/v3/movements/${MOVEMENT_ID}/approve" \
  -H "Content-Type: application/json" \
  -d "{
    \"approver_id\": \"quickstart-operator\",
    \"compiled_plan_hash\": \"${PLAN_HASH}\"
  }" | python -m json.tool

Check these fields in the response:

• request_state: "APPROVED" -> if workers are enabled, it transitions to "EXECUTING"
• approval_status: "approved"

Why compiled_plan_hash is required: it guarantees the plan was not altered between creation and approval. Sending the wrong hash returns 409 Conflict.

Step 4: Check Status

curl -s "http://localhost:8100/v3/movements/${MOVEMENT_ID}" | python -m json.tool

In dry-run mode (MG_WORKERS_ENABLED=false):

• request_state stays at "APPROVED" (because the dispatcher is off)
• Node state stays "BLOCKED" (the first frontier node) or remains inactive

If workers are enabled and exchange credentials are configured:

• request_state: "EXECUTING" -> "COMPLETED"
• Node states advance per node kind. The representative path for a signing on-chain action node is BLOCKED -> READY -> PREPARING -> AWAITING_SIGNATURE -> SUBMITTING -> SUBMITTED -> OBSERVING -> COMPLETED. Common variants: a node needing no signature skips AWAITING_SIGNATURE; a sync-terminal submit (e.g. cex_withdrawal) goes SUBMITTING -> COMPLETED directly; an observe-only node (e.g. cex_deposit_status) goes READY -> OBSERVING -> COMPLETED.

Step 5: List Movements

# Full movement list
curl -s "http://localhost:8100/v3/movements" | python -m json.tool

# Filter by state
curl -s "http://localhost:8100/v3/movements?state=PENDING_APPROVAL" | python -m json.tool

---

Python Client Example

import httpx

BASE = "http://localhost:8100"

# (Template and allowlist rows come from Step 0: dev_quickstart)

# 2. Create movement
resp = httpx.post(f"{BASE}/v3/movements", json={
    "template_key": "dev.cex.upbit_to_binance.xrp",
    "template_version": 1,
    "intent": {"asset": "XRP", "amount": "25", "source": "upbit", "destination": "binance"},
    "input_params": {
        "asset": "XRP", "amount": "25", "network": "XRP",
        "destination_address": "rBinanceXRP...", "destination_tag": "12345",
    },
    # Optional: "callback": {"url": "http://localhost:9999/callback"}
})
data = resp.json()
movement_id = data["movement_id"]
plan_hash = data["compiled_plan_hash"]

# 3. Approve
resp = httpx.post(f"{BASE}/v3/movements/{movement_id}/approve", json={
    "approver_id": "quickstart",
    "compiled_plan_hash": plan_hash,
})
print(resp.json()["request_state"])  # APPROVED

# 4. Check status
resp = httpx.get(f"{BASE}/v3/movements/{movement_id}")
print(resp.json()["request_state"])

---

Movement State Flow Summary

PENDING_APPROVAL -> APPROVED -> EXECUTING -> COMPLETED
                                        -> FAILED
                 -> REJECTED (when rejected)

• PENDING_APPROVAL: Waiting for approval. POST .../approve or POST .../reject
• APPROVED: Approved. If workers are enabled, it automatically transitions to EXECUTING
• EXECUTING: Nodes are running
• COMPLETED: All nodes finished
• FAILED: An unrecoverable failure occurred

For the full state machine, see the States and Transitions reference.

---

Troubleshooting

Symptom	Cause	Fix
409 CONFIG_PROPOSAL_REQUIRED on POST /v3/plan-templates or an allowlist write	Direct remote configuration writes are disabled by design	Dev: run dev_quickstart (Step 0). Otherwise use a configuration proposal — see below
404 template not found on movement create	Step 0 not run against this database/network bucket	Run dev_quickstart with the same .env as the server
422 completion_assurance is required	completion_policy missing or misspelled	Valid values: provider_completed, destination_credited, destination_observed, destination_finalized, protocol_finalized
422 template graph must be a DAG	Cycle exists in the edges	Check edge direction
422 edge_type error	Using "then"	Use "on_success"
409 compiled plan hash mismatch	Hash mismatch at approval	Pass compiled_plan_hash exactly from the movement-create response
409 template is not executable in v3.0	Branching/merging graph	v3.0 executes only linear graphs

---

Registering Templates Outside Dev

dev_quickstart writes directly to a local database and is not a deployment path. Real template and allowlist changes are configuration proposals with maker/checker:

1. Set MG_CONFIG_REMOTE_MUTATION_MODE=proposal_only (the shipped default disabled returns 503 from the proposal routes).
2. An admin or operator creates the proposal in the dashboard: Governance -> Routes (/governance/routes) -> preset -> Register Template, or Destination addresses (/governance/allowlist) -> add. This submits POST /dashboard/configuration-proposals with kind route_template.register or allowlist.add.
3. A different admin reviews it under Governance -> Configuration proposals and applies it with the shown proposal digest. The maker cannot apply their own proposal; proposals expire after MG_CONFIGURATION_PROPOSAL_TTL_SECONDS (default 24h).

For host-level maintenance there is an audited maker/checker bypass CLI (python -m qtg.interfaces.tools.direct_register_plan_template --template-json-file ... --reason ... --direct-maintenance --apply) that also requires MG_CONFIG_DIRECT_MAINTENANCE_ENABLED=true, MG_CLI_AUTH_REQUIRED=true, and an admin CLI key. Without --apply it only previews.

Registering the template still approves nothing: every movement from it goes through Step 3.

---

Next: 03-template-cookbook.md - template examples by lane