# nft-collector-copilot

**Repository Path**: ProjectOpenSea/nft-collector-copilot

## Basic Information

- **Project Name**: nft-collector-copilot
- **Description**: ⛵ NFT Collector Copilot - a Pinata OpenClaw agent template. Watches OpenSea collections, alerts on floor moves, buys listings via a Privy server wallet.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NFT Collector Copilot

An AI agent for NFT collectors. Watches [OpenSea](https://opensea.io), scores every listing across five signals (price, volume, depth, holders, momentum), and executes Seaport trades through a [Privy](https://privy.io) server wallet with a TEE-enforced spend cap. You approve; it acts.

## The killer feature: **Whale-Cross Alerts**

Point it at a list of wallets you respect (vitalik.eth, your favorite PFP whale, whoever) and your watchlist. When a tracked whale buys, mints, or lists into any collection — whether it's on your watchlist or not — you get a one-line alert within a heartbeat, with a one-click follow gated by your Privy spend cap. Nobody else ships this because nobody else has the OpenSea Stream API, a TEE-enforced wallet, and a scoring rubric in one box.

## What it does

- **Watchlist floor + volume tracking** with per-slug alert thresholds and sell-side flip triggers.
- **Conviction Score** before any recommendation — price vs 7d median, 7d/30d volume ratio, listing depth, holder concentration, momentum.
- **Pre-Buy Gate** — wash-trade check, thin-market refusal, gas economics, full-cost (with fees) disclosure, balance & buffer check, policy-fit check.
- **Seaport buys + sells** via `@opensea/cli` + the skill's fulfillment scripts, signed by your Privy wallet.
- **Drop Radar** — upcoming/featured drops cross-referenced against your taste model.
- **Taste learning** — every buy/pass/ask updates a structured `taste.json` so recommendations get sharper over time.
- **Spend-cap safety.** The Privy policy is the real enforcement — the agent literally cannot overspend.

Supported chains: see `workspace/TOOLS.md`. Mainnets only by default.

## What's bundled

- [`@opensea/cli`](https://github.com/ProjectOpenSea/opensea-cli) — installed globally at build time.
- [`ProjectOpenSea/opensea-skill`](https://github.com/ProjectOpenSea/opensea-skill) at `skills/opensea/` (git submodule, pinned to `v2.1.0`) — SKILL.md + 7 reference docs + shell scripts for Seaport, swaps, stream events, wallet setup, and policy templates.

## Secrets you'll need

Paste these into Pinata's environment UI at deploy time:

| Variable | Required | How to get it |
|---|---|---|
| `OPENSEA_API_KEY` | yes | `curl -s -X POST https://api.opensea.io/api/v2/auth/keys \| jq -r .api_key` — no signup |
| `PRIVY_APP_ID` | yes | [dashboard.privy.io](https://dashboard.privy.io) → create app |
| `PRIVY_APP_SECRET` | yes | Same page as App ID |
| `PRIVY_WALLET_ID` | yes | Create a server wallet — see `skills/opensea/references/wallet-setup.md` → *Privy* |

Full walkthrough: `skills/opensea/references/wallet-setup.md`. Policy templates: `skills/opensea/references/wallet-policies.md`.

## 60-second setup

1. **Grab an OpenSea API key** — run the curl above.
2. **Create a Privy app** at [dashboard.privy.io](https://dashboard.privy.io); copy App ID + App Secret.
3. **Create a server wallet** following `skills/opensea/references/wallet-setup.md` → *Privy* → step 2. Save `id` as `PRIVY_WALLET_ID`.
4. **Attach a spend policy** — the agent will walk you through this on first run using the "Agent Trading — Conservative" template from `skills/opensea/references/wallet-policies.md`. Start tight.
5. **Fund the wallet** on whichever chains you plan to trade on.
6. **Deploy** — paste all four env vars into Pinata, then chat.

## Example prompts

> "Add boredapeyachtclub, pudgypenguins, and azuki to my watchlist on ethereum. Alert me on any floor drop over 5%."

> "Follow vitalik.eth and 0xpunks4156 as whales — high-priority alerts."

> "Should I buy this azuki at 2.1 ETH? Run the full gate."

> "Any upcoming drops this week that fit my taste?"

> "What's the best offer on my bored ape #1234? Is it worth flipping?"

> "Swap 0.05 ETH into USDC on Base."

> "Walk me through tightening the wallet policy to cap buys at 0.1 ETH."

## Safety model

- **Env-only credentials.** No private keys in the repo or agent workspace.
- **Privy policy is the hard ceiling.** The spend cap, destination allowlist, and chain filter are enforced inside a TEE before signing.
- **Per-turn confirmation for material actions.** Any buy, offer acceptance, approval, or transfer above `confirmAboveEth` (in `workspace/TOOLS.md`) needs explicit "yes" in the current turn. Snipes can bypass this only when the listing is fully inside your configured envelope — see `workspace/SOUL.md` → *Hierarchy of Ceilings*.
- **Sell-side always confirms.** The native-value Privy cap doesn't constrain WETH offer acceptances, so those always require per-turn approval regardless of price.
- **Pre-Buy Gate.** Wash trades, thin markets, uneconomic gas, and fee surprises all block a buy before it's proposed.
- **Policy rejections surface verbatim.** No workarounds.

## Repository layout

```
.
├── manifest.json              # Pinata agent manifest
├── setup.sh                   # build: submodule init + CLI install
├── .openclaw/
│   ├── openclaw.json
│   └── SOUL.md                # short canonical persona — points at workspace/SOUL.md
├── workspace/
│   ├── SOUL.md                # guardrails + Conviction Score + Pre-Buy Gate
│   ├── AGENTS.md              # workspace conventions + memory schemas
│   ├── IDENTITY.md            # blank — filled on first run
│   ├── TOOLS.md               # watchlist, whales, budgets — user-tunable
│   ├── BOOTSTRAP.md           # first-run walkthrough
│   ├── HEARTBEAT.md           # idle-cycle routine
│   └── USER.md                # collector profile — filled on first run
└── skills/opensea/            # submodule: opensea-skill @ v2.1.0
    ├── SKILL.md
    ├── references/*.md        # rest-api, seaport, wallet-setup, wallet-policies, …
    └── scripts/*.sh           # opensea-fulfill-listing.sh, opensea-stream-collection.sh, …
```

## Updating the skill

```bash
git -C skills/opensea fetch --tags
git -C skills/opensea checkout v2.2.0   # or whichever tag you want
git add skills/opensea && git commit -m "chore: bump opensea-skill to v2.2.0"
```