From e523f4d7577add49eddfdbc4f4e236ebc83d7032 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Thu, 30 Apr 2026 19:25:42 -0700 Subject: [PATCH] docs: use server-side --traits filter from opensea-skill v2.2.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit opensea-skill v2.2.3 added a `--traits` flag to three collection-scoped commands — `nfts list-by-collection`, `listings best`, and `events by-collection`. The previous attempt to document this on the copilot side (#6, closed) walked the agent through a client-side scan because the server filter didn't exist yet. Now it does. SOUL.md → How You Work: one bullet calling out the three endpoints that accept --traits, the AND-combine semantics, the OR workaround (one call per value + union token IDs), the empty-array vs error distinction, and the >1000-match 400 fallback. Points at the new "Server-side trait filtering" section in the skill for the full reference. No AGENTS.md change — the only reason the prior draft introduced `memory/trait_holders..json` and a `trait_scans` cursor in `scan_state.json` was to support whole-collection scanning. Server-side filtering removes that need. Co-Authored-By: Claude Opus 4.7 (1M context) --- workspace/SOUL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/workspace/SOUL.md b/workspace/SOUL.md index 4fc98e3..9acd0ea 100644 --- a/workspace/SOUL.md +++ b/workspace/SOUL.md @@ -62,6 +62,7 @@ Before submitting any transaction, run the gate in order. Any RED stops the flow - **Ordering:** run requests sequentially on the shared `OPENSEA_API_KEY`. Parallel fans out 429s. - **Memory:** `memory/floors.json` = latest watchlist snapshot (overwrite each heartbeat). `memory/actions.jsonl` = append-only log of anything with a side-effect. `memory/taste.json` = structured taste model you maintain per collection. See `AGENTS.md` for schemas. - **Stale-reject listings:** before proposing a buy, re-fetch the listing — OpenSea will 404 or return a new order hash if it expired. +- **Trait filtering: pass `--traits`.** Three collection-scoped commands accept it server-side: `nfts list-by-collection`, `listings best`, `events by-collection`. Format is a JSON array of `{traitType, value}` and multiple entries are AND-combined. For OR semantics (e.g. `feet = skateboard OR hoverboard`), issue one call per value and union the token IDs. An empty result array means no matches, not an error. If the server 400s with "more than 1000 matches," AND in another trait to narrow. Don't paginate the whole collection to filter in-process. Schema lookup: `opensea collections traits `. Full reference: `skills/opensea/SKILL.md` → *Server-side trait filtering*. ## Wallet