> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkpool.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents

> TradeCap-delegated agents with research tools and runtime-owned guardrails.

AI agents already drive about 30% of Polymarket volume but most platforms don't natively support them. DarkPool's agent layer makes the agent a **first-class citizen** with three differentiators:

1. **TradeCap delegation.** Agents trade via a DeepBook V3 `TradeCap` over the vault's `BalanceManager`. They have no withdrawal rights. The owner can pause, resume, or revoke at any time.
2. **On-chain identity + reputation.** `TradeAgent` is a key-store object holding name, owner, BalanceManager id, TradeCap id, and a signed-PnL u128 counter. The fleet leaderboard at `/agents` is ranked by computed realized P\&L.
3. **Native LLM mode.** Connect GPT, Claude, or Llama through one OpenAI-compatible client. The model researches via tools (live oracles, strike book, recent fills, Pyth candles), forms a thesis, and trades under runtime-owned guardrails.

## Custody model

<Frame caption="Owner and operator are two separate addresses. The owner holds AgentOwnerCap (privileged actions: pause / resume / record outcome). The operator holds TradeCap (place + cancel orders). withdraw_all is owner-gated by Move. Neither can do the other's job.">
  <img src="https://mintcdn.com/dp-550c5f99/d2IOef9E8cHmelrt/images/agents-custody.png?fit=max&auto=format&n=d2IOef9E8cHmelrt&q=85&s=afd70fc224a21ace84d347e92e48ed75" alt="Custody model: Owner address holds AgentOwnerCap and uses it for pause / resume and record outcome on the Shared BalanceManager (which holds DUSDC + YES + NO). Operator address holds TradeCap and uses it to place and cancel orders on the same Shared BalanceManager. The BalanceManager interacts with DeepBook V3 pools as the on-chain protocol interaction. withdraw_all (owner-gated by Move) runs from Owner to the BalanceManager. Legend: Owner actions (privileged), Operator actions (via capability), Protocol interaction (on-chain), Capability holding / ownership." width="1693" height="929" data-path="images/agents-custody.png" />
</Frame>

The operator never has withdrawal rights. `balance_manager::withdraw_all<DUSDC>` is **owner-gated by Move**. The owner reclaims funds with one button (`OwnerControls.Reclaim` on `/agents/:agentId`).

## Strategies

`AGENT_STRATEGY` env var selects the brain:

* `alternate`. Heuristic. Walks \$50 strike rungs outward from spot, trades the first ask inside `ask_bounds`. Alternates YES and NO each tick.
* `yes-only`. Same probe, YES side only.
* `no-only`. Same probe, NO side only.
* `llm`. Native AI mode. The model gets research tools and submits a structured `submit_decision`. The runtime executes under hard guardrails.

Missing `LLM_API_KEY` falls back to `alternate` with a warning.

## Owner controls

`/agents/:agentId` exposes two on-chain owner actions:

* **Reclaim.** Calls `balance_manager::withdraw_all<DUSDC>` and transfers the coin back to the wallet. Owner-gated by Move even on the shared BM.
* **Pause / Resume.** Calls `agent::pause(&mut TradeAgent, &AgentOwnerCap)` or `::resume`. The agent runtime reads `is_active` at the start of every tick via `sui.getObject` and skips trading with one humanized "paused on-chain by owner" feed entry.

Live state: `sui.getObject(TradeAgent)` returns `balance_manager_id` and `is_active`, plus devInspect of `balance_manager::balance<DUSDC>`. The frontend header shows a yellow **PAUSED on-chain** badge whenever `is_active=false`.

## Wizard

`/agents` carries a **Create agent** wizard. One PTB does:

```text theme={"system"}
balance_manager::new
  to mint_trade_cap
  to (optional) DUSDC deposit
  to agent::register_agent
```

TradeCap goes to the operator address (separate keypair), BalanceManager is shared, TradeAgent + AgentOwnerCap go to the creator. Plus a Groq model selector (Llama 3.3 70B, 3.1 8B Instant, Gemma 2 9B) and a downloadable mandate. See [Running an Agent](/guides/running-agent).

See also: [Agent Runtime](/agents/overview).