stacks-market

What this skill does

# Stacks Market Skill

Trade prediction markets on [stacksmarket.app](https://www.stacksmarket.app) via the on-chain contract `SP3N5CN0PE7YRRP29X7K9XG22BT861BRS5BN8HFFA.market-factory-v18-bias`.

- **Market Discovery** — List and search prediction markets via REST API with filters for status, category, and featured flag.
- **Price Quoting** — Get real-time LMSR prices for YES/NO shares via on-chain read-only calls before committing funds.
- **Trading** — Buy YES or NO shares with slippage protection (`buy-yes-auto`, `buy-no-auto`). Sell with minimum proceeds guard (`sell-yes-auto`, `sell-no-auto`).
- **Redemption** — Redeem winning shares after market resolution (1 share = 1 STX for winners).
- **Position Tracking** — Check your YES and NO share balances in any market.

All operations are **mainnet-only**. Write operations (buy-yes, buy-no, sell-yes, sell-no, redeem) require an unlocked wallet (use `bun run wallet/wallet.ts unlock` first).

## Usage

```
bun run stacks-market/stacks-market.ts <subcommand> [options]
```

## Subcommands

### list-markets

List prediction markets from stacksmarket.app. Returns markets sorted by most recent activity.

```
bun run stacks-market/stacks-market.ts list-markets [--limit <n>] [--status <status>] [--category <cat>] [--featured]
```

Options:
- `--limit` (optional) — Number of markets to return (default: 20)
- `--status` (optional) — Filter by status: `active` | `ended` | `resolved`
- `--category` (optional) — Filter by category (e.g., `Crypto`, `Politics`)
- `--featured` (optional) — Show only featured markets

Output:
```json
{
  "network": "mainnet",
  "marketCount": 5,
  "markets": [
    {
      "_id": "699c573ea7bb5ad25fee68a0",
      "marketId": "1771853629839",
      "title": "Will BTC close above $100k by end of Q1?",
      "category": "Crypto",
      "isActive": true,
      "isResolved": false,
      "endDate": "2026-03-31T23:59:00.000Z",
      "totalVolume": 5000000000,
      "totalTrades": 42
    }
  ]
}
```

### search-markets

Search prediction markets by keyword. Searches titles and descriptions.

```
bun run stacks-market/stacks-market.ts search-markets --query <keyword> [--limit <n>]
```

Options:
- `--query` (required) — Search keyword
- `--limit` (optional) — Maximum results (default: 10)

Output:
```json
{
  "network": "mainnet",
  "query": "bitcoin",
  "resultCount": 3,
  "markets": [
    {
      "_id": "699c573ea7bb5ad25fee68a0",
      "marketId": "1771853629839",
      "title": "Will BTC close above $100k by end of Q1?",
      "isActive": true,
      "isResolved": false
    }
  ]
}
```

### get-market

Get full details for a single prediction market including trade history and order book.

```
bun run stacks-market/stacks-market.ts get-market --market-id <mongoId>
```

Options:
- `--market-id` (required) — MongoDB `_id` of the market (e.g., `699c573ea7bb5ad25fee68a0`)

Output:
```json
{
  "network": "mainnet",
  "market": {
    "_id": "699c573ea7bb5ad25fee68a0",
    "marketId": "1771853629839",
    "title": "Will BTC close above $100k by end of Q1?",
    "description": "Resolution source: CoinGecko closing price...",
    "category": "Crypto",
    "options": [
      { "text": "Yes", "impliedProbability": 52, "totalVolume": 3000000000 },
      { "text": "No", "impliedProbability": 48, "totalVolume": 2000000000 }
    ],
    "isActive": true,
    "isResolved": false,
    "winningOption": null,
    "endDate": "2026-03-31T23:59:00.000Z",
    "totalVolume": 5000000000,
    "totalTrades": 42,
    "tradeHistory": []
  }
}
```

### quote-buy

Get a price quote for buying YES or NO shares. Always quote before buying to verify cost and slippage.

```
bun run stacks-market/stacks-market.ts quote-buy --market-id <id> --side <yes|no> --amount <shares>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp, e.g., `1771853629839`)
- `--side` (required) — `yes` or `no`
- `--amount` (required) — Number of shares to buy (integer, e.g., `5` for 5 shares)

Output:
```json
{
  "network": "mainnet",
  "quote": {
    "marketId": "1771853629839",
    "side": "yes",
    "shares": 5,
    "totalCostUstx": 5250000,
    "totalCostStx": "5.25",
    "fees": {
      "protocolUstx": 125000,
      "lpUstx": 75000
    }
  }
}
```

### quote-sell

Get a price quote for selling YES or NO shares. Always quote before selling to verify proceeds.

```
bun run stacks-market/stacks-market.ts quote-sell --market-id <id> --side <yes|no> --amount <shares>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp)
- `--side` (required) — `yes` or `no`
- `--amount` (required) — Number of shares to sell (integer)

Output:
```json
{
  "network": "mainnet",
  "quote": {
    "marketId": "1771853629839",
    "side": "yes",
    "shares": 5,
    "totalProceedsUstx": 4750000,
    "totalProceedsStx": "4.75",
    "fees": {
      "protocolUstx": 125000,
      "lpUstx": 75000
    }
  }
}
```

### buy-yes

Buy YES shares in a prediction market. Uses `buy-yes-auto` for slippage protection. Requires an unlocked wallet.

```
bun run stacks-market/stacks-market.ts buy-yes --market-id <id> --amount <shares> --max-cost <ustx>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp)
- `--amount` (required) — Number of YES shares to buy
- `--max-cost` (required) — Maximum total cost in uSTX (slippage protection). Get from `quote-buy` first.

Output:
```json
{
  "success": true,
  "txid": "abc123...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet",
  "trade": {
    "marketId": "1771853629839",
    "side": "yes",
    "shares": 5,
    "maxCostUstx": 5500000
  }
}
```

### buy-no

Buy NO shares in a prediction market. Uses `buy-no-auto` for slippage protection. Requires an unlocked wallet.

```
bun run stacks-market/stacks-market.ts buy-no --market-id <id> --amount <shares> --max-cost <ustx>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp)
- `--amount` (required) — Number of NO shares to buy
- `--max-cost` (required) — Maximum total cost in uSTX (slippage protection)

Output:
```json
{
  "success": true,
  "txid": "abc123...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet",
  "trade": {
    "marketId": "1771853629839",
    "side": "no",
    "shares": 5,
    "maxCostUstx": 5500000
  }
}
```

### sell-yes

Sell YES shares before market resolution. Uses `sell-yes-auto` with minimum proceeds guard. Requires an unlocked wallet.

```
bun run stacks-market/stacks-market.ts sell-yes --market-id <id> --amount <shares> --min-proceeds <ustx>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp)
- `--amount` (required) — Number of YES shares to sell
- `--min-proceeds` (required) — Minimum acceptable proceeds in uSTX (slippage protection). Get from `quote-sell` first.

Output:
```json
{
  "success": true,
  "txid": "abc123...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet",
  "trade": {
    "marketId": "1771853629839",
    "side": "yes",
    "shares": 5,
    "minProceedsUstx": 4500000
  }
}
```

### sell-no

Sell NO shares before market resolution. Uses `sell-no-auto` with minimum proceeds guard. Requires an unlocked wallet.

```
bun run stacks-market/stacks-market.ts sell-no --market-id <id> --amount <shares> --min-proceeds <ustx>
```

Options:
- `--market-id` (required) — Market ID (epoch millisecond timestamp)
- `--amount` (required) — Number of NO shares to sell
- `--min-proceeds` (required) — Minimum acceptable proceeds in uSTX

Output:
```json
{
  "success": true,
  "txid": "abc123...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet",
  "trade": {
    "marketId": "1771853629839",
    "side": "no",
    "shares": 5,
    "minProceedsUstx": 4500000
  }
}
```

### redeem

Redeem winning shares after market resolution. Winning shares pay 1