OpenSea API

API OpenSea

Interrogez les données des NFT et des tokens, parcourez les drops, diffusez les événements en direct, et effectuez des recherches sur Ethereum, Base, Arbitrum, Optimism, Polygon, et bien d'autres.

Quand utiliser cette compétence (scope_in)

Utilisez opensea-api pour :

• Détails, statistiques, attributs (traits), tendances et meilleures collections
• Détails des NFT, propriété, actualisation des métadonnées
• Détails des tokens, tokens tendances, meilleurs tokens, groupes de tokens
• Recherche parmi les collections, NFT, tokens et comptes
• Recherche et découverte d'outils d'agent IA enregistrés (ERC-8257)
• Consultation des annonces, offres et commandes de la place de marché (sans exécution)
• Suivi des événements et de l'activité (y compris les flux WebSocket en temps réel)
• Drops (lancements) et éligibilité au minting
• Recherche de comptes et résolution ENS
• Paramètres de profil authentifié, paramètres de collection, liste de surveillance, drop, annulation de commande, et opérations de liaison de portefeuille décrites dans references/authentication.md
• Vérification d'identité via SIWE, création de PAT (jetons d'accès personnels) restreints, échange de JWT de courte durée, et utilisation de REST ou MCP avec authentification par portefeuille

Quand NE PAS utiliser cette compétence (scope_out, transfert)

Besoin	Utilisez plutôt
Acheter/vendre des NFT (exécuter des annonces ou des offres)	opensea-marketplace
Créer de nouvelles annonces ou offres	opensea-marketplace
Achats de NFT跨-chaînes	opensea-marketplace
Échanger des tokens ERC20	opensea-swaps
Configurer des fournisseurs de signature pour portefeuille	opensea-wallet
Construire/enregistrer/restreindre des outils d'agent IA	opensea-tool-sdk

Démarrage rapide

# Résoudre une clé API : réutilise votre variable d'env / une clé instantanée mise en cache,
# ou récupère une nouvelle clé instantanée (sans inscription) ET la sauvegarde sur le disque
# pour la réutiliser. Voir "Résolution de clé API" ci-dessous — sauvegardez toujours et
# réutilisez une clé récupérée.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

# Installer la CLI globalement (ou utiliser npx)
npm install -g @opensea/cli

# Obtenir les informations d'une collection
opensea collections get boredapeyachtclub

# Obtenir le prix plancher et les statistiques de volume
opensea collections stats boredapeyachtclub

# Obtenir les détails d'un NFT
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234

# Rechercher sur OpenSea
opensea search "cool cats"

# Obtenir les tokens tendances
opensea tokens trending --limit 5

Résolution de clé API (lire ceci avant votre première requête)

Chaque requête OpenSea nécessite OPENSEA_API_KEY. Si vous n'avez pas encore de clé, vous pouvez récupérer une clé instantanée gratuite sans inscription. La seule règle importante : une fois que vous avez récupéré une clé instantanée, sauvegardez-la sur le disque et réutilisez-la. Ne la récupérez pas à chaque requête. Une seconde récupération peut échouer et vous laisser sans clé. La requête précédente réussie n'aura pas persisté la clé pour vous.

Le flux (suivez ces étapes dans l'ordre, à chaque fois)

1. Vérifiez d'abord l'environnement. Si OPENSEA_API_KEY est déjà définie et non vide, utilisez-la telle quelle. C'est le cas pour les utilisateurs qui fournissent leur propre clé — ne l'écrasez jamais et ne la récupérez pas à nouveau.
2. Vérifiez ensuite le disque. Si aucune variable d'env, cherchez une clé mise en cache dans ~/.opensea/api_key (remplacez le répertoire avec $OPENSEA_CONFIG_DIR). Si le fichier existe et n'est pas vide, chargez-le dans OPENSEA_API_KEY et utilisez-le.
3. Récupérez seulement si elle est manquante. S'il n'y a ni variable d'env ni clé mise en cache, demandez une nouvelle clé instantanée via POST /api/v2/auth/keys.
4. Sauvegardez immédiatement après la récupération. Écrivez la clé récupérée dans ~/.opensea/api_key (mode 600) avant d'effectuer votre appel API, afin que la prochaine étape — et toutes les requêtes futures — la réutilisent au lieu de la récupérer à nouveau.

Le script d'aide scripts/auth/opensea-resolve-key.sh effectue les quatre étapes pour vous et affiche la clé résolue. Préférez-le à un appel curl ... /auth/keys nu, qui récupère sans sauvegarder et c'est exactement ce qui a causé la perte de clés :

# variable d'env ? -> utilisez-la. clé mise en cache ? -> réutilisez-la. sinon récupérez + sauvegardez sur le disque.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

opensea collections get boredapeyachtclub

Si vous ne pouvez pas utiliser le script d'aide, reproduisez la même logique ordonnée explicitement :

KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
  :                                              # 1. la variable d'env l'emporte
elif [ -s "$KEY_FILE" ]; then
  export OPENSEA_API_KEY=$(cat "$KEY_FILE")      # 2. réutiliser la clé mise en cache
else
  api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')  # 3. récupérer
  mkdir -p "$(dirname "$KEY_FILE")"
  (umask 077; printf '%s\n' "$api_key" > "$KEY_FILE")  # 4. SAUVEGARDER avant d'utiliser
  export OPENSEA_API_KEY="${api_key}"
fi

Cas particuliers

• Clé déjà existante (variable d'env ou fichier mis en cache) : réutilisez-la ; ne récupérez pas une nouvelle clé. La récupération répétée gaspille la limite de taux et peut échouer.
• Clé invalide ou expirée (les clés instantanées expirent après 7 jours ; une requête renvoie HTTP 401/403) : la clé mise en cache est obsolète. Récupérez-en une nouvelle et écrasez le cache avec scripts/auth/opensea-resolve-key.sh --force (ou supprimez ~/.opensea/api_key et relancez le flux). --force n'écrase jamais une clé fournie via la variable d'environnement OPENSEA_API_KEY.
• La récupération échoue (limite de taux HTTP 429, ou erreur réseau) : ne réessayez pas en boucle serrée. Si vous avez une clé mise en cache, continuez à l'utiliser. Sinon, attendez et réessayez plus tard, ou créez une clé complète sur Settings → Developer. Pour des limites de taux plus élevées que le niveau gratuit instantané, utilisez une clé complète.

Vous pouvez aussi récupérer une clé brute (réponse JSON, sans persistance) avec opensea auth request-key ou scripts/auth/opensea-auth-request-key.sh — mais si vous les utilisez, vous devez sauvegarder la clé vous-même selon l'étape 4 ci-dessus.

Guide des tâches

Recommandation : Utilisez la CLI opensea (@opensea/cli) comme outil principal. Installez-la avec npm install -g @opensea/cli ou utilisez npx @opensea/cli. Les scripts shell dans scripts/ restent disponibles comme alternatives.

Lecture des données NFT

Tâche	Commande CLI	Alternative
Obtenir les détails d'une collection	opensea collections get <slug>	collections/opensea-collection.sh <slug>
Obtenir les statistiques d'une collection	opensea collections stats <slug>	collections/opensea-collection-stats.sh <slug>
Obtenir les collections tendances	opensea collections trending [--timeframe <tf>] [--chains <chains>]	collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category]
Obtenir les meilleures collections	opensea collections top [--sort-by <field>] [--chains <chains>]	collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category]
Lister les NFT d'une collection	opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]	collections/opensea-collection-nfts.sh <slug> [limit] [next]
Obtenir un NFT individuel	opensea nfts get <chain> <contract> <token_id>	nfts/opensea-nft.sh <chain> <contract> <token_id>
Lister les NFT par portefeuille	opensea nfts list-by-account <chain> <address> [--limit <n>]	accounts/opensea-account-nfts.sh <chain> <address> [limit]
Lister les NFT par contrat	opensea nfts list-by-contract <chain> <contract> [--limit <n>]
Obtenir les attributs (traits) d'une collection	opensea collections traits <slug>
Obtenir les détails d'un contrat	opensea nfts contract <chain> <address>
Actualiser les métadonnées d'un NFT	opensea nfts refresh <chain> <contract> <token_id>

Lecture des données de tokens

Tâche	Commande CLI	Alternative
Obtenir les tokens tendances	opensea tokens trending [--chains <chains>] [--limit <n>]	get_trending_tokens (MCP)
Obtenir les meilleurs tokens par volume	opensea tokens top [--chains <chains>] [--limit <n>]	get_top_tokens (MCP)
Obtenir les détails d'un token	opensea tokens get <chain> <address>	get_tokens (MCP)
Obtenir l'activité d'échange d'un token	opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>]	tokens/opensea-token-activity.sh
Obtenir l'activité d'un token pour un compte	opensea tokens account-activity <address> [--chains <chains>] [--tokens <tokens>] [--type <types>] [--limit <n>] [--next <cursor>]
Lister les groupes de tokens	opensea token-groups list [--limit <n>] [--next <cursor>]	tokens/opensea-token-groups.sh [limit] [cursor]
Obtenir un groupe de token par slug	opensea token-groups get <slug>	tokens/opensea-token-group.sh <slug>
Rechercher des tokens	opensea search <query> --types token	search_tokens (MCP)
Vérifier les soldes de tokens	get_token_balances (MCP)

REST et MCP avec authentification par portefeuille

Lisez la référence sur l'authentification par portefeuille avant d'agir en tant que portefeuille. Elle contient les chemins optimaux (happy paths) via CLI et SDK, les en-têtes REST et MCP, le cycle de vie des identifiants, et les règles de récupération.

Requêtes sur la place de marché (lecture seule)

Tâche	Commande CLI	Alternative
Obtenir les meilleures annonces pour une collection	opensea listings best <slug> [--limit <n>] [--traits <json>]	listings/opensea-best-listing.sh <slug> <token_id>
Obtenir la meilleure annonce pour un NFT spécifique	opensea listings best-for-nft <slug> <token_id>	listings/opensea-best-listing.sh <slug> <token_id>
Obtenir la meilleure offre pour un NFT	opensea offers best-for-nft <slug> <token_id>	offers/opensea-best-offer.sh <slug> <token_id>
Lister toutes les annonces d'une collection	opensea listings all <slug> [--limit <n>]	listings/opensea-listings-collection.sh <slug> [limit]
Lister toutes les offres d'une collection	opensea offers all <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
Obtenir les offres pour une collection	opensea offers collection <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
Obtenir les offres pour un attribut	opensea offers traits <slug> --type <type> --value <value>
Obtenir une commande par son hash		orders/opensea-order.sh <chain> <order_hash>

Filtrage côté serveur par attributs

Trois endpoints dédiés à une collection acceptent un paramètre de requête traits pour le filtrage côté serveur :

Endpoint	CLI	SDK
Lister les NFT d'une collection	opensea nfts list-by-collection <slug> --traits <json>	client.nfts.listByCollection(slug, { traits })
Meilleures annonces pour une collection	opensea listings best <slug> --traits <json>	client.listings.best(slug, { traits })
Événements pour une collection	opensea events by-collection <slug> --traits <json>	client.events.byCollection(slug, { traits })

--traits prend un tableau encodé en JSON d'objets { "traitType": string, "value": string }. Les entrées multiples sont combinées avec un ET logique :

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

Privilégiez toujours le filtrage côté serveur au filtrage côté client : paginer un ensemble non filtré gaspille le budget de limite de taux.

Recherche

Tâche	Commande CLI
Rechercher des collections	opensea search <query> --types collection
Rechercher des NFT	opensea search <query> --types nft
Rechercher des tokens	opensea search <query> --types token
Rechercher des comptes	opensea search <query> --types account
Rechercher plusieurs types	opensea search <query> --types collection,nft,token
Rechercher sur une chaîne spécifique	opensea search <query> --chains base,ethereum

Événements et surveillance

Tâche	Commande CLI	Alternative
Lister les événements récents	opensea events list [--event-type <type>] [--limit <n>]
Obtenir les événements d'une collection	opensea events by-collection <slug> [--event-type <type>] [--traits <json>]	events/opensea-events-collection.sh <slug> [event_type] [limit]
Obtenir les événements pour un NFT spécifique	opensea events by-nft <chain> <contract> <token_id>
Obtenir les événements pour un compte	opensea events by-account <address>
Diffuser les événements en temps réel		stream/opensea-stream-collection.sh <slug> (nécessite websocat)

Types d'événements : sale (vente), transfer (transfert), mint (création), listing (annonce), offer (offre), trait_offer (offre sur attribut), collection_offer (offre sur collection)

Drops et minting

Tâche	Commande CLI	Alternative
Lister les drops (en vedette/à venir/récents)	opensea drops list [--type <type>] [--chains <chains>]	drops/opensea-drops.sh [type] [limit] [chains]
Obtenir les détails et étapes d'un drop	opensea drops get <slug>	drops/opensea-drop.sh <slug>
Construire une transaction de mint	opensea drops mint <slug> --minter <address> [--quantity <n>]	drops/opensea-drop-mint.sh <slug> <minter> [quantity]
Construire des transactions de mint跨-chaînes	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]
Construire ou envoyer la transaction de publication (portefeuille propriétaire, write:drops)	opensea drops publish <slug> [--send] [--wallet-provider <provider>]
Construire ou envoyer la transaction de dépublication	opensea drops unpublish <slug> [--send] [--wallet-provider <provider>]
Télécharger les médias et métadonnées d'un drop vers IPFS	opensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>]
Vérifier la progression du téléchargement IPFS	opensea drops metadata-ipfs-status <slug> <workflow-execution-id>
Demander un téléchargement CSV (manifeste des métadonnées)	opensea drops create-manifest-upload <slug>
Télécharger un fichier dans un contexte de téléchargement	opensea drops upload-file --context <path|-> --file <path> [--index <n>]
Déployer un nouveau contrat SeaDrop		deploy_seadrop_contract (MCP)
Vérifier l'état du déploiement		get_deploy_receipt (MCP)

publish --send signe avec le portefeuille EVM configuré et refuse tout portefeuille qui n'est pas le from de la transaction (le propriétaire on-chain du contrat), car une transaction provenant d'une autre adresse est annulée. upload-file prend un seul contexte de téléchargement ; pour le tableau renvoyé par create-item-media-upload, passez --index <n> ou pipez un élément avec jq '.[0]'. upload-metadata-ipfs --wait se termine avec le code 1 lorsque le téléchargement échoue, n'est pas trouvé, ou dépasse --wait-timeout.

Pour un mint跨-chaîne, soumettez chaque transaction renvoyée dans l'ordre. Sauvegardez l'objet receipt_request renvoyé exactement tel que reçu, puis interrogez-le jusqu'à ce que le statut soit SUCCES (succès).

upload-file exige un contexte unique. Quatre workflows renvoient un tableau de contextes de téléchargement :

Workflow	Endpoint CLI	Action
Création d'un élément de drop	opensea drops upload-file --context <(opensea drops create-item-media-upload <slug> | jq '.[0]') --file my-image.jpg	create-item-media-upload sur un slug de drop, avec tous les détails saisis
Téléchargement en masse d'images de drop	opensea drops upload-file --context <(opensea drops bulk-image-upload <slug> | jq '.[0]') --file my-bulk-image.zip	create-bulk-image-upload
Téléchargement de bannière de collection	opensea drops upload-file --context <(opensea drops upload-collection-banner <slug> | jq '.[0]') --file my-banner.png	collection-upload-banner
Attributs et métadonnées d'une collection de drop	opensea drops set-collection-metadata --file my-attributes.csv --context <(opensea drops upload-collection-attributes <slug> | jq '.[0]')	collection-upload-attributes

Outils MCP

Ces outils MCP exposent une partie de la fonctionnalité de l'API via le Model Context Protocol.

Outil	Description	Commandes associées
get_nfts	Obtenir les NFT par collection, portefeuille ou contrat	Voir la section NFT ci-dessus
get_nft	Obtenir un NFT individuel	opensea nfts get <chain> <contract> <token_id>
get_collection	Obtenir les détails et les statistiques d'une collection	opensea collections get <slug>, opensea collections stats <slug>
get_trending_collections	Collections tendances avec volume, changement de prix et plancher	opensea collections trending
get_top_collections	Meilleures collections triées par métrique	opensea collections top
search_nfts	Rechercher des NFT par mot-clé	opensea search <query> --types nft
search_collections	Rechercher des collections par mot-clé	opensea search <query> --types collection
search_tokens	Rechercher des tokens par mot-clé	opensea search <query> --types token
get_trending_tokens	Obtenir les tokens tendances	opensea tokens trending
get_top_tokens	Obtenir les meilleurs tokens par volume	opensea tokens top
get_tokens	Obtenir les détails d'un token	opensea tokens get <chain> <address>
get_token_balances	Obtenir les soldes de tokens pour un compte
get_events	Obtenir les événements pour une collection ou un NFT	Voir la section Événements ci-dessus
get_drops	Obtenir les drops (lancements)	opensea drops list
get_drop	Obtenir les détails d'un drop spécifique	opensea drops get <slug>
get_listings	Obtenir les annonces pour une collection ou un NFT	Voir la section Place de marché ci-dessus
get_offers	Obtenir les offres pour une collection ou un NFT	Voir la section Place de marché ci-dessus
get_orders	Obtenir les commandes (par hash)	orders/opensea-order.sh <chain> <order_hash>
get_contract	Obtenir les détails d'un contrat	opensea nfts contract <chain> <address>
get_account	Obtenir les détails d'un compte
check_eligible_drop	Vérifier l'éligibilité au mint pour un drop
build_mint_transaction	Construire une transaction de mint pour un drop	opensea drops mint
deploy_seadrop_contract	Déployer un nouveau contrat SeaDrop
get_deploy_receipt	Obtenir le reçu de déploiement d'un contrat SeaDrop
resolve_ens	Résoudre un nom ENS en adresse Ethereum
register_ai_agent_tool	Enregistrer un outil d'agent IA (ERC-8257)
search_ai_agent_tools	Rechercher des outils d'agent IA enregistrés

Références

• Référence de l'API OpenSea
• Démarrage rapide de la CLI OpenSea