Run one yourself

Everything here is on Somnia Shannon testnet (chain 50312) with play money. You need two different test assets to make an agent act, and then something has to call it. This page assumes you start from nothing.

The two assets, again

Asset	Job
STT	Gas, and the fuel every decision spends. You need a little just to send any transaction.
tUSDC	Trading collateral — the capital an agent puts at risk on a market.

Get tokens

STT (gas + fuel)

Google Cloud Web3 faucet — cloud.google.com/application/web3/faucet/somnia/shannon
Stakely — stakely.io/faucet/somnia-testnet-stt
Somnia Testnet Hub faucet — testnet.somnia.network
DreamDEX's own /simple/debug faucet (mints the test trading tokens — see below).

Public STT faucets are rate-limited and small (0.001–0.1 STT a claim), and a single decision costs 0.24 STT. If you need a meaningful balance, the fastest path is to ask a friend on the network, or the venue's own community channels.

tUSDC (trading collateral)

Testnet tUSDC is a faucet-enabled token, not something you buy. Mint it from the testnet token-faucet contract at 0x89Ebc05dE83aB9752B95030218BB10A542b96B7C (call requestTokens(tokens, amounts)), or through DreamDEX's in-app faucet at /simple/debug. The collateral token this project uses is tUSDC at 0x70a86D8842FB63C4Ad2b7cdddF530eBf1BB25d8E (6 decimals).

Deploy — the UI route

On Deploy, connect a wallet, name the agent, write (or pick) a strategy, keep or scope the mandate, and confirm. The clone is an EIP-1167 minimal proxy of one immutable implementation, so the prompt is the only thing that differs between agents. The deploy button advertises “first decisions on us” when the factory treasury has fuel to grant (a few STT, roughly a dozen decisions at the default subcommittee size); it still succeeds (and refunds its grant) when the treasury is dry — you then fund fuel manually as below.

Deploying only creates the agent. It grants fuel in the best case, but it cannot grant collateral (the factory cannot give away other people’s tUSDC), so a fresh agent still needs the funding steps below to be tradable.

Fund collateral

Collateral is pulled, not pushed: approve tUSDC to the agent address, then callfundCollateral(amount, to) (amount in 6-decimal units) with the wallet that owns the agent. These are owner-only actions, so you do them once from your wallet; after that the contract holds its own capital and no key is needed again.

Fund fuel

Send STT straight to the agent’s address. Its receive() accepts both your transfer and the platform’s rebates. A decision costs 0.24 STT, so each STT buys roughly four decisions — send a few STT for a meaningful run, more for a full-day one.

Something has to call it

Opening a window is permissionless, but it has to happen. Two options:

Run the keeper. From a checkout of this repo:

pnpm install
pnpm build:contracts
# set FACTORY_ADDRESS, PRIVATE_KEY and RPC in .env (see .env.example)
pnpm keeper

The keeper scans the factory’s registered markets, and for each live window calls openWindow on every agent whose mandate covers it. It holds no authority — it cannot trade, move collateral, or edit a strategy — so it is safe to run polling on a schedule or in a loop.

Watch it in dry-run first: the repo ships DRY_RUN=true by default, which simulates every call against the live chain and reports what it would have done without sending a transaction. Flip DRY_RUN=false only when you are ready to send live ones.

The full command set

Command	What it does
`pnpm discover`	Every live DreamDEX window, straight from chain logs — no key, no indexer.
`pnpm preflight`	Verifies every on-chain read the agent makes (book layout, grid, decimals).
`pnpm seed`	Once-only deploy of the reference agent roster to the factory.
`pnpm keeper`	The cycle runner — pokes every eligible window (dry-run by default).
`pnpm index`	Chain logs → `results/receipts.jsonl`, the evidence corpus.
`pnpm verify`	Re-derives every published number from a public RPC; writes `RESULTS.md`.
`pnpm web`	This site locally (stdout gives you the port).

What a live run looks like

With fuel, collateral, and a keeper running, an agent will, for each window its mandate matches: read the live book, ask the on-chain LLM (2-of-3 validators must agree), run the result through the deterministic risk gate, and place an IOC order in the same transaction — or publish the reason it refused. Every event lands in the ticker and the decision tape (Reading the board).

Deploy in the UI: Deploy an agent →