API OpenSea
Consulte dados de NFTs e tokens, navegue por drops, transmita eventos e pesquise em Ethereum, Base, Arbitrum, Optimism, Polygon e muito mais.
Quando usar esta skill (scope_in)
Use opensea-api para:
- Detalhes, estatísticas, atributos, coleções em alta e principais coleções
- Detalhes de NFTs, propriedade, atualização de metadados
- Detalhes de tokens, tokens em alta, principais tokens, grupos de tokens
- Pesquisar em coleções, NFTs, tokens e contas
- Pesquisar e descobrir ferramentas de agente de IA registradas (ERC-8257)
- Ler anúncios, ofertas e pedidos do marketplace (sem executá-los)
- Monitoramento de eventos e atividades (incluindo streams WebSocket em tempo real)
- Drops e elegibilidade para mint
- Consultas de conta e resolução ENS
- Operações autenticadas de perfil, configurações de coleção, lista de observação, drop, cancelamento de pedido e vinculação de carteira descritas em
references/authentication.md - SIWE sem cabeçalho, criação de PAT com escopo, troca de JWT de curta duração e REST ou MCP autenticados por carteira
Quando NÃO usar esta skill (scope_out, transferência)
| Necessidade | Use em vez disso |
|---|---|
| Comprar/vender NFTs (executar anúncios ou ofertas) | opensea-marketplace |
| Criar novos anúncios ou ofertas | opensea-marketplace |
| Compras de NFTs entre cadeias | opensea-marketplace |
| Trocar tokens ERC20 | opensea-swaps |
| Configurar provedores de assinatura de carteira | opensea-wallet |
| Construir/registrar/bloquear ferramentas de agente de IA | opensea-tool-sdk |
Início rápido
# Resolver uma chave de API: reutiliza sua variável de ambiente / uma chave instantânea em cache, ou busca
# uma nova chave instantânea (sem cadastro) E a salva em disco para reutilização. Veja
# "Resolução de chave de API" abaixo — sempre salve e reutilize uma chave obtida.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)
# Instalar a CLI globalmente (ou use npx)
npm install -g @opensea/cli
# Obter informações da coleção
opensea collections get boredapeyachtclub
# Obter preço mínimo e estatísticas de volume
opensea collections stats boredapeyachtclub
# Obter detalhes do NFT
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234
# Pesquisar no OpenSea
opensea search "cool cats"
# Obter tokens em alta
opensea tokens trending --limit 5
Resolução de chave de API (leia antes da sua primeira requisição)
Toda requisição ao OpenSea precisa de OPENSEA_API_KEY. Se você ainda não tem uma chave,
pode obter uma chave instantânea gratuita sem cadastro. A única regra que
importa: uma vez que você obtenha uma chave instantânea, salve-a em disco e reutilize-a. Não
a obtenha novamente a cada requisição. Uma segunda obtenção pode falhar e deixá-lo sem chave.
A requisição anterior bem-sucedida não terá persistido a chave para você.
O fluxo (siga estas etapas em ordem, sempre)
- Verifique o ambiente primeiro. Se
OPENSEA_API_KEYjá estiver definida e não vazia, use-a como está. Este é o caminho para usuários que fornecem sua própria chave — nunca sobrescreva ou obtenha novamente. - Verifique o disco em seguida. Se não houver variável de ambiente, procure uma chave em cache em
~/.opensea/api_key(substitua o diretório com$OPENSEA_CONFIG_DIR). Se o arquivo existir e não estiver vazio, carregue-o emOPENSEA_API_KEYe use-o. - Obtenha somente se estiver faltando. Se não houver variável de ambiente nem chave em cache,
solicite uma nova chave instantânea via
POST /api/v2/auth/keys. - Salve imediatamente após obter. Escreva a chave obtida em
~/.opensea/api_key(modo600) antes de fazer sua chamada à API, para que a próxima etapa — e toda requisição futura — reutilize-a em vez de obtê-la novamente.
O helper scripts/auth/opensea-resolve-key.sh executa todas as quatro etapas para você e
imprime a chave resolvida. Prefira-o a uma chamada curl ... /auth/keys simples,
que obtém sem salvar e é exatamente o que causou a perda de chaves:
# variável de ambiente? -> use-a. chave em cache? -> reutilize-a. caso contrário, obtenha + salve em disco.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)
opensea collections get boredapeyachtclub
Se você não puder usar o helper, replicar a mesma lógica ordenada explicitamente:
KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
: # 1. variável de ambiente vence
elif [ -s "$KEY_FILE" ]; then
export OPENSEA_API_KEY=$(cat "$KEY_FILE") # 2. reutilizar chave em cache
else
api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key') # 3. obter
mkdir -p "$(dirname "$KEY_FILE")"
(umask 077; printf '%s\n' "$api_key" > "$KEY_FILE") # 4. SALVAR antes de usar
export OPENSEA_API_KEY="${api_key}"
fi
Casos extremos
- Chave já existe (variável de ambiente ou arquivo em cache): reutilize-a; não obtenha uma nova. Obter novamente desperdiça o limite de taxa e pode falhar.
- Chave inválida ou expirada (chaves instantâneas expiram após 7 dias; uma requisição
retorna HTTP
401/403): a chave em cache está obsoleta. Obtenha novamente e sobrescreva o cache comscripts/auth/opensea-resolve-key.sh --force(ou exclua~/.opensea/api_keye execute novamente o fluxo).--forcenunca substitui uma chave fornecida via variável de ambienteOPENSEA_API_KEY. - Falha ao obter (limite de taxa HTTP
429ou erro de rede): não tente novamente em um loop curto. Se você tiver uma chave em cache, continue usando-a. Caso contrário, aguarde e tente novamente mais tarde, ou crie uma chave completa em Configurações → Desenvolvedor. Para limites de taxa mais altos que o nível gratuito instantâneo, use uma chave completa.
Você também pode obter uma chave bruta (resposta JSON, sem persistência) com
opensea auth request-key ou scripts/auth/opensea-auth-request-key.sh — mas se
você usar esses, deve salvar a chave você mesmo conforme a etapa 4 acima.
Guia de tarefas
Recomendado: Use a CLI
opensea(@opensea/cli) como sua ferramenta principal. Instale comnpm install -g @opensea/cliou usenpx @opensea/cli. Os scripts shell emscripts/permanecem disponíveis como alternativas.
Leitura de dados de NFTs
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Obter detalhes da coleção | opensea collections get <slug> | collections/opensea-collection.sh <slug> |
| Obter estatísticas da coleção | opensea collections stats <slug> | collections/opensea-collection-stats.sh <slug> |
| Obter coleções em alta | opensea collections trending [--timeframe <tf>] [--chains <chains>] | collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category] |
| Obter principais coleções | opensea collections top [--sort-by <field>] [--chains <chains>] | collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category] |
| Listar NFTs na coleção | opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>] | collections/opensea-collection-nfts.sh <slug> [limit] [next] |
| Obter NFT único | opensea nfts get <chain> <contract> <token_id> | nfts/opensea-nft.sh <chain> <contract> <token_id> |
| Listar NFTs por carteira | opensea nfts list-by-account <chain> <address> [--limit <n>] | accounts/opensea-account-nfts.sh <chain> <address> [limit] |
| Listar NFTs por contrato | opensea nfts list-by-contract <chain> <contract> [--limit <n>] | |
| Obter atributos da coleção | opensea collections traits <slug> | |
| Obter detalhes do contrato | opensea nfts contract <chain> <address> | |
| Atualizar metadados do NFT | opensea nfts refresh <chain> <contract> <token_id> |
Leitura de dados de tokens
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Obter tokens em alta | opensea tokens trending [--chains <chains>] [--limit <n>] | get_trending_tokens (MCP) |
| Obter principais tokens por volume | opensea tokens top [--chains <chains>] [--limit <n>] | get_top_tokens (MCP) |
| Obter detalhes do token | opensea tokens get <chain> <address> | get_tokens (MCP) |
| Obter atividade de swap do token | opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>] | tokens/opensea-token-activity.sh |
| Obter atividade de token da conta | 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] |
| Obter grupo de token por slug | opensea token-groups get <slug> | tokens/opensea-token-group.sh <slug> |
| Pesquisar tokens | opensea search <query> --types token | search_tokens (MCP) |
| Verificar saldos de tokens | get_token_balances (MCP) |
REST e MCP autenticados por carteira
Leia a referência de autenticação por carteira antes de agir como uma carteira. Ela contém os caminhos felizes da CLI e SDK, cabeçalhos REST e MCP, ciclo de vida de credenciais e regras de recuperação.
Consultas ao marketplace (somente leitura)
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Obter melhores anúncios para coleção | opensea listings best <slug> [--limit <n>] [--traits <json>] | listings/opensea-best-listing.sh <slug> <token_id> |
| Obter melhor anúncio para NFT específico | opensea listings best-for-nft <slug> <token_id> | listings/opensea-best-listing.sh <slug> <token_id> |
| Obter melhor oferta para NFT | opensea offers best-for-nft <slug> <token_id> | offers/opensea-best-offer.sh <slug> <token_id> |
| Listar todos os anúncios da coleção | opensea listings all <slug> [--limit <n>] | listings/opensea-listings-collection.sh <slug> [limit] |
| Listar todas as ofertas da coleção | opensea offers all <slug> [--limit <n>] | offers/opensea-offers-collection.sh <slug> [limit] |
| Obter ofertas da coleção | opensea offers collection <slug> [--limit <n>] | offers/opensea-offers-collection.sh <slug> [limit] |
| Obter ofertas de atributo | opensea offers traits <slug> --type <type> --value <value> | |
| Obter pedido por hash | orders/opensea-order.sh <chain> <order_hash> |
Filtragem de atributos no servidor
Três endpoints com escopo de coleção aceitam um parâmetro de consulta traits para filtragem no servidor:
| Endpoint | CLI | SDK |
|---|---|---|
| Listar NFTs na coleção | opensea nfts list-by-collection <slug> --traits <json> | client.nfts.listByCollection(slug, { traits }) |
| Melhores anúncios para coleção | opensea listings best <slug> --traits <json> | client.listings.best(slug, { traits }) |
| Eventos para coleção | opensea events by-collection <slug> --traits <json> | client.events.byCollection(slug, { traits }) |
--traits recebe um array codificado em JSON de objetos { "traitType": string, "value": string }. Múltiplas entradas são combinadas com AND:
opensea nfts list-by-collection doodles-official \
--traits '[{"traitType":"Background","value":"Red"}]'
Sempre prefira a filtragem no servidor à do cliente: paginar o conjunto não filtrado desperdiça o orçamento de limite de taxa.
Pesquisa
| Tarefa | Comando CLI |
|---|---|
| Pesquisar coleções | opensea search <query> --types collection |
| Pesquisar NFTs | opensea search <query> --types nft |
| Pesquisar tokens | opensea search <query> --types token |
| Pesquisar contas | opensea search <query> --types account |
| Pesquisar múltiplos tipos | opensea search <query> --types collection,nft,token |
| Pesquisar em cadeia específica | opensea search <query> --chains base,ethereum |
Eventos e monitoramento
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Listar eventos recentes | opensea events list [--event-type <type>] [--limit <n>] | |
| Obter eventos da coleção | opensea events by-collection <slug> [--event-type <type>] [--traits <json>] | events/opensea-events-collection.sh <slug> [event_type] [limit] |
| Obter eventos para NFT específico | opensea events by-nft <chain> <contract> <token_id> | |
| Obter eventos para conta | opensea events by-account <address> | |
| Transmitir eventos em tempo real | stream/opensea-stream-collection.sh <slug> (requer websocat) |
Tipos de evento: sale, transfer, mint, listing, offer, trait_offer, collection_offer
Drops e mint
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Listar drops (em destaque/próximos/recentes) | opensea drops list [--type <type>] [--chains <chains>] | drops/opensea-drops.sh [type] [limit] [chains] |
| Obter detalhes e etapas do drop | opensea drops get <slug> | drops/opensea-drop.sh <slug> |
| Construir transação de mint | opensea drops mint <slug> --minter <address> [--quantity <n>] | drops/opensea-drop-mint.sh <slug> <minter> [quantity] |
| Construir transações de mint entre cadeias | 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 ou enviar a transação de publicação (carteira do proprietário, write:drops) | opensea drops publish <slug> [--send] [--wallet-provider <provider>] | |
| Construir ou enviar a transação de despublicação | opensea drops unpublish <slug> [--send] [--wallet-provider <provider>] | |
| Enviar mídia e metadados do drop para IPFS | opensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>] | |
| Verificar progresso do upload IPFS | opensea drops metadata-ipfs-status <slug> <workflow-execution-id> | |
| Solicitar upload de manifesto CSV de metadados | opensea drops create-manifest-upload <slug> | |
| Enviar arquivo para um contexto de upload | opensea drops upload-file --context <path|-> --file <path> [--index <n>] | |
| Implantar novo contrato SeaDrop | deploy_seadrop_contract (MCP) | |
| Verificar status da implantação | get_deploy_receipt (MCP) |
publish --send assina com a carteira EVM configurada e recusa uma que não seja
o from da transação (o proprietário on-chain do contrato), já que uma
transação de qualquer outro endereço é revertida. upload-file aceita um único
contexto de upload; para o array que create-item-media-upload retorna, passe --index <n> ou
canalize um elemento com jq '.[0]'. upload-metadata-ipfs --wait sai com 1 quando
o upload falha, não é encontrado ou excede --wait-timeout.
Para um mint entre cadeias, envie cada transação retornada em ordem. Salve o
objeto receipt_request retornado exatamente como recebido e consulte-o até que o
status seja SUCCESS. O reembolso de gás entre cadeias é tratado automaticamente pela plataforma OpenSea.
Operações autenticadas (perfil, coleção, carteira)
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Obter perfil do usuário | opensea account get | accounts/opensea-account.sh |
| Atualizar perfil do usuário | opensea account update --username <name> --bio "<bio>" | |
| Obter coleções da conta | opensea account collections [--limit <n>] | accounts/opensea-account-collections.sh [limit] |
| Definir coleção como favorita | opensea account add-favorite <slug> | |
| Remover coleção dos favoritos | opensea account remove-favorite <slug> | |
| Obter favoritos da conta | opensea account favorites [--limit <n>] | accounts/opensea-account-favorites.sh [limit] |
| Obter watchlist da conta | opensea account watchlist | |
| Adicionar coleção à watchlist | opensea account add-to-watchlist <slug> | |
| Remover coleção da watchlist | opensea account remove-from-watchlist <slug> | |
| Verificar existência de token | opensea tokens check <chain> <address> |
Ferramentas de agente de IA registradas (ERC-8257 / ERC-7507)
| Tarefa | Comando CLI | Alternativa |
|---|---|---|
| Pesquisar ferramentas registradas | opensea search <query> --types tool | |
| Obter detalhes da ferramenta | opensea tools get <chain> <contract> | |
| Listar ferramentas por proprietário | opensea tools by-owner <address> |
Clientes suportados
| Cliente | Uso |
|---|---|
CLI @opensea/cli | Principal interface interativa e de script |
SDK @opensea/sdk | Integração programática em Node.js/TypeScript |
| Servidor MCP | Integração com Model Context Protocol (por exemplo, em assistentes de IA) |
Scripts shell (scripts/) | Alternativa leve para tarefas comuns |