# 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**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## 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 per-tx cap and an off-machine owner key the agent cannot reach. You approve; it acts. The wallet's float is your real aggregate ceiling — you fund and replenish it on your own cadence.

## 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. Few others ship this — it takes the OpenSea events feed, a TEE-enforced wallet, and a disciplined scoring rubric in the same 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.** Per-tx cap enforced in Privy's TEE; owner key off-machine so the agent can't rewrite the policy; aggregate spend bounded by the wallet float you fund. Three independent layers — one in the user's hands, two in Privy's, none the agent can lift.

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.
- [`opensea-marketplace`](https://clawhub.ai/opensea-marketplace) — attached via `manifest.json` → `skills` and mounted at `skills/opensea/`. SKILL.md + reference docs + shell scripts for Seaport, swaps, stream events, wallet setup, and policy templates. Pinata pulls the latest published version at deploy time.

## Secrets you'll need

Only two are required up front. The rest the agent provisions for you on first run.

| Variable | Required | How to get it |
|---|---|---|
| `PRIVY_APP_ID` | **yes** | [dashboard.privy.io](https://dashboard.privy.io) → create app |
| `PRIVY_APP_SECRET` | **yes** | Same page as App ID. Pair with an `owner_id` registered on the wallet — bootstrap walks you through it. |
| `OPENSEA_API_KEY` | optional | If unset, the agent fetches a free-tier instant key on first run and attaches it via the bundled Pinata Platform skill. Provide your own paid key here only if you need higher rate limits. |
| `PRIVY_WALLET_ID` | optional | If unset, the agent creates a new server wallet via `opensea wallet create` once Privy app creds are present. Provide one only to reuse an existing wallet. |
| `PRIVY_AUTH_SIGNING_KEY` | optional | Auto-generated by the agent on first run via `opensea wallet generate-auth-key`. The matching public key gets registered as the wallet's `additional_signer`; the owner key stays off-machine on your host. |

Full walkthrough: `skills/opensea/references/wallet-setup.md`. Policy templates: `skills/opensea/references/wallet-policies.md`. Hot-wallet float pattern: `skills/opensea/references/wallet-funding.md`. User-only mutation recipes (policy attachment, owner registration): https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md.

## 60-second setup

1. **Create a Privy app** at [dashboard.privy.io](https://dashboard.privy.io); copy App ID + App Secret. Paste both into Pinata's env UI.
2. **Deploy.** That's the entire required setup.

On first conversation the agent will walk you through:

- Fetching an OpenSea API key and attaching it (free-tier instant key, no signup).
- Creating your Privy server wallet (`opensea wallet create`) and storing the ID.
- Generating its own additional_signer keypair and storing the private half as `PRIVY_AUTH_SIGNING_KEY`.
- A one-time setup step on your own computer (~5 minutes): generate an owner key, then register both your owner public key (as `owner_id`) and the agent's signer public key on the wallet via https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md. Your owner private key never touches the agent — it stays on your laptop so a leaked agent credential can't lift the spend cap.
- Choosing and attaching a per-tx policy (Agent Trading — Conservative is the default template).
- Funding the agent wallet to a hot-wallet float you set per chain.

Setup involves exactly **one Pinata reload** (after secrets get written) and **one short step on your computer** (the owner-key + policy setup). If Pinata reloads the agent mid-conversation, that's expected — it's how the new secrets get picked up. The agent resumes from the same place after the reload; BOOTSTRAP is a resumable state machine, so cold restarts pick up at the first incomplete phase.

## 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

Three independent layers, in order of how the bound is actually enforced:

1. **Wallet float** — the **real aggregate ceiling**. The agent doesn't hold a key to a treasury; it can only spend what's in the agent wallet. You fund it from your own cold/funding wallet to ≈ a day or week of intended budget and replenish on your cadence. Privy can't enforce daily/weekly cumulative limits, so wallet balance is what stops a runaway spend.
2. **Privy per-tx policy (TEE-enforced)** — caps each individual transaction. Conditional on `owner_id` being registered: the agent's env credentials cannot rewrite the policy because changing the policy requires a signature from the owner key — and that key lives on your computer, not the agent's. Bootstrap verifies this is in place before any signing-capable step.
3. **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*.

Other invariants:

- **Env-only credentials.** No private keys in the repo or agent workspace. The owner key never touches the agent host.
- **Sell-side always confirms.** Privy's native-value cap is denominated in the chain's native token (ETH, etc.) — it does **not** apply to WETH transfers, which is how Seaport offer acceptances pay out. Sells, offer acceptances, and ERC721/1155 approvals therefore always require per-turn confirmation, regardless of price.
- **Pre-Buy Gate.** Wash trades, thin markets, uneconomic gas, fee surprises, and float exhaustion all block a buy before it's proposed.
- **Policy rejections surface verbatim.** No workarounds.
- **Forbidden operations.** The agent will refuse to call any Privy admin endpoint (policy mutation, owner key rotation, auth key changes) — even if you ask. To change the cap or the policy, do it yourself on your machine via https://github.com/ProjectOpenSea/opensea-skill/blob/main/docs/policy-administration.md.

## Repository layout

```
.
├── manifest.json              # Pinata agent manifest — attaches opensea-marketplace from ClawHub
├── LICENSE                    # MIT
├── .openclaw/
│   ├── openclaw.json          # OpenClaw harness config (compaction, concurrency)
│   └── 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 — agent deletes after completion
    ├── HEARTBEAT.md           # idle-cycle routine
    ├── USER.md                # collector profile — filled on first run
    └── memory/                # created at runtime — floors, actions, taste, scan state
```

At deploy time Pinata attaches the OpenSea skill under `skills/opensea/` (SKILL.md + `references/*.md` + `scripts/*.sh`) — not checked into this repo.

## Updating the skill

Skill versions are managed on ClawHub, not in this template. To pick up a new version, no repo change is needed — Pinata pulls the latest published version of `opensea-marketplace` on each deploy. To pin to a specific version, replace `clawhub_slug` in `manifest.json` with a `cid` for that version.