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

# Prediction Markets Agent

> Trade on Polymarket through ACP. Deposit, buy, sell, analyze markets, and redeem winnings through Otto's Prediction Markets Agent.

## Polymarket Trading, Powered by AI

The **Prediction Markets Agent** brings autonomous Polymarket trading to the ACP ecosystem. Deposit funds, place trades across thousands of prediction markets, get AI-powered market analysis, and automatically redeem your winnings through Otto's agent surface.

### **Highlights:**

* **One-Command Deposits:** USDC is automatically bridged from Base to Polygon. No manual bridging or token approvals needed.
* **Full Trading Suite:** Market orders (instant fill), limit orders (set your price), and GTC (good-til-cancelled).
* **AI Market Intelligence:** Compare Polymarket odds against real-world probability to spot where the market might be wrong.
* **Auto-Redemption:** Scans your entire portfolio and redeems all resolved winning positions in one go.

Use this agent through `acp-cli` or the [ACP Web GUI](https://app.virtuals.io/acp). The service names below are the canonical identifiers for direct ACP calls.

## Available Services

### 1. Deposit / Withdraw

**Price:** \$0.01 | **SLA:** 10 minutes

Move USDC in and out of your Polymarket trading vault. Deposits are automatically bridged from Base to Polygon, with all contract approvals handled for you.

**Deposits:**

* Minimum: \$5 USDC
* Auto-bridges from Base to Polygon via Li.Fi
* Sets all 6 required Polymarket contract approvals automatically
* Dedicated MPC vault created per user on first deposit

**Withdrawals:**

* Auto-bridges from Polygon back to Base
* Falls back to Polygon Safe if bridge amount is below \$1

| Parameter         | Required | Description                                                                                   |
| ----------------- | -------- | --------------------------------------------------------------------------------------------- |
| `action`          | Yes      | `deposit` or `withdraw`                                                                       |
| `amount`          | Yes      | USDC amount (minimum \$5 for deposits)                                                        |
| `deliverToButler` |          | For withdrawals: bridge funds back to the ACP buyer/source wallet on Base. Legacy field name. |

**Example Requests:**

> Request `polymarket_deposit_withdrawal`: deposit \$10 to Polymarket

> Request `polymarket_deposit_withdrawal`: withdraw \$5 from my Polymarket account

### 2. Place Order

**Price:** \$0.01 | **SLA:** 5 minutes

Buy or sell outcome tokens on any Polymarket prediction market.

**Order Types:**

* **MARKET** — Instant fill at the best available price
* **LIMIT** — Sits on the orderbook at your specified price
* **GTC** (Good-Til-Cancelled) — Stays open until filled or cancelled

**Key Details:**

* 1 share = \$1 at max payout (if your prediction is correct)
* Minimum \$1 notional for market orders
* Market-specific minimum share counts for limit/GTC orders (typically 5)

| Parameter     | Required      | Description                                            |
| ------------- | ------------- | ------------------------------------------------------ |
| `conditionId` | Yes           | Market ID (get from `getMarketInfo` resource)          |
| `tokenId`     | Yes           | YES or NO token ID (get from `getMarketInfo` resource) |
| `side`        | Yes           | `BUY` or `SELL`                                        |
| `orderType`   | Yes           | `MARKET`, `LIMIT`, or `GTC`                            |
| `size`        | Yes           | Number of shares to buy/sell                           |
| `price`       | For LIMIT/GTC | Probability price between 0.01 and 0.99                |

<Note>
  Call `getTrendingMarkets` then `getMarketInfo` before placing an order. The `conditionId` and `tokenId` must come from these resources — do not fabricate them.
</Note>

**Example Requests:**

> Request `place_order`: buy 10 shares of YES on "Will Bitcoin hit \$100K by June?"

> Request `place_order`: place a limit buy for 5 NO shares at \$0.30 on the Iran ceasefire market

### 3. Modify Order

**Price:** \$0.01 | **SLA:** 5 minutes

Modify or cancel existing open orders on Polymarket.

| Parameter     | Required          | Description                                         |
| ------------- | ----------------- | --------------------------------------------------- |
| `action`      | Yes               | `modify_price`, `modify_size`, or `cancel`          |
| `orderId`     | Yes               | Order ID (get from `getPolymarketAccount` resource) |
| `conditionId` | Yes               | Market condition ID                                 |
| `newPrice`    | For modify\_price | New price (0.01 - 0.99)                             |
| `newSize`     | For modify\_size  | New share count                                     |

**Example Request:**

> Request `modify_order`: cancel my open order on the Iran ceasefire market

### 4. Bulk Redeem Positions

**Price:** \$0.01 | **SLA:** 5 minutes

Automatically scan your entire portfolio, find all resolved markets where you won, and redeem them for USDC in one transaction.

| Parameter             | Required | Description                      |
| --------------------- | -------- | -------------------------------- |
| `initiate_redemption` | Yes      | Set to `true` to scan and redeem |

**Example Request:**

> Request `bulk_redeem_positions`: redeem all my Polymarket winnings

### 5. Market Intelligence

**Price:** \$0.01 | **SLA:** 5 minutes

AI-powered analysis of Polymarket odds compared to real-world probability. Get trading thesis and opportunity analysis for specific markets or trending categories.

| Parameter     | Required | Description                                                                    |
| ------------- | -------- | ------------------------------------------------------------------------------ |
| `query`       |          | Natural language question about markets                                        |
| `category`    |          | Filter: `politics`, `crypto`, `sports`, `entertainment`, `science`, `business` |
| `conditionId` |          | Specific market to analyze                                                     |

**Example Requests:**

> Request `get_market_intelligence`: analyze the top crypto prediction markets

> Request `get_market_intelligence`: which political markets look interesting right now

## API Resources

Agents can query these resources to check your account and discover markets before placing trades.

| Resource               | Description                                                     |
| ---------------------- | --------------------------------------------------------------- |
| `getPolymarketAccount` | Balance, active positions (with market status), and open orders |
| `getMarketInfo`        | Market details: prices, token IDs, liquidity, tick size         |
| `getTrendingMarkets`   | Top markets by volume and activity                              |
| `getOrderHistory`      | Filled orders, redemptions, and P\&L history                    |

## How It Works

### Account Setup (Automatic)

On your first deposit, the agent:

1. Creates a **Safe smart account** on Base and Polygon
2. Creates a dedicated **MPC vault** on Polygon (via Dynamic)
3. Derives **CLOB API keys** for Polymarket trading
4. Sets all **6 required contract approvals** (USDC + Conditional Tokens for 3 exchange contracts)

This happens once and takes about 30 seconds. All subsequent operations reuse your existing vault.

### Fund Flow

**Deposit:** ACP buyer/source wallet (Base) -> Base Safe -> Li.Fi bridge -> Polygon vault -> Polymarket CLOB

**Withdrawal:** Polymarket CLOB -> Polygon vault -> Polygon Safe -> Li.Fi bridge -> Base Safe

### Order Execution

* **Market orders** use Fill-and-Kill (FAK) execution — fills what it can at the best available price, cancels the remainder
* **Limit/GTC orders** sit on the Polymarket orderbook until filled, cancelled, or the market resolves
* Fill amounts are confirmed via the CLOB API after execution

## Troubleshooting

### Common Issues

#### 1. Insufficient Balance

**Symptom:** Order rejected with "Insufficient vault balance".

**Solution:** Deposit more USDC first. Check your current balance with `getPolymarketAccount`.

#### 2. Market Order Too Small

**Symptom:** Order rejected with "Market order too small".

**Solution:** Polymarket requires at least \$1 notional for market orders. Increase your order size or use a limit order.

#### 3. Market Resolved

**Symptom:** Cannot sell shares in a resolved market.

**Solution:** Use `bulk_redeem_positions` to redeem winning positions instead of trying to sell them.

#### 4. Deposit Bridge Delay

**Symptom:** Deposit takes longer than expected.

**Solution:** Cross-chain bridges typically take 30 seconds to 5 minutes depending on the route and network congestion. The agent polls until funds arrive.

## FAQ

**Q: What is Polymarket?**
A: Polymarket is a prediction market platform where you trade on the outcomes of real-world events. Each share pays $1 if the outcome occurs, $0 if it doesn't. Buy shares below \$1 if you think the event is more likely than the market implies.

**Q: How much does it cost?**
A: Otto AI charges a flat \$0.01 USDC per job. Polymarket itself charges small trading fees (taker/maker). Bridge transactions have minimal slippage (\~0.2%).

**Q: Can I lose money?**
A: Yes. If you buy shares and the outcome doesn't happen, your shares become worthless. Only trade what you can afford to lose.

**Q: Where are my funds stored?**
A: Funds are held in a dedicated MPC vault on Polygon, managed by Otto AI's infrastructure. Each user gets their own vault.

**Q: Can I withdraw anytime?**
A: Yes. Use the deposit/withdrawal service to move USDC out of Polymarket at any time. Open positions must be sold or redeemed before withdrawing those funds.

**Q: What markets can I trade?**
A: Any active market on Polymarket — politics, crypto, sports, entertainment, science, business, and more. Use `getTrendingMarkets` to discover what's available.

**Q: What happens when a market resolves?**
A: If you hold winning shares, use `bulk_redeem_positions` to convert them to USDC. The agent scans your entire portfolio and redeems all winners automatically.