ProjectOpenSea-opensea-skill

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: opensea-wallet
#3	description: Set up and configure wallet signing providers for OpenSea transactions. Supports Privy, Turnkey, Fireblocks, Bankr, and local private keys. Required for executing trades (opensea-marketplace) and token swaps (opensea-swaps).
#4	homepage: https://github.com/ProjectOpenSea/opensea-skill
#5	repository: https://github.com/ProjectOpenSea/opensea-skill
#6	license: MIT
#7	env:
#8	PRIVY_APP_ID:
#9	description: Privy application ID for wallet signing (default provider)
#10	required: false
#11	obtain: https://dashboard.privy.io
#12	PRIVY_APP_SECRET:
#13	description: Privy application secret
#14	required: false
#15	obtain: https://dashboard.privy.io
#16	PRIVY_WALLET_ID:
#17	description: Privy wallet ID to sign transactions with
#18	required: false
#19	TURNKEY_API_PUBLIC_KEY:
#20	description: Turnkey API public key
#21	required: false
#22	obtain: https://app.turnkey.com
#23	TURNKEY_API_PRIVATE_KEY:
#24	description: Turnkey API private key
#25	required: false
#26	TURNKEY_ORGANIZATION_ID:
#27	description: Turnkey organization ID
#28	required: false
#29	TURNKEY_WALLET_ADDRESS:
#30	description: Turnkey wallet address
#31	required: false
#32	FIREBLOCKS_API_KEY:
#33	description: Fireblocks API key
#34	required: false
#35	obtain: https://console.fireblocks.io
#36	FIREBLOCKS_API_SECRET:
#37	description: Fireblocks API secret
#38	required: false
#39	FIREBLOCKS_VAULT_ID:
#40	description: Fireblocks vault account ID
#41	required: false
#42	BANKR_API_KEY:
#43	description: Bankr API key for HTTP-based agent wallet signing
#44	required: false
#45	obtain: https://bankr.bot
#46	dependencies:
#47	- node >= 18.0.0
#48	---
#49
#50	# OpenSea Wallet
#51
#52	Set up and configure wallet signing providers for OpenSea transactions. The CLI and SDK auto-detect which provider to use based on environment variables, or you can specify one explicitly with `--wallet-provider`.
#53
#54	## When to use this skill (`scope_in`)
#55
#56	Use `opensea-wallet` when you need to:
#57
#58	- Set up a wallet provider for the first time (Privy, Turnkey, Fireblocks, Bankr, or local keys)
#59	- Configure signing policies (value caps, allowlists, multi-party approval)
#60	- Switch between wallet providers
#61	- Understand the security model for each provider
#62
#63	## When NOT to use this skill (`scope_out`, handoff)
#64
#65	\| Need \| Use instead \|
#66	\|---\|---\|
#67	\| Query NFT/token data \| `opensea-api` \|
#68	\| Buy/sell NFTs \| `opensea-marketplace` \|
#69	\| Swap ERC20 tokens \| `opensea-swaps` \|
#70	\| Build/register/gate AI agent tools \| `opensea-tool-sdk` \|
#71
#72	## Quick start
#73
#74	```bash
#75	# 1. Pick a managed provider and set its env vars (Privy default shown)
#76	export OPENSEA_API_KEY=your_key
#77	export PRIVY_APP_ID=your_app_id
#78	export PRIVY_APP_SECRET=your_app_secret
#79	export PRIVY_WALLET_ID=your_wallet_id
#80
#81	# 2. Use the wallet via any signing-capable command
#82	opensea swaps execute \
#83	--from-chain base --from-address 0x0000000000000000000000000000000000000000 \
#84	--to-chain base --to-address 0xb695559b26bb2c9703ef1935c37aeae9526bab07 \
#85	--quantity 0.001
#86	```
#87
#88	For other providers, see the table below and `references/wallet-setup.md`.
#89
#90	## Supported providers
#91
#92	\| Provider \| Env Vars \| Best For \|
#93	\|----------\|----------\|----------\|
#94	\| Privy (default) \| `PRIVY_APP_ID`, `PRIVY_APP_SECRET`, `PRIVY_WALLET_ID` \| TEE-enforced policies, embedded wallets \|
#95	\| Turnkey \| `TURNKEY_API_PUBLIC_KEY`, `TURNKEY_API_PRIVATE_KEY`, `TURNKEY_ORGANIZATION_ID`, `TURNKEY_WALLET_ADDRESS` \| HSM-backed keys, multi-party approval \|
#96	\| Fireblocks \| `FIREBLOCKS_API_KEY`, `FIREBLOCKS_API_SECRET`, `FIREBLOCKS_VAULT_ID` \| Enterprise MPC custody, institutional use \|
#97	\| Bankr \| `BANKR_API_KEY` \| Agent wallets via Bankr's HTTP signing API \|
#98	\| Private Key (local dev only) \| `PRIVATE_KEY`, `RPC_URL`, `WALLET_ADDRESS` \| Local dev/testing only (no spending limits or guardrails) \|
#99
#100	The CLI and SDK handle signing automatically once env vars are set. Auto-detect order: Privy, Fireblocks, Turnkey, Bankr, Private Key. To specify a provider explicitly:
#101
#102	```bash
#103	opensea swaps execute --wallet-provider turnkey ...
#104	opensea swaps execute --wallet-provider fireblocks ...
#105	opensea swaps execute --wallet-provider bankr ...
#106	opensea swaps execute --wallet-provider private-key ...
#107	```
#108
#109	## Security
#110
#111	- Managed providers (Privy, Turnkey, Fireblocks, Bankr) are strongly recommended over raw private keys.
#112	- Raw `PRIVATE_KEY` is for local development only. Never paste a raw private key into a shared agent environment, hosted CI, or any context where the key could be logged or exfiltrated.
#113	- Production and shared-agent setups must use a managed provider with conservative signing policies (value caps, allowlists, multi-party approval).
#114
#115	## Security model
#116
#117	The agent's environment holds signing credentials, not administrative ones. This is a structural property, and getting it right depends on each provider being configured correctly — none of the four supported providers ship in this state by default.
#118
#119	### What the agent must never do
#120
#121	- Modify its own signing policy, role, or scope.
#122	- Rotate its own owner key, auth key, or API user.
#123	- Export or claim ownership of the wallet's private key.
#124	- Construct any of the requests in `../docs/policy-administration.md`.
#125
#126	If a user asks the agent to do any of these, the agent should refuse and direct them to the user-only recipes in `../docs/policy-administration.md`. A leaked agent env is recoverable only if the credentials it held could not, on their own, lift the spending cap or rewrite the allowlist.
#127
#128	### Per-tx caps: enforced by the provider
#129
#130	Each provider enforces per-tx caps and allowlists in a different layer, but all four are checked before the signing operation completes:
#131
#132	\| Provider \| Where caps are enforced \|
#133	\|---\|---\|
#134	\| Privy \| TEE-evaluated wallet policy (`policy_ids` on the wallet) \|
#135	\| Turnkey \| Policy engine, scoped to the API user's allowed activities \|
#136	\| Fireblocks \| TAP rules in the workspace \|
#137	\| Bankr \| Per-API-key `allowedRecipients` allowlist + daily message limits \|
#138
#139	Run `opensea wallet info` to see whether your wallet has these in place. The command prints loud warnings when the per-tx layer is missing.
#140
#141	### Aggregate caps: not natively enforced by any provider
#142
#143	None of Privy, Turnkey, Fireblocks, or Bankr expose stateful daily/weekly cumulative spend caps as a native primitive. Their policies/TAP/key-flag layers are stateless per-transaction evaluators (or per-message-quota in Bankr's case, which is not a dollar cap).
#144
#145	The intended pattern for aggregate ceilings is wallet float: keep the agent's wallet balance sized to roughly one budget period, and have the user replenish on their own cadence. The wallet balance is the real cap; if the agent tries to overspend, transactions fail at the provider layer (per-tx cap) or chain layer (insufficient funds), not at an honor-system limit the agent could decide to ignore. See `references/wallet-funding.md` for the worked pattern.
#146
#147	(Privy is investigating transaction-approval webhooks that would allow stateful evaluation; if and when those land, the field will support aggregate caps natively. Until then, wallet float is the answer.)
#148
#149	### Policy mutation: requires a separately-held credential
#150
#151	Each provider has a different out-of-band credential that gates mutation:
#152
#153	\| Provider \| Mutation gate \|
#154	\|---\|---\|
#155	\| Privy \| `owner_id` key quorum on the wallet — owner key held off-machine \|
#156	\| Turnkey \| Root user quorum — non-root API user used for signing \|
#157	\| Fireblocks \| Admin quorum for TAP changes; API user role set to `Signer` only \|
#158	\| Bankr \| Dashboard re-scoping at bankr.bot/api — no API to mutate scope \|
#159
#160	Setting these up is part of the happy path in `references/wallet-setup.md`, not optional hardening. `opensea wallet info` reports whether the structural gate is in place where it can be detected via API; for Fireblocks and Bankr, where it cannot, the command prints a static reminder to verify at the console.
#161
#162	### Where mutation recipes live
#163
#164	The actual HTTP/SDK recipes for changing policies, rotating keys, and re-scoping API users are in `../docs/policy-administration.md` — that is, in the skill repo's top-level `docs/` folder, alongside the per-skill folders like `opensea-wallet/`, not inside any of them. Skill loaders only mount individual skill directories (`opensea-wallet/SKILL.md` and the files it explicitly references), so the mutation recipes never enter an agent's context. If a future contributor moves this file inside a skill folder, an agent will read it and try to "help" by running the recipes — defeating the structural separation.
#165
#166	## References
#167
#168	- `references/wallet-setup.md`: detailed setup instructions for each provider, with hardening as part of the happy path
#169	- `references/wallet-policies.md`: policy templates and field reference (no mutation recipes)
#170	- `references/wallet-funding.md`: hot/cold wallet float pattern for aggregate-cap enforcement
#171	- `../docs/policy-administration.md` (in the skill repo's top-level `docs/`, outside any individual skill mount path): user-only mutation recipes for all four providers
#172	- [OpenSea CLI](https://github.com/ProjectOpenSea/opensea-cli)
#173

z6MkqRzA/ProjectOpenSea-opensea-skill