OpenSea API

OpenSea API은(는) 무엇을 하나요?

NFT 및 토큰 데이터를 조회하고, 드롭을 탐색하며, 이벤트를 스트리밍하고, 이더리움, Base, Arbitrum, Optimism, Polygon 등 여러 체인에서 검색합니다.

이 기술을 사용해야 하는 경우 (scope_in)

다음과 같은 경우 opensea-api를 사용하세요:

• 컬렉션 세부 정보, 통계, 특성, 트렌딩, 상위 컬렉션
• NFT 세부 정보, 소유권, 메타데이터 새로고침
• 토큰 세부 정보, 트렌딩 토큰, 상위 토큰, 토큰 그룹
• 컬렉션, NFT, 토큰, 계정 검색
• 등록된 AI 에이전트 도구(ERC-8257) 검색 및 발견
• 마켓플레이스 리스팅, 오퍼, 주문 조회(실행은 제외)
• 이벤트 및 활동 모니터링(실시간 WebSocket 스트림 포함)
• 드롭 및 민트 자격 확인
• 계정 조회 및 ENS 확인
• 인증된 프로필, 컬렉션 설정, 관심 목록, 드롭, 주문 취소, 지갑 연결 작업 (참조: references/authentication.md)
• 헤드리스 SIWE, 범위 지정 PAT 생성, 단기 JWT 교환, 지갑 인증 REST 또는 MCP

이 기술을 사용하지 말아야 하는 경우 (scope_out, 핸드오프)

필요 기능	대신 사용
NFT 구매/판매 (리스팅 또는 오퍼 체결)	opensea-marketplace
새 리스팅 또는 오퍼 생성	opensea-marketplace
크로스체인 NFT 구매	opensea-marketplace
ERC20 토큰 스왑	opensea-swaps
지갑 서명 제공자 설정	opensea-wallet
AI 에이전트 도구 구축/등록/게이트	opensea-tool-sdk

빠른 시작

# API 키 해결: 환경 변수/캐시된 인스턴트 키를 재사용하거나,
# 새로운 인스턴트 키를 가져와서(가입 불필요) 디스크에 저장하여 재사용합니다.
# 아래 "API 키 해결" 참조 — 가져온 키는 항상 저장하고 재사용하세요.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

# CLI 전역 설치 (또는 npx 사용)
npm install -g @opensea/cli

# 컬렉션 정보 가져오기
opensea collections get boredapeyachtclub

# 바닥 가격 및 거래량 통계 가져오기
opensea collections stats boredapeyachtclub

# NFT 세부 정보 가져오기
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234

# OpenSea 검색
opensea search "cool cats"

# 트렌딩 토큰 가져오기
opensea tokens trending --limit 5

API 키 해결 (첫 번째 요청 전에 읽어야 함)

모든 OpenSea 요청에는 OPENSEA_API_KEY가 필요합니다. 키가 아직 없는 경우, 가입 없이 인스턴트 무료 티어 키를 가져올 수 있습니다. 중요한 규칙은 인스턴트 키를 한 번 가져오면 디스크에 저장하고 재사용하세요입니다. 요청할 때마다 다시 가져오지 마십시오. 두 번째 가져오기는 실패하여 키가 없을 수 있습니다. 이전 성공적인 요청이 키를 지속시키지 않았을 수 있습니다.

흐름 (매번 다음 순서대로 따르세요)

1. 먼저 환경을 확인하세요. OPENSEA_API_KEY가 이미 설정되어 있고 비어 있지 않으면 그대로 사용하세요. 이는 자신의 키를 제공하는 사용자를 위한 경로입니다. 절대 덮어쓰거나 다시 가져오지 마십시오.
2. 다음으로 디스크를 확인하세요. 환경 변수가 없으면 ~/.opensea/api_key에서 캐시된 키를 찾으십시오($OPENSEA_CONFIG_DIR로 디렉토리 재정의 가능). 파일이 존재하고 비어 있지 않으면 OPENSEA_API_KEY로 로드하고 사용하십시오.
3. 누락된 경우에만 가져오세요. 환경 변수나 캐시된 키가 모두 없으면 POST /api/v2/auth/keys에서 새 인스턴트 키를 요청하십시오.
4. 가져온 직후 저장하세요. 가져온 키를 API 호출 전에 ~/.opensea/api_key(모드 600)에 기록하여 다음 단계와 모든 향후 요청에서 다시 가져오지 않고 재사용하도록 하십시오.

scripts/auth/opensea-resolve-key.sh 헬퍼는 위의 네 단계를 모두 수행하고 해결된 키를 출력합니다. 저장 없이 가져오기만 하는 curl ... /auth/keys 호출보다 이것을 선호하세요. 저장 없이 가져오는 것이 정확히 키 손실의 원인입니다:

# 환경 변수? -> 사용. 캐시된 키? -> 재사용. 그 외에는 가져와서 디스크에 저장.
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

opensea collections get boredapeyachtclub

헬퍼를 사용할 수 없는 경우 동일한 순서 논리를 명시적으로 복제하십시오:

KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
  :                                              # 1. 환경 변수 우선
elif [ -s "$KEY_FILE" ]; then
  export OPENSEA_API_KEY=$(cat "$KEY_FILE")      # 2. 캐시된 키 재사용
else
  api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')  # 3. 가져오기
  mkdir -p "$(dirname "$KEY_FILE")"
  (umask 077; printf '%s\n' "$api_key" > "$KEY_FILE")  # 4. 사용하기 전에 저장
  export OPENSEA_API_KEY="${api_key}"
fi

예외 상황

• 키가 이미 존재하는 경우 (환경 변수 또는 캐시된 파일): 재사용하십시오. 새 키를 가져오지 마십시오. 다시 가져오면 속도 제한을 낭비하고 실패할 수 있습니다.
• 키가 유효하지 않거나 만료된 경우 (인스턴트 키는 7일 후 만료, 요청이 HTTP 401/403 반환): 캐시된 키가 오래된 것입니다. scripts/auth/opensea-resolve-key.sh --force로 다시 가져와 캐시를 덮어쓰거나 ~/.opensea/api_key를 삭제하고 흐름을 다시 실행하십시오. --force는 OPENSEA_API_KEY 환경 변수를 통해 제공된 키를 절대 재정의하지 않습니다.
• 가져오기 실패 (HTTP 429 속도 제한 또는 네트워크 오류): 짧은 루프에서 재시도하지 마십시오. 캐시된 키가 있으면 계속 사용하십시오. 그렇지 않으면 나중에 다시 시도하거나 설정 → 개발자에서 전체 키를 만드십시오. 인스턴트 무료 티어보다 높은 속도 제한이 필요하면 전체 키를 사용하십시오.

opensea auth request-key 또는 scripts/auth/opensea-auth-request-key.sh로 원시 키(JSON 응답, 지속성 없음)를 가져올 수도 있지만, 이를 사용하는 경우 위의 4단계에 따라 직접 키를 저장해야 합니다.

작업 가이드

권장: opensea CLI(@opensea/cli)를 기본 도구로 사용하십시오. npm install -g @opensea/cli로 설치하거나 npx @opensea/cli를 사용하십시오. scripts/의 셸 스크립트도 대안으로 사용할 수 있습니다.

NFT 데이터 읽기

작업	CLI 명령어	대안
컬렉션 세부 정보 가져오기	opensea collections get <slug>	collections/opensea-collection.sh <slug>
컬렉션 통계 가져오기	opensea collections stats <slug>	collections/opensea-collection-stats.sh <slug>
트렌딩 컬렉션 가져오기	opensea collections trending [--timeframe <tf>] [--chains <chains>]	collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category]
상위 컬렉션 가져오기	opensea collections top [--sort-by <field>] [--chains <chains>]	collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category]
컬렉션의 NFT 목록	opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]	collections/opensea-collection-nfts.sh <slug> [limit] [next]
단일 NFT 가져오기	opensea nfts get <chain> <contract> <token_id>	nfts/opensea-nft.sh <chain> <contract> <token_id>
지갑별 NFT 목록	opensea nfts list-by-account <chain> <address> [--limit <n>]	accounts/opensea-account-nfts.sh <chain> <address> [limit]
컨트랙트별 NFT 목록	opensea nfts list-by-contract <chain> <contract> [--limit <n>]
컬렉션 특성 가져오기	opensea collections traits <slug>
컨트랙트 세부 정보 가져오기	opensea nfts contract <chain> <address>
NFT 메타데이터 새로고침	opensea nfts refresh <chain> <contract> <token_id>

토큰 데이터 읽기

작업	CLI 명령어	대안
트렌딩 토큰 가져오기	opensea tokens trending [--chains <chains>] [--limit <n>]	get_trending_tokens (MCP)
거래량 기준 상위 토큰 가져오기	opensea tokens top [--chains <chains>] [--limit <n>]	get_top_tokens (MCP)
토큰 세부 정보 가져오기	opensea tokens get <chain> <address>	get_tokens (MCP)
토큰 스왑 활동 가져오기	opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>]	tokens/opensea-token-activity.sh
계정 토큰 활동 가져오기	opensea tokens account-activity <address> [--chains <chains>] [--tokens <tokens>] [--type <types>] [--limit <n>] [--next <cursor>]
토큰 그룹 목록	opensea token-groups list [--limit <n>] [--next <cursor>]	tokens/opensea-token-groups.sh [limit] [cursor]
슬러그로 토큰 그룹 가져오기	opensea token-groups get <slug>	tokens/opensea-token-group.sh <slug>
토큰 검색	opensea search <query> --types token	search_tokens (MCP)
토큰 잔액 확인	get_token_balances (MCP)

지갑 인증 REST 및 MCP

지갑으로 작업하기 전에 wallet 인증 참조를 읽으십시오. 여기에는 CLI 및 SDK 행복 경로, REST 및 MCP 헤더, 자격 증명 수명 주기, 복구 규칙이 포함되어 있습니다.

마켓플레이스 쿼리 (읽기 전용)

작업	CLI 명령어	대안
컬렉션 최고 리스팅 가져오기	opensea listings best <slug> [--limit <n>] [--traits <json>]	listings/opensea-best-listing.sh <slug> <token_id>
특정 NFT 최고 리스팅 가져오기	opensea listings best-for-nft <slug> <token_id>	listings/opensea-best-listing.sh <slug> <token_id>
NFT 최고 오퍼 가져오기	opensea offers best-for-nft <slug> <token_id>	offers/opensea-best-offer.sh <slug> <token_id>
모든 컬렉션 리스팅 목록	opensea listings all <slug> [--limit <n>]	listings/opensea-listings-collection.sh <slug> [limit]
모든 컬렉션 오퍼 목록	opensea offers all <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
컬렉션 오퍼 가져오기	opensea offers collection <slug> [--limit <n>]	offers/opensea-offers-collection.sh <slug> [limit]
특성 오퍼 가져오기	opensea offers traits <slug> --type <type> --value <value>
해시로 주문 가져오기		orders/opensea-order.sh <chain> <order_hash>

서버 측 특성 필터링

세 가지 컬렉션 범위 엔드포인트는 서버 측 필터링을 위해 traits 쿼리 매개변수를 허용합니다:

엔드포인트	CLI	SDK
컬렉션의 NFT 목록	opensea nfts list-by-collection <slug> --traits <json>	client.nfts.listByCollection(slug, { traits })
컬렉션 최고 리스팅	opensea listings best <slug> --traits <json>	client.listings.best(slug, { traits })
컬렉션 이벤트	opensea events by-collection <slug> --traits <json>	client.events.byCollection(slug, { traits })

--traits는 { "traitType": string, "value": string } 객체의 JSON 인코딩 배열을 받습니다. 여러 항목은 AND로 결합됩니다:

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

항상 클라이언트 측 필터링보다 서버 측 필터링을 선호하십시오: 필터링되지 않은 집합을 페이지 매기면 속도 제한 예산이 낭비됩니다.

검색

작업	CLI 명령어
컬렉션 검색	opensea search <query> --types collection
NFT 검색	opensea search <query> --types nft
토큰 검색	opensea search <query> --types token
계정 검색	opensea search <query> --types account
여러 유형 검색	opensea search <query> --types collection,nft,token
특정 체인 검색	opensea search <query> --chains base,ethereum

이벤트 및 모니터링

작업	CLI 명령어	대안
최근 이벤트 목록	opensea events list [--event-type <type>] [--limit <n>]
컬렉션 이벤트 가져오기	opensea events by-collection <slug> [--event-type <type>] [--traits <json>]	events/opensea-events-collection.sh <slug> [event_type] [limit]
특정 NFT 이벤트 가져오기	opensea events by-nft <chain> <contract> <token_id>
계정 이벤트 가져오기	opensea events by-account <address>
실시간 이벤트 스트리밍		stream/opensea-stream-collection.sh <slug> (websocat 필요)

이벤트 유형: sale, transfer, mint, listing, offer, trait_offer, collection_offer

드롭 및 민팅

작업	CLI 명령어	대안
드롭 목록 (추천/예정/최근)	opensea drops list [--type <type>] [--chains <chains>]	drops/opensea-drops.sh [type] [limit] [chains]
드롭 세부 정보 및 단계 가져오기	opensea drops get <slug>	drops/opensea-drop.sh <slug>
민트 트랜잭션 구성	opensea drops mint <slug> --minter <address> [--quantity <n>]	drops/opensea-drop-mint.sh <slug> <minter> [quantity]
크로스체인 민트 트랜잭션 구성	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]
게시 트랜잭션 구성 또는 전송 (소유자 지갑, write:drops)	opensea drops publish <slug> [--send] [--wallet-provider <provider>]
게시 취소 트랜잭션 구성 또는 전송	opensea drops unpublish <slug> [--send] [--wallet-provider <provider>]
드롭 미디어 및 메타데이터를 IPFS에 업로드	opensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>]
IPFS 업로드 진행 상황 확인	opensea drops metadata-ipfs-status <slug> <workflow-execution-id>
메타데이터 매니페스트 CSV 업로드 요청	opensea drops create-manifest-upload <slug>
업로드 컨텍스트에 파일 업로드	`opensea drops upload-file --context <path	-> --file [--index ]`
새 SeaDrop 컨트랙트 배포		deploy_seadrop_contract (MCP)
배포 상태 확인		get_deploy_receipt (MCP)

publish --send는 구성된 EVM 지갑으로 서명하며, 트랜잭션의 from(컨트랙트의 온체인 소유자)이 아닌 지갑은 거부합니다. 다른 주소의 트랜잭션은 되돌아가기 때문입니다. upload-file은 단일 업로드 컨텍스트를 취합니다. create-item-media-upload가 반환하는 배열의 경우 --index <n>을 전달하거나 jq '.[0]'로 하나의 요소를 파이프하십시오. upload-metadata-ipfs --wait는 업로드가 실패하거나, 찾을 수 없거나, --wait-timeout을 초과하면 종료 코드 1로 종료됩니다.

크로스체인 민트의 경우 반환된 모든 트랜잭션을 순서대로 제출하십시오. 반환된 receipt_request 객체를 받은 그대로 저장한 후, 상태가 SUCCESS가 될 때까지 폴링하십시오.