Opensea MarketplaceSAFE

Bankr Skills equip builders with plug-and-play tools to build more powerful agents.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: opensea-marketplace
description: Buy and sell NFTs on OpenSea's Seaport marketplace. Fulfill listings, accept offers, create new orders, cross-chain purchases, and sweep multiple listings. Requires wallet signing; for read-only queries use opensea-api instead.
homepage: https://github.com/ProjectOpenSea/opensea-skill
repository: https://github.com/ProjectOpenSea/opensea-skill
license: MIT
env:
  OPENSEA_API_KEY:
    description: API key for all OpenSea services
    required: true
    obtain: https://docs.opensea.io/reference/api-keys#instant-api-key-for-agents
dependencies:
  - node >= 18.0.0
  - curl
  - jq (recommended)
---

<!-- Wallet provider env vars (Privy/Turnkey/Fireblocks/Bankr/PRIVATE_KEY) are documented in the opensea-wallet skill. -->


# OpenSea Marketplace

Buy and sell NFTs on OpenSea's Seaport marketplace. Fulfill listings, accept offers, create new orders, cross-chain purchases, and sweep multiple listings.

## When to use this skill (`scope_in`)

Use `opensea-marketplace` when you need to **execute trades**:

- Buy an NFT (fulfill a listing)
- Sell an NFT (accept an offer)
- Create a new Seaport listing or offer
- Cross-chain NFT purchases (pay with tokens from a different chain)
- Sweep multiple listings in one transaction

## When NOT to use this skill (`scope_out`, handoff)

| Need | Use instead |
|---|---|
| Query collection/NFT data, search, browse listings | `opensea-api` |
| Swap ERC20 tokens | `opensea-swaps` |
| Set up wallet signing providers | `opensea-wallet` |
| Build/register/gate AI agent tools | `opensea-tool-sdk` |

## Buying an NFT

1. Find the NFT and check its listing (use `opensea-api` skill):
   ```bash
   opensea listings best-for-nft cool-cats-nft 1234
   ```

2. Get the order hash from the response, then get fulfillment data:
   ```bash
   ./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet
   ```

3. The response contains transaction data to execute onchain.

## Selling an NFT (accepting an offer)

1. Check offers on your NFT (use `opensea-api` skill):
   ```bash
   opensea offers best-for-nft cool-cats-nft 1234
   ```

2. Get fulfillment data for the offer:
   ```bash
   ./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234
   ```

3. Execute the returned transaction data.

## Cross-chain buying

Buy NFTs using tokens from a different chain (e.g., USDC on Base to buy an ETH mainnet NFT). Also supports same-chain different-token purchases and sweeping up to 50 listings.

1. Find the NFT and check its listing:
   ```bash
   opensea listings best-for-nft cool-cats-nft 1234
   ```

2. Get cross-chain fulfillment data:
   ```bash
   ./scripts/opensea-cross-chain-fulfill.sh 0xYourWallet base 0x0000000000000000000000000000000000000000 ethereum 0x0000000000000068f116a894984e2db1123eb395 0xOrderHash
   ```

3. The response contains an ordered list of transactions to sign and submit (first may be an ERC20 approval).

**Sweep multiple listings:**
```bash
./scripts/opensea-cross-chain-fulfill.sh 0xYourWallet base 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 ethereum 0x0000000000000068f116a894984e2db1123eb395 0xHash1 0xHash2 0xHash3
```

**CLI alternative:**
```bash
opensea listings cross-chain-fulfill \
  --hashes 0xHash1,0xHash2 \
  --listing-chain ethereum \
  --protocol-address 0x0000000000000068f116a894984e2db1123eb395 \
  --fulfiller 0xYourWallet \
  --payment-chain base \
  --payment-token 0x0000000000000000000000000000000000000000
```

## Creating listings/offers

Creating new listings and offers requires wallet signatures. Use `../opensea-api/scripts/opensea-post.sh` with the Seaport order structure (see `references/marketplace-api.md` for full details).

## Marketplace action scripts

| Task | Script |
|------|--------|
| Get fulfillment data (buy NFT) | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |
| Get cross-chain fulfillment data | `opensea-cross-chain-fulfill.sh [--recipient <addr>] <fulfiller> <payment_chain> <payment_token> <listing_chain> <protocol_address> <hash1> [hash2 ...]` |
| Get fulfillment data (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |
| Generic POST request | `../opensea-api/scripts/opensea-post.sh <path> <json_body>` |

## Signing transactions

All transaction signing uses managed wallet providers through the `WalletAdapter` interface. See the [`opensea-wallet`](../opensea-wallet/SKILL.md) skill for supported providers, env vars, setup walkthroughs, and signing-policy configuration. The CLI auto-detects which provider to use based on environment variables, or you can specify one explicitly with `--wallet-provider`.

## References

- `references/marketplace-api.md`: buy/sell workflows and Seaport details
- `references/seaport.md`: Seaport protocol and NFT purchase execution
- [OpenSea CLI](https://github.com/ProjectOpenSea/opensea-cli)
- [Developer docs](https://docs.opensea.io/)

## Error handling

Marketplace operations involve onchain transactions. Always check for errors before signing.

### Fulfillment errors

| HTTP Status | Meaning | Recommended Action |
|---|---|---|
| 400 | Bad Request (invalid order hash, wrong chain, missing params) | Verify the order hash and chain match the listing/offer |
| 401 | Unauthorized | Verify `OPENSEA_API_KEY` is set and valid |
| 404 | Order not found or already fulfilled | Re-query listings/offers to find a current order |
| 429 | Rate Limited | Wait 60 seconds, then retry with exponential backoff |
| 500 | Server Error | Retry up to 3 times with exponential backoff (2s, 4s, 8s) |

### CLI exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | API error (check stderr for details) |
| 2 | Authentication error (missing or invalid API key / wallet credentials) |

### Transaction safety

- **Always verify fulfillment data before signing.** Check that the returned `to` address, `value`, and `data` fields look correct.
- **Check order exp

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.