Skip to content

fix(opensea): persist API key across agent sessions #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CodySearsOS wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix(opensea): persist API key across agent sessions #133

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 53 additions & 18 deletions skills/base-mcp/plugins/opensea.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,56 @@ OpenSea is an NFT marketplace and token trading platform. This plugin covers thr

All OpenSea API endpoints require an `x-api-key` header. **This is the first step before using any tool.**

### Instant API key for agents
### API key resolution (always run this sequence)

Create a free-tier API key instantly with a single call — no signup, no wallet, no human needed:
You can create a free-tier API key instantly — no signup, no wallet, no human needed. However, instant key creation is **rate-limited to 3 per hour per IP**, so you must **save and reuse** a key once you have one. How you do this depends on your environment.

#### Environments with filesystem access (Cursor, Claude Code, Codex, Windsurf, terminal agents)

These environments can persist a key to disk so it survives across chat sessions. **Follow this sequence every time**, in order:

1. **Check the environment.** If `OPENSEA_API_KEY` is already set and non-empty, use it as-is. User-supplied keys always win — never overwrite or re-fetch.
2. **Check disk.** Look for a cached key at `${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key`. If the file exists and is non-empty, load it into `OPENSEA_API_KEY`.
3. **Fetch only if missing.** If neither env var nor cached file exists, request a new instant key via `POST /api/v2/auth/keys`.
4. **Save immediately after fetching.** Write the key to `~/.opensea/api_key` (mode `600`) *before* making any API call, so every future session reuses it instead of re-fetching.

```bash
KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
: # 1. env var wins
elif [ -s "$KEY_FILE" ]; then
export OPENSEA_API_KEY=$(cat "$KEY_FILE") # 2. reuse cached key
else
api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key') # 3. fetch
mkdir -p "$(dirname "$KEY_FILE")"
(umask 077; printf '%s\n' "$api_key" > "$KEY_FILE") # 4. save before using
export OPENSEA_API_KEY="$api_key"
fi
```

**Expired or invalid key** — if a request returns HTTP `401` or `403`, the cached key is stale (instant keys expire after 30 days). Delete it and re-run the sequence:

```bash
rm -f "${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
unset OPENSEA_API_KEY
# Re-run the resolution sequence above
```

#### Chat-only surfaces (Claude.ai, ChatGPT, or any environment without filesystem access)

These environments cannot persist to disk. Create a key per session:

```bash
export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')
```

Response shape:
Or set an existing key:

```bash
export OPENSEA_API_KEY="your-api-key"
```

### Key creation response shape

```json
{
Expand All @@ -54,7 +95,7 @@ Use the returned key in the `X-API-KEY` header on all subsequent requests.

**Limits:**

- 3 key creations per hour per IP
- 3 key creations per hour per IP — reuse your key to stay within this limit
- 60 requests/min for read endpoints
- 5 requests/min for write endpoints
- 5 requests/min for fulfillment endpoints
Expand All @@ -64,12 +105,6 @@ To upgrade to higher rate limits, visit <https://opensea.io/settings/developer>.

Full documentation: <https://docs.opensea.io/reference/api-keys#instant-api-key-for-agents>

Or set an existing key:

```bash
export OPENSEA_API_KEY="your-api-key"
```

The CLI reads `OPENSEA_API_KEY` from the environment automatically.

## Detection
Expand Down Expand Up @@ -333,7 +368,7 @@ In Python: `hex(20000000000000000)` outputs `"0x470de4df820000"`

```
1. get_wallets → address
2. Create API key if not already set (POST /api/v2/auth/keys)
2. Resolve API key (see Auth → API key resolution sequence)
3. opensea swaps quote --from-chain <chain> --from-address <from> \
--to-chain <chain> --to-address <to> \
--quantity <amount> --address <address>
Expand All @@ -349,7 +384,7 @@ In Python: `hex(20000000000000000)` outputs `"0x470de4df820000"`

```
1. get_wallets → address
2. Create API key if not already set (POST /api/v2/auth/keys)
2. Resolve API key (see Auth → API key resolution sequence)
3. opensea drops list --chains <chains> --type upcoming
(or GET /api/v2/drops?type=upcoming&chains=<chains>)
4. opensea drops get <slug> → check eligibility, pricing, supply
Expand All @@ -366,7 +401,7 @@ In Python: `hex(20000000000000000)` outputs `"0x470de4df820000"`

```
1. get_wallets → address
2. Create API key if not already set (POST /api/v2/auth/keys)
2. Resolve API key (see Auth → API key resolution sequence)
3. opensea search "<query>" --types collection → find collection
(or GET /api/v2/search?query=<query>&type=collections)
4. opensea listings best-for-nft <slug> <token_id> → get order_hash, price
Expand All @@ -385,7 +420,7 @@ In Python: `hex(20000000000000000)` outputs `"0x470de4df820000"`

```
1. get_wallets → address
2. Create API key if not already set (POST /api/v2/auth/keys)
2. Resolve API key (see Auth → API key resolution sequence)
3. opensea offers best-for-nft <slug> <token_id> → get offer_hash, price
4. Confirm acceptance with user
5. Use CLI to handle fulfillment (CLI encodes Seaport calldata internally)
Expand Down Expand Up @@ -449,7 +484,7 @@ See [../references/batch-calls.md](../references/batch-calls.md) and [../referen
```
Swap 0.02 ETH for USDC on Base
```
1. Create API key via `POST /api/v2/auth/keys` (if not already set).
1. Resolve API key (see Auth → API key resolution sequence).
2. Get wallet address via `get_wallets`.
3. Run `opensea swaps quote --from-chain base --from-address 0x0000000000000000000000000000000000000000 --to-chain base --to-address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --quantity 0.02 --address <address>` (or GET `/api/v2/swap/quote` with `quantity=20000000000000000`).
4. Review quote with user (price impact, fees).
Expand All @@ -458,7 +493,7 @@ Swap 0.02 ETH for USDC on Base
```
Buy a Bored Ape on Ethereum
```
1. Create API key via `POST /api/v2/auth/keys` (if not already set).
1. Resolve API key (see Auth → API key resolution sequence).
2. Get wallet address via `get_wallets`.
3. Run `opensea listings best boredapeyachtclub --limit 5` to show cheapest listings.
4. User picks one; extract `order_hash`.
Expand All @@ -468,15 +503,15 @@ Buy a Bored Ape on Ethereum
```
What drops are coming up on Base?
```
1. Create API key via `POST /api/v2/auth/keys` (if not already set).
1. Resolve API key (see Auth → API key resolution sequence).
2. Run `opensea drops list --chains base --type upcoming` (or GET `/api/v2/drops?type=upcoming&chains=base`).
3. Present results. If user wants to mint, run `opensea drops mint <slug> --minter <address>` (or POST to `/api/v2/drops/{slug}/mint`).
4. Map response directly to `send_calls` (mint value is already hex).

```
Buy an NFT on Ethereum using USDC from Base
```
1. Create API key via `POST /api/v2/auth/keys` (if not already set).
1. Resolve API key (see Auth → API key resolution sequence).
2. Get wallet address via `get_wallets`.
3. Find the listing: `opensea listings best-for-nft <slug> <token_id>`.
4. Confirm price and payment token with user.
Expand Down