Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

14.6 KB
Raw Blame

agent-orders — Programmable Orders Engine worker

Set-and-forget institutional order tooling for memecoins. Pump.fun has no native order types; this worker gives every agent wallet a real programmable order layer: limit, stop, trailing stop, DCA, TWAP, and validated conditional triggers ("buy when smart-money score > 60 and mcap < $40k", "sell if the dev dumps", "buy on graduation").

What it does

Every ORDERS_POLL_MS it sweeps all active/partial orders, re-quotes each mint off live on-chain state (bonding curve → AMM after graduation), evaluates the trigger/schedule, and on a match fires the order through executeAgentTrade (api/agents/agent-trade.js) — the same pipeline the owner-driven trade endpoint uses:

quote → rug/honeypot firewall → spend guards (kill switch, per-trade cap,
daily budget, USD ceiling) → custody claim → MEV-aware sign+confirm → audit

The orders worker adds no new way to move funds — it only decides when to call that one audited path. Every fill is firewall-gated, capped by the agent's spend policy, and written to agent_custody_events (the canonical spend ledger), with an order_fills receipt linking back to it.

Any SPL token, ladders, OCO and the order book

Orders are not limited to pump.fun mints. Each fill picks a venue (Jupiter or PumpSwap) from live liquidity and runs the same audited executor. Beyond single orders the engine supports ladders (several take-profit levels in one call), OCO pairs (one fill cancels its sibling), expiry, price bands, and a per-agent order book (api/_lib/order-book.js) that reports the next fire time and one closed-vocabulary skip reason per order. The sweep notifies the owner when an order fires, fails, expires or starts waiting. MCP tools and the preview-then-confirm contract: docs/mcp.md ("Orders and DCA on any SPL token"). Tests: tests/orders-any-token.test.js, tests/orders-engine.test.js, tests/agent-orders-sweep.test.js.

Order lifecycle

active → firing → filled (price/conditional, single fill) · active → partial → … → filled (DCA/TWAP, one slice per interval) · → cancelled (instant, owner) · → expired (deadline) · → error (a terminal block such as a firewall rug verdict).

  • Idempotent. Each fire claims its order atomically (active|partial → firing) so exactly one sweep fires it; across processes the custody idempotency_key (order:<id>:slice:<n>) is the double-spend backstop.
  • Per-agent serialized. An agent's orders run under a per-agent lock so two orders can't both pass the daily-budget check on the same stale total.
  • Honest on data gaps. No live quote → the order holds (never fires on a missing/zero price). A conditional with a missing signal does not fire.
  • Self-healing. Stale firing claims (a crash mid-fire) are recovered each sweep; expired deadlines are swept to expired.

Triggers

Type Fires when
limit buy / sell metric ≤ target (dip) / ≥ target (rise)
stop sell / buy metric ≤ stop (stop-loss) / ≥ stop (breakout)
trailing sell / buy metric ≤ peak·(1−trail%) / ≥ trough·(1+trail%)
trail_ratchet sell the two-phase stop below: initial wide stop, then lock tiers that never loosen
dca next_fire_at ≤ now, one slice per interval, N slices
twap same scheduling; slices ONE total order to cut impact
conditional a validated { all|any: [{ signal, op, value }] } is true

trigger_metric ∈ price_sol | mcap_sol | mcap_usd. Conditional signals: price_sol, mcap_sol, mcap_usd, price_change_pct, smart_money_score, dev_dump, graduated — all real, code-free (see api/_lib/orders.js).

Ratcheting trailing stop (trail_ratchet)

A sell-only stop with two phases, pure logic in api/_lib/exit-ratchet.js:

  1. Phase 1, the wide stop. The position gets room to breathe: the order sells if the trigger metric falls ratchet.initial_stop_pct below the entry.
  2. Phase 2, lock tiers. ratchet.tiers is [{ profit_pct, lock_pct }], ascending. Once the high-water mark has shown profit_pct over the entry, the stop is never below entry * (1 + lock_pct/100). The high-water mark only rises, so a tier stays armed after price falls back under its trigger.

The entry is entry_price (in the trigger metric) when the order is placed, otherwise the first live reading the sweep takes. A gap down through a lock tier still exits on the first sweep that sees it, at the live fill, because the test is value <= stop. Create it from the Orders tab (Ratchet) or POST /api/agents/:id/orders with { type: "trail_ratchet", side: "sell", mint, sell_pct, ratchet: { initial_stop_pct: 30, tiers: [{ profit_pct: 50, lock_pct: 10 }] }, entry_price? }.

Reason codes

Every ratchet exit and every guard refusal carries a stable code, shown as a chip on the order card and in Activity, written to agent_order_events (meta.reason_code for exits, a [CODE] prefix on the skip detail for refusals), and recorded on the agent's decision trail as kind order_exit for exits:

Code Meaning
DRAWDOWN price fell through the phase 1 initial stop
TIER_LOCK price fell back to a locked-in profit tier
DAILY_LOSS a fill was refused because the agent hit its daily loss limit
IMPACT a fill was refused because price impact exceeded the safety limit

Sizing a percentage sell (DCA and TWAP differ on purpose)

Both scheduled types accept sell_pct, and they mean different things:

  • DCA measures against the live bag every slice. "DCA out 10% an hour" disposes 10% of whatever is still held, so the position asymptotes rather than closing, which is what a dollar-cost exit is.
  • TWAP measures against the bag at creation. The API divides the owner's total across the slices (total_pct / slices), so the worker re-bases each later slice onto what is left of that promise: sell 100% over 4 slices disposes a real quarter of the original bag each time and the last slice sells the remainder outright. Applying the stored per-slice percentage to the live holding instead would dispose 25 / 18.75 / 14.06 / 10.55%, strand ~31.6% of the position, and still mark the order filled.

One sweep reads at most 500 active orders per network, ordered by COALESCE(next_fire_at, last_eval_at, created_at): due slices first, then least-recently-evaluated. Past that cap the work set rotates rather than starving one side of the book.

Run

npm run worker:orders          # ORDERS_MODE=simulate (real quotes, no broadcast)
npm run worker:orders:live     # ORDERS_MODE=live (real fills)

Both scripts load the repo-root .env and .env.local if they exist (node --env-file-if-exists, applied in that order so .env.local wins), so a local run needs no extra flags. Loading both matters: in this worktree .env holds only the QA audit login and the worker's own credentials (DATABASE_URL, JWT_SECRET, WALLET_ENCRYPTION_KEY, SOLANA_RPC_URL) live in .env.local. Reading .env alone makes the worker die at boot on missing required env var: DATABASE_URL. The container sets its env from Cloud Run instead and ships neither file. On boot the worker prints one JSON line per event (boot, housekeeping, fill, …) and writes a bot_heartbeat row under the worker name agent-orders, which is the fastest liveness check:

SELECT mode, last_beat_at, meta FROM bot_heartbeat WHERE worker = 'agent-orders';

Env

loadConfig (config.js) validates all of this once at boot and throws rather than start half-configured.

Var Default Notes
DATABASE_URL, JWT_SECRET none required (any POSTGRES_URL/NEON_DATABASE_URL alias also satisfies the first)
WALLET_ENCRYPTION_KEY none required in live mode: it decrypts the custodial agent key. Wrong/absent, every fill dies at key recovery and retries forever
ORDERS_NETWORK mainnet mainnet|devnet
ORDERS_MODE simulate live also requires SOLANA_RPC_URL or HELIUS_API_KEY
ORDERS_POLL_MS 10000 sweep cadence, floored at 3000
ORDERS_CONCURRENCY 4 agents evaluated in parallel per sweep, clamped to 1-16
ORDERS_STALE_FIRING_MS 180000 recover crash-orphaned firing claims older than this, floored at 60000
ORDERS_GLOBAL_KILL 0 halt all fires (orders untouched; cancel still works via the API)
ORDERS_HEARTBEAT_MS 30000 bot_heartbeat liveness write (0 disables)

The worker never serves user traffic, so it needs no rate-limit backend; the execution path touches Postgres and Solana RPC only.

Tests

npx vitest run tests/orders-engine.test.js tests/agent-orders-sweep.test.js tests/exit-ratchet.test.js

tests/orders-engine.test.js covers the pure rule layer (api/_lib/orders.js: validation, condition evaluation, price predicates). tests/agent-orders-sweep.test.js covers this worker: that a matched trigger fires exactly once through executeAgentTrade with the custody idempotency key, that a missing quote holds instead of firing, that terminal vs clearable blocks land in error vs back in active, DCA slice advance, TWAP percentage-sell re-basing (including the full-exit last slice), per-agent serialization, and the boot-config guards. Only the chain reads and the trade executor are stubbed, so the real store SQL and the real trigger predicates run.

Beyond the suites, two checks prove the live edges the stubs replace. The market reader against $THREE on mainnet returns a real graduated-AMM quote:

node --env-file-if-exists=.env -e "import('./workers/agent-orders/market.js').then(async m => \
  console.log(await m.getSignals({ network: 'mainnet', mint: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump' })))"

And a short npm run worker:orders run writes the heartbeat row and answers the liveness endpoint (PORT=8791 npm run worker:orders, then curl localhost:8791). Both were last exercised on 2026-08-14: the quote came back as a real graduated-AMM price in ~12 s through the RPC failover chain, and a 30 s boot ran 5 sweeps (427 ms each), answered / with {"ok":true,"worker":"agent-orders",…}, wrote bot_heartbeat, and drained cleanly on SIGTERM.

Deploy

Status: built and wired, not yet running in production (re-checked 2026-08-14: no agent-orders service, no job, and no image in the workers Artifact Registry repo). No order fires on its own until someone runs the command below. Orders created through the API sit in active until then, which is the honest failure mode (nothing fires early, nothing fires wrong). Deploys are owner-gated; everything else is ready.

The target is Cloud Run as a background-daemon service, like agent-sniper. It isn't request-driven, but index.js binds a liveness endpoint on $PORT so the startup probe passes; --no-cpu-throttling + --min-instances=1 keep the sweep timer ticking between probes. One command, from the repo root:

gcloud builds submit --config workers/agent-orders/cloudbuild.yaml . \
  --region us-central1 --project aerial-vehicle-466722-p5 \
  --substitutions=SHORT_SHA=manual$(date +%s)

SHORT_SHA is only auto-populated for trigger-driven builds; a manual submit must pass it or the image tag comes out empty. The four secrets the config mounts (agent-orders-database-url, agent-orders-jwt-secret, agent-orders-wallet-encryption-key, agent-orders-solana-rpc-url) already exist and are readable by the three-ws@ runtime service account; all four were re-checked on 2026-08-14 (each carries the roles/secretmanager.secretAccessor binding, and each payload hashes identical to the value three-ws-api runs with). Do not repoint them at the project's generic JWT_SECRET / WALLET_ENCRYPTION_KEY secrets: those hold older values and would break custodial key recovery on every live fill.

It ships in ORDERS_MODE=simulate (real quotes, no broadcast). Flip _ORDERS_MODE=live (build substitution) or update the running service's ORDERS_MODE only after agent wallets are funded. It can equally run as a Cloud Run Job (jobs get no startup probe, so PORT is unset and no listener binds; the sweep loop is unaffected either way).

Verifying the image without deploying

The deploy config above always ends in gcloud run deploy. To prove the image still builds without shipping it, use the build-only config next to it:

gcloud builds submit . \
  --config workers/agent-orders/cloudbuild.verify.yaml \
  --ignore-file workers/agent-orders/verify.gcloudignore \
  --region us-central1 --project aerial-vehicle-466722-p5

Same Dockerfile, same repo-root context, no push and no deploy. Last green 2026-08-14 (build 28d998f3, 4m43s, all 14 layers, 95.7 MiB uploaded).

The equivalent local build is docker build -f workers/agent-orders/Dockerfile -t agent-orders ., but expect it to fail on a dev container: the image installs the whole root workspace (3000+ packages) and then compiles agent-payments-sdk, which is more memory than a Codespace has, and the local context is not filtered by .gcloudignore so it also walks a multi-GB dist/. Cloud Build is the supported path.

A green build proves less than it looks like it does, because two ways of breaking this image only show up when the container boots. Re-check both if you add an import to any file under workers/agent-orders/:

  • Every module the worker reaches must be inside the Dockerfile's COPY set (agent-payments-sdk/, api/, src/, workers/agent-orders/, and the single file workers/agent-sniper/amm-exit.js). Reaching outside it builds fine and then dies at ERR_MODULE_NOT_FOUND on the first sweep.
  • Every bare import must be a prod dependency. The image runs npm prune --omit=dev, so an import that resolves to a devDependency disappears from the shipped layer.

Both held on 2026-08-14: 59 modules reached, all inside the COPY set, and all 17 distinct bare specifiers resolve to prod dependencies or the workspace SDK.

One thing about the build log is worth knowing before you read it as a failure: the repo-root package-lock.json is out of sync with package.json, so the image's npm ci exits with EUSAGE (missing @ethereum-attestation-service/* and friends) and the Dockerfile's || npm install fallback carries the install. Expected today, and shared with every other worker image.

The migration is api/_lib/migrations/20260623160000_programmable_orders.sql (npm run db:migrate). The owner-facing surface is the Orders tab in the agent wallet hub (src/agent-wallet-hub/tabs/orders.js), backed by /api/agents/:id/orders.