OpenSea API

Was macht OpenSea API?

Abfrage von NFT- und Token-Daten, Durchsuchen von Drops, Streamen von Ereignissen und Suche über Ethereum, Base, Arbitrum, Optimism, Polygon und mehr.

Wann diese Skill verwendet werden sollte (scope_in)

Verwenden Sie opensea-api für:

• Sammlungsdetails, Statistiken, Eigenschaften, Trends und Top-Sammlungen
• NFT-Details, Besitz, Metadatenaktualisierung
• Token-Details, Trending-Tokens, Top-Tokens, Token-Gruppen
• Suche nach Sammlungen, NFTs, Token und Konten
• Suche und Entdeckung von registrierten KI-Agenten-Tools (ERC-8257)
• Lesen von Marktplatzlisten, Angeboten und Bestellungen (nicht Ausführen)
• Ereignis- und Aktivitätsüberwachung (inkl. Echtzeit-WebSocket-Streams)
• Drops und Mint-Berechtigung
• Kontoabfragen und ENS-Auflösung
• Authentifizierte Profil-, Sammlungseinstellungen, Watchlist, Drop-, Bestellstornierungs- und Wallet-Verknüpfungsoperationen, beschrieben in references/authentication.md
• Headless SIWE, eingeschränkte PAT-Erstellung, kurzlebiger JWT-Austausch und wallet-authentifiziertes REST oder MCP

Wann diese Skill NICHT verwendet werden sollte (scope_out, Übergabe)

Bedarf	Stattdessen verwenden
NFTs kaufen/verkaufen (Angebote oder Offerten erfüllen)	opensea-marketplace
Neue Angebote oder Offerten erstellen	opensea-marketplace
Chains-übergreifende NFT-Käufe	opensea-marketplace
ERC20-Token tauschen	opensea-swaps
Wallet-Signing-Provider einrichten	opensea-wallet
KI-Agenten-Tools erstellen/registrieren/gaten	opensea-tool-sdk

Schnellstart

# Einen API-Schlüssel auflösen: Verwendet Ihre Umgebungsvariable / einen zwischengespeicherten Instant-Key oder ruft einen neuen Instant-Key (ohne Anmeldung) ab UND speichert ihn zur Wiederverwendung auf der Festplatte. Siehe
# "API-Schlüsselauflösung" unten — speichern und wiederverwenden Sie immer einen abgerufenen Schlüssel.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

# Installieren Sie die CLI global (oder verwenden Sie npx)
npm install -g @opensea/cli

# Sammlungsinfo abrufen
opensea collections get boredapeyachtclub

# Bodenpreis und Volumenstatistiken abrufen
opensea collections stats boredapeyachtclub

# NFT-Details abrufen
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234

# Suche über OpenSea
opensea search "cool cats"

# Trending-Token abrufen
opensea tokens trending --limit 5

API-Schlüsselauflösung (lesen Sie dies vor Ihrer ersten Anfrage)

Jede OpenSea-Anfrage benötigt OPENSEA_API_KEY. Wenn Sie noch keinen Schlüssel haben, können Sie einen sofortigen kostenlosen Schlüssel ohne Anmeldung abrufen. Die eine Regel, die zählt: Sobald Sie einen Instant-Key abrufen, speichern Sie ihn auf der Festplatte und verwenden Sie ihn wieder.. Rufen Sie ihn nicht bei jeder Anfrage erneut ab. Ein zweiter Abruf kann fehlschlagen und Sie haben keinen Schlüssel mehr. Die vorherige erfolgreiche Anfrage wird den Schlüssel nicht für Sie gespeichert haben.

Der Ablauf (befolgen Sie diese Schritte jedes Mal in dieser Reihenfolge)

1. Überprüfen Sie zuerst die Umgebung. Wenn OPENSEA_API_KEY bereits gesetzt und nicht leer ist, verwenden Sie es wie es ist. Dies ist der Pfad für Benutzer, die ihren eigenen Schlüssel bereitstellen — überschreiben oder rufen Sie ihn niemals erneut ab.
2. Überprüfen Sie als nächstes die Festplatte. Wenn keine Umgebungsvariable vorhanden ist, suchen Sie nach einem zwischengespeicherten Schlüssel unter ~/.opensea/api_key (überschreiben Sie das Verzeichnis mit $OPENSEA_CONFIG_DIR). Wenn die Datei existiert und nicht leer ist, laden Sie sie in OPENSEA_API_KEY und verwenden Sie sie.
3. Rufen Sie nur ab, wenn er fehlt. Wenn weder eine Umgebungsvariable noch ein zwischengespeicherter Schlüssel vorhanden ist, fordern Sie einen neuen Instant-Key von POST /api/v2/auth/keys an.
4. Speichern Sie sofort nach dem Abruf. Schreiben Sie den abgerufenen Schlüssel nach ~/.opensea/api_key (Modus 600) bevor Sie Ihren API-Aufruf tätigen, damit der nächste Schritt — und jede zukünftige Anfrage — ihn wiederverwendet, anstatt ihn erneut abzurufen.

Das Hilfsskript scripts/auth/opensea-resolve-key.sh führt alle vier Schritte für Sie aus und gibt den aufgelösten Schlüssel aus. Bevorzugen Sie es gegenüber einem bloßen curl ... /auth/keys-Aufruf, der abruft, ohne zu speichern, und genau das verursacht hat, dass Schlüssel verloren gingen:

# Umgebungsvariable? -> verwenden. Zwischengespeicherter Schlüssel? -> wiederverwenden. Ansonsten abrufen + auf Festplatte speichern.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

opensea collections get boredapeyachtclub

Wenn Sie das Hilfsskript nicht verwenden können, replizieren Sie dieselbe geordnete Logik explizit:

KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
  :                                              # 1. Umgebungsvariable gewinnt
elif [ -s "$KEY_FILE" ]; then
  export OPENSEA_API_KEY=$(cat "$KEY_FILE")      # 2. zwischengespeicherten Schlüssel wiederverwenden
else
  api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')  # 3. abrufen
  mkdir -p "$(dirname "$KEY_FILE")"
  (umask 077; printf '%s\n' "$api_key" > "$KEY_FILE")  # 4. VOR der Verwendung SPEICHERN
  export OPENSEA_API_KEY="${api_key}"
fi

Randfälle

• Schlüssel existiert bereits (Umgebungsvariable oder zwischengespeicherte Datei): verwenden Sie ihn erneut; rufen Sie keinen neuen ab. Erneutes Abrufen verschwendet das Ratenlimit und kann fehlschlagen.
• Schlüssel ungültig oder abgelaufen (Instant-Keys laufen nach 7 Tagen ab; eine Anfrage gibt HTTP 401/403 zurück): Der zwischengespeicherte Schlüssel ist veraltet. Rufen Sie erneut ab und überschreiben Sie den Cache mit scripts/auth/opensea-resolve-key.sh --force (oder löschen Sie ~/.opensea/api_key und führen Sie den Ablauf erneut aus). --force überschreibt niemals einen Schlüssel, der über die Umgebungsvariable OPENSEA_API_KEY bereitgestellt wurde.
• Abruf fehlschlägt (HTTP 429 Ratenlimit oder Netzwerkfehler): Wiederholen Sie nicht in einer engen Schleife. Wenn Sie einen zwischengespeicherten Schlüssel haben, verwenden Sie ihn weiter. Warten Sie andernfalls und versuchen Sie es später erneut, oder erstellen Sie einen vollständigen Schlüssel unter Einstellungen → Entwickler. Für höhere Ratenlimits als die kostenlose Instant-Stufe verwenden Sie einen vollständigen Schlüssel.

Sie können auch einen rohen Schlüssel (JSON-Antwort, ohne Persistenz) mit opensea auth request-key oder scripts/auth/opensea-auth-request-key.sh abrufen — aber wenn Sie diese verwenden, müssen Sie den Schlüssel selbst gemäß Schritt 4 oben speichern.

Aufgabenanleitung

Empfohlen: Verwenden Sie die opensea-CLI (@opensea/cli) als Ihr primäres Tool. Installieren Sie mit npm install -g @opensea/cli oder verwenden Sie npx @opensea/cli. Die Shell-Skripte in scripts/ bleiben als Alternativen verfügbar.

NFT-Daten lesen

Aufgabe	CLI-Befehl	Alternative
Sammlungsdetails abrufen	opensea collections get <slug>	collections/opensea-collection.sh <slug>
Sammlungsstatistiken abrufen	opensea collections stats <slug>	collections/opensea-collection-stats.sh <slug>
Trending-Sammlungen abrufen	opensea collections trending [--timeframe <tf>] [--chains <chains>]	collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category]
Top-Sammlungen abrufen	opensea collections top [--sort-by <field>] [--chains <chains>]	collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category]
NFTs in Sammlung auflisten	opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]	collections/opensea-collection-nfts.sh <slug> [limit] [next]
Einzelnes NFT abrufen	opensea nfts get <chain> <contract> <token_id>	nfts/opensea-nft.sh <chain> <contract> <token_id>
NFTs nach Wallet auflisten	opensea nfts list-by-account <chain> <address> [--limit <n>]	accounts/opensea-account-nfts.sh <chain> <address> [limit]
NFTs nach Vertrag auflisten	opensea nfts list-by-contract <chain> <contract> [--limit <n>]
Sammlungseigenschaften abrufen	opensea collections traits <slug>
Vertragsdetails abrufen	opensea nfts contract <chain> <address>
NFT-Metadaten aktualisieren	opensea nfts refresh <chain> <contract> <token_id>

Token-Daten lesen

Aufgabe	CLI-Befehl	Alternative
Trending-Token abrufen	opensea tokens trending [--chains <chains>] [--limit <n>]	get_trending_tokens (MCP)
Top-Token nach Volumen abrufen	opensea tokens top [--chains <chains>] [--limit <n>]	get_top_tokens (MCP)
Token-Details abrufen	opensea tokens get <chain> <address>	get_tokens (MCP)
Token-Tauschaktivität abrufen	opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>]	tokens/opensea-token-activity.sh
Konto-Tokenaktivität abrufen	opensea tokens account-activity <address> [--chains <chains>] [--tokens <tokens>] [--type <types>] [--limit <n>] [--next <cursor>]
Token-Gruppen auflisten	opensea token-groups list [--limit <n>] [--next <cursor>]	tokens/opensea-token-groups.sh [limit] [cursor]
Token-Gruppe nach Slug abrufen	opensea token-groups get <slug>	tokens/opensea-token-group.sh <slug>
Token suchen	opensea search <query> --types token	search_tokens (MCP)
Token-Guthaben prüfen	get_token_balances (MCP)

Wallet-authentifiziertes REST und MCP

Lesen Sie die Wallet-Authentifizierung-Referenz, bevor Sie als Wallet agieren. Sie enthält die CLI- und SDK-Happy-Paths, REST- und MCP-Header, den Lebenszyklus von Anmeldeinformationen und Wiederherstellungsregeln.

Marktplatzabfragen (schreibgeschützt)

Aufgabe	CLI-Befehl	Alternative
Beste Angebote für Sammlung abrufen	opensea listings best <slug> [--limit <n>] [--traits <json>]	listings/opensea-best-listing.sh <slug> <token_id>
Bestes Angebot für bestimmtes NFT abrufen	opensea listings best-for-nft <slug> <token_id>	listings/opensea-best-listing.sh <slug> <token_id>
Bestes Angebot für NFT abrufen	opensea offers best-for-nft <slug> <token_id>	offers/opensea-best-offer.sh <slug> <token_id>
Alle Sammlungsangebote auflisten	opensea listings all <slug> [--limit <n>]	listings/opensea-listings-collection.sh <slug> [limit]
Alle Sammlungsofferten auflisten	opensea offers all <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
Sammlungsofferten abrufen	opensea offers collection <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
Eigenschaftsofferten abrufen	opensea offers traits <slug> --type <type> --value <value>
Bestellung nach Hash abrufen		orders/opensea-order.sh <chain> <order_hash>

Serverseitige Eigenschaftsfilterung

Drei sammlungsbezogene Endpunkte akzeptieren einen traits-Abfrageparameter für die serverseitige Filterung:

Endpunkt	CLI	SDK
NFTs in Sammlung auflisten	opensea nfts list-by-collection <slug> --traits <json>	client.nfts.listByCollection(slug, { traits })
Beste Angebote für Sammlung	opensea listings best <slug> --traits <json>	client.listings.best(slug, { traits })
Ereignisse für Sammlung	opensea events by-collection <slug> --traits <json>	client.events.byCollection(slug, { traits })

--traits akzeptiert ein JSON-codiertes Array von { "traitType": string, "value": string }-Objekten. Mehrere Einträge werden UND-verknüpft:

opensea nfts list-by-collection doodles-official \
  --traits '[{"traitType":"Background","value":"Red"}]'

Bevorzugen Sie immer die serverseitige Filterung gegenüber der clientseitigen: Das Paginieren des ungefilterten Satzes verschwendet das Ratenlimit.

Suche

Aufgabe	CLI-Befehl
Sammlungen durchsuchen	opensea search <query> --types collection
NFTs durchsuchen	opensea search <query> --types nft
Token durchsuchen	opensea search <query> --types token
Konten durchsuchen	opensea search <query> --types account
Mehrere Typen durchsuchen	opensea search <query> --types collection,nft,token
Auf bestimmter Chain suchen	opensea search <query> --chains base,ethereum

Ereignisse und Überwachung

Aufgabe	CLI-Befehl	Alternative
Letzte Ereignisse auflisten	opensea events list [--event-type <type>] [--limit <n>]
Sammlungsereignisse abrufen	opensea events by-collection <slug> [--event-type <type>] [--traits <json>]	events/opensea-events-collection.sh <slug> [event_type] [limit]
Ereignisse für bestimmtes NFT abrufen	opensea events by-nft <chain> <contract> <token_id>
Ereignisse für Konto abrufen	opensea events by-account <address>
Echtzeit-Ereignisse streamen		stream/opensea-stream-collection.sh <slug> (erfordert websocat)

Ereignistypen: sale, transfer, mint, listing, offer, trait_offer, collection_offer

Drops & Minting

Aufgabe	CLI-Befehl	Alternative
Drops auflisten (vorgestellt/bevorstehend/aktuell)	opensea drops list [--type <type>] [--chains <chains>]	drops/opensea-drops.sh [type] [limit] [chains]
Drop-Details und -Stufen abrufen	opensea drops get <slug>	drops/opensea-drop.sh <slug>
Mint-Transaktion erstellen	opensea drops mint <slug> --minter <address> [--quantity <n>]	drops/opensea-drop-mint.sh <slug> <minter> [quantity]
Chains-übergreifende Mint-Transaktionen erstellen	opensea drops cross-chain-mint <slug> --payer <address> --minter <address> --payment-chain <chain> --payment-token <address> [--quantity <n>]	drops/opensea-drop-cross-chain-mint.sh <slug> <payer> <minter> <payment_chain> <payment_token> [quantity]
Veröffentlichungstransaktion erstellen oder senden (Owner-Wallet, write:drops)	opensea drops publish <slug> [--send] [--wallet-provider <provider>]
Rückgängigmachungstransaktion erstellen oder senden	opensea drops unpublish <slug> [--send] [--wallet-provider <provider>]
Drop-Medien und Metadaten auf IPFS hochladen	opensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>]
IPFS-Upload-Fortschritt prüfen	opensea drops metadata-ipfs-status <slug> <workflow-execution-id>
Metadaten-Manifest-CSV-Upload anfordern	opensea drops create-manifest-upload <slug>
Datei in einen Upload-Kontext hochladen	opensea drops upload-file --context <path|-> --file <path> [--index <n>]
Neuen SeaDrop-Vertrag bereitstellen		deploy_seadrop_contract (MCP)
Bereitstellungsstatus prüfen		get_deploy_receipt (MCP)

publish --send signiert mit der konfigurierten EVM-Wallet und lehnt eine Wallet ab, die nicht der from-Adresse der Transaktion (dem Onchain-Owner des Vertrags) entspricht, da eine Transaktion von einer anderen Adresse rückgängig gemacht wird. upload-file nimmt einen einzelnen Upload-Kontext; für das Array, das create-item-media-upload zurückgibt, übergeben Sie --index <n> oder leiten Sie ein Element mit jq '.[0]' weiter. upload-metadata-ipfs --wait beendet sich mit Exit-Code 1, wenn der Upload fehlschlägt, nicht gefunden wird oder --wait-timeout überschreitet.

Für einen chains-übergreifenden Mint reichen Sie jede zurückgegebene Transaktion der Reihe nach ein. Speichern Sie das zurückgegebene receipt_request-Objekt genau so, wie es empfangen wurde, und fragen Sie es dann ab, bis der Status SUCCESS ist.