API de OpenSea
Consulta datos de NFT y tokens, explora drops, transmite eventos en tiempo real y realiza búsquedas en Ethereum, Base, Arbitrum, Optimism, Polygon y más.
Cuándo usar esta skill (scope_in)
Usa opensea-api para:
- Detalles de colecciones, estadísticas, rasgos, tendencias y colecciones principales
- Detalles de NFT, propiedad, actualización de metadatos
- Detalles de tokens, tokens en tendencia, tokens principales, grupos de tokens
- Búsqueda entre colecciones, NFT, tokens y cuentas
- Búsqueda y descubrimiento de herramientas de agente IA registradas (ERC-8257)
- Lectura de listados, ofertas y órdenes del mercado (sin ejecutarlas)
- Eventos y monitoreo de actividad (incluyendo transmisiones WebSocket en tiempo real)
- Drops y elegibilidad para acuñación
- Consultas de cuentas y resolución ENS
- Operaciones autenticadas de perfil, configuración de colecciones, lista de seguimiento, drops, cancelación de órdenes y vinculación de carteras descritas en
references/authentication.md - SIWE sin cabeza, creación de PAT con ámbito, intercambio de JWT de corta duración y REST o MCP autenticados con cartera
Cuándo NO usar esta skill (scope_out, transferencia)
| Necesidad | Usa en su lugar |
|---|---|
| Comprar/vender NFT (ejecutar listados u ofertas) | opensea-marketplace |
| Crear nuevos listados u ofertas | opensea-marketplace |
| Compras de NFT entre cadenas | opensea-marketplace |
| Intercambiar tokens ERC20 | opensea-swaps |
| Configurar proveedores de firma de cartera | opensea-wallet |
| Construir/registrar/restringir herramientas de agente IA | opensea-tool-sdk |
Inicio rápido
# Resolver una clave API: reutiliza tu variable de entorno / una clave instantánea
# en caché, o busca una nueva clave instantánea (sin registro) Y la guarda en
# disco para reutilizarla. Consulta "Resolución de clave API" más abajo: guarda
# y reutiliza siempre una clave obtenida.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)
# Instalar la CLI globalmente (o usar npx)
npm install -g @opensea/cli
# Obtener información de una colección
opensea collections get boredapeyachtclub
# Obtener precio mínimo y estadísticas de volumen
opensea collections stats boredapeyachtclub
# Obtener detalles de un NFT
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234
# Buscar en OpenSea
opensea search "cool cats"
# Obtener tokens en tendencia
opensea tokens trending --limit 5
Resolución de clave API (léelo antes de tu primera solicitud)
Toda solicitud a OpenSea necesita OPENSEA_API_KEY. Si aún no tienes una clave,
puedes obtener una clave instantánea gratuita sin registro. La única regla
importante: una vez que obtengas una clave instantánea, guárdala en disco y
reutilízala. No la vuelvas a obtener en cada solicitud. Una segunda obtención
puede fallar y dejarte sin clave. La solicitud anterior exitosa
no habrá persistido la clave por ti.
El flujo (sigue estos pasos en orden, cada vez)
- Primero verifica el entorno. Si
OPENSEA_API_KEYya está definida y no está vacía, úsala tal cual. Esta es la ruta para usuarios que proporcionan su propia clave: nunca la sobrescribas ni la vuelvas a obtener. - Luego verifica el disco. Si no hay variable de entorno, busca una clave
en caché en
~/.opensea/api_key(sobrescribe el directorio con$OPENSEA_CONFIG_DIR). Si el archivo existe y no está vacío, cárgalo enOPENSEA_API_KEYy úsalo. - Obtén solo si falta. Si no hay ni variable de entorno ni clave en caché,
solicita una nueva clave instantánea a
POST /api/v2/auth/keys. - Guarda inmediatamente después de obtener. Escribe la clave obtenida en
~/.opensea/api_key(modo600) antes de hacer tu llamada a la API, para que el siguiente paso — y cada solicitud futura — la reutilice en lugar de volver a obtenerla.
El helper scripts/auth/opensea-resolve-key.sh realiza los cuatro pasos por ti
y muestra la clave resuelta. Prefiérelo sobre una llamada curl ... /auth/keys
desnuda, que obtiene sin guardar y es exactamente lo que causó que se
perdieran las claves:
# ¿Variable de entorno? -> úsala. ¿Clave en caché? -> reutilízala. Si no, obtén + guarda en disco.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)
opensea collections get boredapeyachtclub
Si no puedes usar el helper, replica la misma lógica ordenada explícitamente:
KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
: # 1. la variable de entorno gana
elif [ -s "$KEY_FILE" ]; then
export OPENSEA_API_KEY=$(cat "$KEY_FILE") # 2. reutilizar clave en caché
else
api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key') # 3. obtener
mkdir -p "$(dirname "$KEY_FILE")"
(umask 077; printf '%s\n' "$api_key" > "$KEY_FILE") # 4. GUARDAR antes de usarla
export OPENSEA_API_KEY="${api_key}"
fi
Casos límite
- La clave ya existe (variable de entorno o archivo en caché): reutilízala; no obtengas una nueva. Volver a obtener desperdicia el límite de tasa y puede fallar.
- Clave inválida o caducada (las claves instantáneas caducan después de 7
días; una solicitud devuelve HTTP
401/403): la clave en caché está obsoleta. Vuelve a obtenerla y sobrescribe la caché conscripts/auth/opensea-resolve-key.sh --force(o elimina~/.opensea/api_keyy vuelve a ejecutar el flujo).--forcenunca sobrescribe una clave proporcionada a través de la variable de entornoOPENSEA_API_KEY. - La obtención falla (límite de tasa HTTP
429, o error de red): no reintentes en un bucle cerrado. Si tienes una clave en caché, sigue usándola. De lo contrario, espera e inténtalo de nuevo más tarde, o crea una clave completa en Configuración → Desarrollador. Para límites de tasa más altos que el nivel gratuito instantáneo, usa una clave completa.
También puedes obtener una clave cruda (respuesta JSON, sin persistencia) con
opensea auth request-key o scripts/auth/opensea-auth-request-key.sh — pero si
usas esos, debes guardar la clave tú mismo según el paso 4 anterior.
Guía de tareas
Recomendado: Usa la CLI
opensea(@opensea/cli) como tu herramienta principal. Instálala connpm install -g @opensea/clio usanpx @opensea/cli. Los scripts de shell enscripts/siguen disponibles como alternativas.
Lectura de datos NFT
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Obtener detalles de colección | opensea collections get <slug> | collections/opensea-collection.sh <slug> |
| Obtener estadísticas de colección | opensea collections stats <slug> | collections/opensea-collection-stats.sh <slug> |
| Obtener colecciones en tendencia | opensea collections trending [--timeframe <tf>] [--chains <chains>] | collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category] |
| Obtener colecciones principales | opensea collections top [--sort-by <field>] [--chains <chains>] | collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category] |
| Listar NFT en colección | opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>] | collections/opensea-collection-nfts.sh <slug> [limit] [next] |
| Obtener un solo NFT | opensea nfts get <chain> <contract> <token_id> | nfts/opensea-nft.sh <chain> <contract> <token_id> |
| Listar NFT por cartera | opensea nfts list-by-account <chain> <address> [--limit <n>] | accounts/opensea-account-nfts.sh <chain> <address> [limit] |
| Listar NFT por contrato | opensea nfts list-by-contract <chain> <contract> [--limit <n>] | |
| Obtener rasgos de colección | opensea collections traits <slug> | |
| Obtener detalles de contrato | opensea nfts contract <chain> <address> | |
| Actualizar metadatos de NFT | opensea nfts refresh <chain> <contract> <token_id> |
Lectura de datos de tokens
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Obtener tokens en tendencia | opensea tokens trending [--chains <chains>] [--limit <n>] | get_trending_tokens (MCP) |
| Obtener tokens principales por volumen | opensea tokens top [--chains <chains>] [--limit <n>] | get_top_tokens (MCP) |
| Obtener detalles de token | opensea tokens get <chain> <address> | get_tokens (MCP) |
| Obtener actividad de intercambio de token | opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>] | tokens/opensea-token-activity.sh |
| Obtener actividad de token de cuenta | opensea tokens account-activity <address> [--chains <chains>] [--tokens <tokens>] [--type <types>] [--limit <n>] [--next <cursor>] | |
| Listar grupos de tokens | opensea token-groups list [--limit <n>] [--next <cursor>] | tokens/opensea-token-groups.sh [limit] [cursor] |
| Obtener grupo de token por slug | opensea token-groups get <slug> | tokens/opensea-token-group.sh <slug> |
| Buscar tokens | opensea search <query> --types token | search_tokens (MCP) |
| Verificar saldos de tokens | get_token_balances (MCP) |
REST y MCP autenticados con cartera
Lee la referencia de autenticación de cartera antes de actuar como una cartera. Contiene las rutas felices de CLI y SDK, encabezados REST y MCP, ciclo de vida de credenciales y reglas de recuperación.
Consultas del mercado (solo lectura)
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Obtener mejores listados para colección | opensea listings best <slug> [--limit <n>] [--traits <json>] | listings/opensea-best-listing.sh <slug> <token_id> |
| Obtener mejor listado para un NFT específico | opensea listings best-for-nft <slug> <token_id> | listings/opensea-best-listing.sh <slug> <token_id> |
| Obtener mejor oferta para NFT | opensea offers best-for-nft <slug> <token_id> | offers/opensea-best-offer.sh <slug> <token_id> |
| Listar todos los listados de colección | opensea listings all <slug> [--limit <n>] | listings/opensea-listings-collection.sh <slug> [limit] |
| Listar todas las ofertas de colección | opensea offers all <slug> [--limit <n>] | offers/opensea-offers-collection.sh <slug> [limit] |
| Obtener ofertas de colección | opensea offers collection <slug> [--limit <n>] | offers/opensea-offers-collection.sh <slug> [limit] |
| Obtener ofertas de rasgos | opensea offers traits <slug> --type <type> --value <value> | |
| Obtener orden por hash | orders/opensea-order.sh <chain> <order_hash> |
Filtrado de rasgos del lado del servidor
Tres endpoints con ámbito de colección aceptan un parámetro de consulta traits para filtrado del lado del servidor:
| Endpoint | CLI | SDK |
|---|---|---|
| Listar NFT en colección | opensea nfts list-by-collection <slug> --traits <json> | client.nfts.listByCollection(slug, { traits }) |
| Mejores listados para colección | opensea listings best <slug> --traits <json> | client.listings.best(slug, { traits }) |
| Eventos para colección | opensea events by-collection <slug> --traits <json> | client.events.byCollection(slug, { traits }) |
--traits toma un arreglo codificado en JSON de objetos { "traitType": string, "value": string }. Múltiples entradas se combinan con AND:
opensea nfts list-by-collection doodles-official \
--traits '[{"traitType":"Background","value":"Red"}]'
Siempre prefiere el filtrado del lado del servidor sobre el del lado del cliente: paginar el conjunto sin filtrar desperdicia el presupuesto del límite de tasa.
Búsqueda
| Tarea | Comando CLI |
|---|---|
| Buscar colecciones | opensea search <query> --types collection |
| Buscar NFT | opensea search <query> --types nft |
| Buscar tokens | opensea search <query> --types token |
| Buscar cuentas | opensea search <query> --types account |
| Buscar múltiples tipos | opensea search <query> --types collection,nft,token |
| Buscar en cadena específica | opensea search <query> --chains base,ethereum |
Eventos y monitoreo
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Listar eventos recientes | opensea events list [--event-type <type>] [--limit <n>] | |
| Obtener eventos de colección | opensea events by-collection <slug> [--event-type <type>] [--traits <json>] | events/opensea-events-collection.sh <slug> [event_type] [limit] |
| Obtener eventos para un NFT específico | opensea events by-nft <chain> <contract> <token_id> | |
| Obtener eventos para una cuenta | opensea events by-account <address> | |
| Transmitir eventos en tiempo real | stream/opensea-stream-collection.sh <slug> (requiere websocat) |
Tipos de evento: sale, transfer, mint, listing, offer, trait_offer, collection_offer
Drops y acuñación
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Listar drops (destacados/próximos/recientes) | opensea drops list [--type <type>] [--chains <chains>] | drops/opensea-drops.sh [type] [limit] [chains] |
| Obtener detalles y etapas de drop | opensea drops get <slug> | drops/opensea-drop.sh <slug> |
| Construir transacción de acuñación | opensea drops mint <slug> --minter <address> [--quantity <n>] | drops/opensea-drop-mint.sh <slug> <minter> [quantity] |
| Construir transacciones de acuñación entre cadenas | 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] |
Construir o enviar la transacción de publicación (cartera propietaria, write:drops) | opensea drops publish <slug> [--send] [--wallet-provider <provider>] | |
| Construir o enviar la transacción de despublicación | opensea drops unpublish <slug> [--send] [--wallet-provider <provider>] | |
| Subir medios y metadatos de drop a IPFS | opensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>] | |
| Verificar progreso de subida IPFS | opensea drops metadata-ipfs-status <slug> <workflow-execution-id> | |
| Solicitar subida de manifiesto CSV de metadatos | opensea drops create-manifest-upload <slug> | |
| Subir un archivo a un contexto de subida | `opensea drops upload-file --context <path | -> --file [--index ]` |
| Desplegar un nuevo contrato SeaDrop | deploy_seadrop_contract (MCP) | |
| Verificar estado del despliegue | get_deploy_receipt (MCP) |
publish --send firma con la cartera EVM configurada y rechaza una que no sea
el from de la transacción (el propietario en cadena del contrato), ya que una
transacción desde cualquier otra dirección se revertiría. upload-file toma un
único contexto de subida; para el arreglo que devuelve create-item-media-upload,
pasa --index <n> o canaliza un elemento con jq '.[0]'. upload-metadata-ipfs --wait sale con 1 cuando
la subida falla, no se encuentra o supera --wait-timeout.
Para una acuñación entre cadenas, envía cada transacción devuelta en orden.
Guarda el objeto receipt_request devuelto exactamente como se recibió, luego
consúltalo hasta que el estado sea SUCCESS o FAILED. Si es FAILED, revisa
los registros de la transacción para depurar.
Transmisión en tiempo real
# Transmitir eventos de colección (requiere websocat)
stream/opensea-stream-collection.sh boredapeyachtclub
Cuentas y perfiles
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Obtener detalles de cuenta | opensea accounts get <address_or_ens> | accounts/opensea-account.sh <address_or_ens> |
| Listar NFT de cuenta | opensea nfts list-by-account <chain> <address> [--limit <n>] | accounts/opensea-account-nfts.sh <chain> <address> [limit] |
| Obtener actividad de cuenta | opensea events by-account <address> | |
| Resolver ENS | opensea accounts resolve-ens <name> | |
| Obtener perfil del usuario actual | opensea accounts me | |
| Actualizar perfil del usuario actual | opensea accounts update-me --bio "<text>" [--profile-image <url>] [--banner-image <url>] | |
| Añadir cartera al perfil | opensea accounts add-wallet <address> |
Actualizaciones de listados (solo lectura)
Estos endpoints devuelven actualizaciones de metadatos de listados. Para la
creación y ejecución real de órdenes, usa opensea-marketplace.
| Tarea | Comando CLI | Alternativa |
|---|---|---|
| Obtener listado por hash | opensea orders get <chain> <order_hash> | orders/opensea-order.sh <chain> <order_hash> |
| Obtener listado por criterios | listings/opensea-listing-by-criteria.sh | |
| Obtener oferta por criterios | offers/opensea-offer-by-criteria.sh |
Arquitectura y MCP
Esta skill expone comandos CLI (vía @opensea/cli), scripts de shell en scripts/
y una ruta de Protocolo de Contexto de Modelo (MCP). Para conectarte a un servidor
MCP:
{
"mcpServers": {
"opensea": {
"command": "npx",
"args": ["-y", "@opensea/mcp-server"]
}
}
}
El servidor MCP carga tu OPENSEA_API_KEY del entorno y expone todas las
consultas como herramientas. La mayoría de los comandos CLI tienen una
contraparte MCP directa (por ejemplo, get_collection, get_collection_stats,
search_collections). La autenticación MCP sigue el mismo flujo de resolución
de claves descrito anteriormente.
Referencia de SDK y API REST
La documentación completa de la API REST de OpenSea está en
docs.opensea.io. El SDK (@opensea/sdk)
ofrece clientes con seguridad de tipos para todos los endpoints. Los scripts de
shell en scripts/ y los comandos CLI son envoltorios alrededor de la API REST.
Solución de problemas
- Clave API no encontrada: Ejecuta
scripts/auth/opensea-resolve-key.shy exporta el resultado comoOPENSEA_API_KEY. Si el script falla, verifica tu conectividad de red. - Error 401/403: la clave ha caducado o es inválida. Fuerza una nueva
obtención con
scripts/auth/opensea-resolve-key.sh --force. - Error 429: te has quedado sin límite de tasa. Reduce la frecuencia de las solicitudes o usa una clave de nivel superior.
- Comando no encontrado: instala la CLI con
npm install -g @opensea/clio usanpx @opensea/cli. - Scripts de shell no ejecutables: ejecuta
chmod +x scripts/**/*.sh. - Preguntas sobre la API: consulta la documentación de OpenSea.
Para la API del toolkit de agente (ERC-8257), usa opensea-search-tools o
la referencia de herramientas registradas en references/agent-toolkit.md.