Documentation

Shell Agent & TypeScript SDK — npm packages for quants and bots

npm @shell-finance/shell-agentnpm @shell-finance/sdkv0.1.0 · Sui testnet

shell-agent is an autonomous trading daemon for Shell Finance. The LLM drives both sides of the loop: it picks IOI terms (side, size range, price range, TTL) from live market data + your policy each posting window, then decides accept / reject / wait on every match proposal the enclave returns. When it accepts, it builds and submits the sealed order transaction without any human intervention.

The agent is designed for quants running systematic strategies or market makers who want to operate in the dark pool programmatically. Bring your own LLM key (OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint including local Ollama). Write your trading policy in plain English — the LLM calls tools like get_ref_price, get_my_balance, and check_risk_cap to inform both IOI-term selection and match acceptance.

Install — local (recommended)

sh
mkdir my-agent && cd my-agent
npm init -y
npm install @shell-finance/shell-agent

Local install pins the agent version in your package.json, colocates your plugins/ + mcp.json with the project, avoids global PATH issues, and lets multiple projects run different agent versions side-by-side.

Install — global (alternative)

sh
npm install -g @shell-finance/shell-agent

Use global only for ops boxes running a single daemon with no project dir. Plugin / MCP discovery is identical either way — both read from process.cwd().

Run commands

sh
# local install — prefix with npx
npx shell-agent run          # live trading loop — posts IOIs, polls proposals, LLM decides
npx shell-agent demo         # dry-run: two synthetic agents trade against each other
npx shell-agent post-ioi     # post one IOI and exit

# global install — no prefix
shell-agent run

Minimal .env

NOTE Shell is currently testnet-only. The agent defaults to AGENT_NETWORK=testnet — flip to mainnet once Shell deploys there.
env
# Required
AGENT_PRIVATE_KEY=suiprivkey1...    # Sui Ed25519 keypair (sui keytool export)
# AGENT_NETWORK=testnet             # default. Flip to "mainnet" once Shell ships on mainnet.

# LLM — pick one
OPENAI_API_KEY=sk-...               # shortcut: defaults to openai + gpt-4o-mini
# or
LLM_PROVIDER=anthropic              # openai | anthropic | google | openai-compatible
LLM_MODEL=claude-haiku-4-5-20251001
LLM_API_KEY=sk-ant-...

# Trading policy — LLM uses this for BOTH IOI posting and match acceptance.
# Prices: 1e6-scaled USDC (1.00 USDC = 1_000_000)  Sizes: 1e9-scaled SUI (1 SUI = 1_000_000_000)
AGENT_POLICY=Accumulate 1-3 SUI when DeepBook mid < 1.0 USDC. Max position 10 SUI. Skip posting if spread > 2%. Accept matches priced between 900000 and 1100000.

Decision lifecycle — two LLM-driven decisions per cycle

(1) IOI posting — every TTL window (default 60min) the LLM runs a bounded tool-use loop (max 6 rounds), then returns:

json
// Post an IOI
{ "skip": false,
  "reasoning": "string",
  "side": "buy" | "sell",
  "asset": "0x2::sui::SUI",
  "size_lo": 100000000, "size_hi": 200000000,
  "price_lo": 900000, "price_hi": 1100000,
  "ttl_min": 60 }

// Or skip this window
{ "skip": true, "reasoning": "spread too wide" }

(2) Match acceptance — for each MatchProposal received, a second LLM loop produces:

json
{
  "decision": "accept_match" | "reject_match" | "wait",
  "reasoning": "string explaining why",
  "policy_check": true  // true only if policy provably satisfied via tool checks
}