openapi: 3.1.0
info:
  title: OpenSea Account Endpoints NFT Endpoints API
  description: The API for OpenSea
  contact:
    name: OpenSea
    url: https://www.opensea.io
    email: contact@opensea.io
  version: 2.0.0
servers:
- url: https://api.opensea.io
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: NFT Endpoints
  description: NFT endpoints to retrieve individual NFTs, metadata, ownership, and rarity
paths:
  /api/v2/nfts/batch:
    post:
      tags:
      - NFT Endpoints
      summary: Get NFTs by identifiers
      description: Retrieve multiple NFTs in a single request by providing a list of identifiers (chain, contract address, and token ID). Not-found NFTs are silently omitted from the response.
      operationId: get_nfts_batch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchNftsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/validate-metadata:
    post:
      tags:
      - NFT Endpoints
      summary: Validate NFT metadata
      description: Fetch and validate NFT metadata directly from the blockchain without using cached data. Returns both original and processed (SeaDN) URLs to show how the metadata would be ingested. This endpoint does not persist any data.
      operationId: validate_nft_metadata
      parameters:
      - name: chain
        in: path
        description: The blockchain on which the NFT exists
        required: true
        schema:
          type: string
        example: ethereum
      - name: address
        in: path
        description: The contract address
        required: true
        schema:
          type: string
        example: '0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d'
      - name: identifier
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      - name: ignoreCachedItemUrls
        in: query
        description: Whether to bypass cached SeaDN URLs
        required: false
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ValidateMetadataResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/refresh:
    post:
      tags:
      - NFT Endpoints
      summary: Refresh NFT metadata
      description: Queue a metadata refresh for a specific NFT to update its information from the blockchain.
      operationId: refresh_nft_metadata
      parameters:
      - name: address
        in: path
        description: Contract address
        required: true
        schema:
          type: string
      - name: chain
        in: path
        description: Blockchain chain identifier
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: Token identifier
        required: true
        schema:
          type: string
      - name: ignoreCachedItemUrls
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/assets/transfer:
    post:
      tags:
      - NFT Endpoints
      summary: Transfer NFTs or tokens between wallets
      description: Returns ordered blockchain actions to execute for transferring one or more NFTs or tokens from one wallet to another. Supports bulk transfers of multiple assets in a single request.
      operationId: transfer_assets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
        required: true
      responses:
        '200':
          description: Transfer actions retrieved successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          description: 'The request is invalid. Possible reasons: empty assets array, invalid addresses, invalid chain, or cross-ecosystem transfer.'
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/metadata/{chain}/{contractAddress}/{tokenId}:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFT metadata
      description: Get detailed metadata for an NFT including name, description, image, traits, and external links.
      operationId: get_nft_metadata
      parameters:
      - name: chain
        in: path
        description: The blockchain on which to filter the results
        required: true
        schema:
          type: string
        example: ethereum
      - name: contractAddress
        in: path
        description: The unique public blockchain identifier for the contract
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      - name: tokenId
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AssetMetadataResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collection/{slug}/nfts:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFTs by collection
      description: 'Get NFTs in a specific collection. Optionally filter by traits using the ''traits'' query parameter with a JSON array of trait filters. Multiple traits are AND-combined (items must match all specified traits). Example: ?traits=[{"traitType":"Background","value":"Red"},{"traitType":"Eyes","value":"Blue"}]'
      operationId: get_nfts_by_collection
      parameters:
      - name: slug
        in: path
        description: Collection slug
        required: true
        schema:
          type: string
      - name: traits
        in: query
        description: 'JSON array of trait filters. Each object has ''traitType'' and ''value'' fields. Multiple traits are AND-combined (items must match all). Example: [{"traitType":"Background","value":"Red"}]'
        required: false
        schema:
          type: string
        example:
        - traitType: Background
          value: Red
      - name: has_agent_binding
        in: query
        description: Filter by NFTs that have an ERC-8217 agent binding
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        description: Number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          description: Number of items to return per page
          example: 20
          maximum: 200
          minimum: 1
        example: 20
      - name: next.value
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFTs by contract
      description: Get all NFTs for a specific contract address on a blockchain.
      operationId: get_nfts_by_contract
      parameters:
      - name: address
        in: path
        description: Contract address
        required: true
        schema:
          type: string
      - name: chain
        in: path
        description: Blockchain chain identifier
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          description: Number of items to return per page
          example: 20
          maximum: 200
          minimum: 1
        example: 20
      - name: next.value
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFT
      description: Get metadata, traits, ownership information, and rarity for a single NFT.
      operationId: get_nft
      parameters:
      - name: chain
        in: path
        description: The blockchain on which to filter the results
        required: true
        schema:
          type: string
        example: ethereum
      - name: address
        in: path
        description: The unique public blockchain identifier for the contract
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      - name: identifier
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/owners:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFT owners
      description: Get a paginated list of owners for a specific NFT. Particularly useful for ERC-1155 tokens which can have multiple owners.
      operationId: get_nft_owners
      parameters:
      - name: chain
        in: path
        description: The blockchain on which to filter the results
        required: true
        schema:
          type: string
        example: ethereum
      - name: address
        in: path
        description: The unique public blockchain identifier for the contract
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      - name: identifier
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      - name: limit
        in: query
        description: 'Number of results to return (default: 20, max: 100)'
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: next
        in: query
        description: Pagination cursor for next page
        required: false
        schema:
          type: string
      responses:
        '200':
          description: NFT owners
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OwnersPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/analytics:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFT analytics
      description: Get analytics data for a specific NFT including sales history and floor price history.
      operationId: get_nft_analytics
      parameters:
      - name: chain
        in: path
        description: The blockchain on which to filter the results
        required: true
        schema:
          type: string
        example: ethereum
      - name: address
        in: path
        description: The unique public blockchain identifier for the contract
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      - name: identifier
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      responses:
        '200':
          description: NFT analytics data
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftAnalyticsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/account/{address}/nfts:
    get:
      tags:
      - NFT Endpoints
      summary: Get NFTs by account
      description: Get all NFTs owned by a specific account on a blockchain, with optional collection filtering.
      operationId: get_nfts_by_account
      parameters:
      - name: address
        in: path
        description: Account address
        required: true
        schema:
          type: string
      - name: chain
        in: path
        description: Blockchain chain identifier
        required: true
        schema:
          type: string
      - name: collection
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          description: Number of items to return per page
          example: 20
          maximum: 200
          minimum: 1
        example: 20
      - name: next.value
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    AgentNftResponse:
      type: object
      properties:
        chain:
          type: string
        token_id:
          type: string
        contract_address:
          type: string
      required:
      - chain
      - contract_address
      - token_id
    NftSalePointResponse:
      type: object
      description: A sale data point for an NFT
      properties:
        time:
          type: string
          format: date-time
          description: Timestamp of the sale
        usd_price:
          type: string
          description: Sale price in USD
        token_unit:
          type: number
          format: double
          description: Sale price in token units
        symbol:
          type: string
          description: Payment token symbol
        chain:
          type: string
          description: Blockchain chain
      required:
      - chain
      - time
      - token_unit
      - usd_price
    Trait:
      type: object
      properties:
        trait_type:
          type: string
        display_type:
          type: string
        max_value:
          type: string
        value: {}
      required:
      - trait_type
      - value
    ValidateMetadataAssetIdentifier:
      type: object
      properties:
        chain:
          type: string
        contractAddress:
          type: string
        tokenId:
          type: string
      required:
      - chain
      - contractAddress
      - tokenId
    Rarity:
      type: object
      properties:
        strategy_id:
          type: string
        strategy_version:
          type: string
        rank:
          type: integer
          format: int64
      required:
      - strategy_id
      - strategy_version
    AgentBindingResponse:
      type: object
      properties:
        agent_id:
          type: string
        binding_contract:
          type: string
        agent:
          $ref: '#/components/schemas/AgentNftResponse'
        registered_by:
          type: string
      required:
      - agent
      - agent_id
      - binding_contract
    ValidateMetadataResponse:
      type: object
      properties:
        assetIdentifier:
          $ref: '#/components/schemas/ValidateMetadataAssetIdentifier'
        tokenUri:
          type: string
        metadata:
          $ref: '#/components/schemas/ValidateMetadataDetails'
        error:
          $ref: '#/components/schemas/MetadataIngestionError'
      required:
      - assetIdentifier
    NftAnalyticsResponse:
      type: object
      description: Analytics data for an NFT including sales and floor price history
      properties:
        sales:
          type: array
          description: List of sale data points
          items:
            $ref: '#/components/schemas/NftSalePointResponse'
        floor_prices:
          type: array
          description: List of floor price data points
          items:
            $ref: '#/components/schemas/FloorPricePointResponse'
      required:
      - floor_prices
      - sales
    OwnersPaginatedResponse:
      type: object
      properties:
        owners:
          type: array
          items:
            $ref: '#/components/schemas/Owner'
        next:
          type: string
      required:
      - owners
    NftDetailed:
      type: object
      properties:
        identifier:
          type: string
        collection:
          type: string
        contract:
          type: string
        token_standard:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        display_image_url:
          type: string
        display_animation_url:
          type: string
        metadata_url:
          type: string
        opensea_url:
          type: string
        updated_at:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        original_image_url:
          type: string
        original_animation_url:
          type: string
        traits:
          type: array
          items:
            $ref: '#/components/schemas/Trait'
        animation_url:
          type: string
        is_suspicious:
          type: boolean
        creator:
          type: string
        owners:
          type: array
          items:
            $ref: '#/components/schemas/Owner'
        rarity:
          $ref: '#/components/schemas/Rarity'
        subscription:
          $ref: '#/components/schemas/SubscriptionInfoResponse'
        agent_binding:
          $ref: '#/components/schemas/AgentBindingResponse'
      required:
      - collection
      - contract
      - creator
      - identifier
      - is_disabled
      - is_nsfw
      - is_suspicious
      - opensea_url
      - owners
      - token_standard
      - traits
      - updated_at
    NftIdentifierInput:
      type: object
      description: An NFT identifier consisting of chain, contract address, and token ID
      properties:
        chain:
          type: string
          description: The blockchain the NFT is on
          example: ethereum
        contract_address:
          type: string
          description: The contract address of the NFT
          example: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'
        token_id:
          type: string
          description: The token ID of the NFT
          example: 1
      required:
      - chain
      - contract_address
      - token_id
    AssetMetadataResponse:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        image:
          type: string
        external_link:
          type: string
        animation_url:
          type: string
        traits:
          type: array
          items:
            $ref: '#/components/schemas/Trait'
      required:
      - traits
    TransferRequest:
      type: object
      description: Request to transfer NFTs or tokens between wallets
      properties:
        assets:
          type: array
          description: List of assets to transfer
          items:
            $ref: '#/components/schemas/TransferAsset'
        from_address:
          type: string
          description: Address of the sender wallet
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        to_address:
          type: string
          description: Address of the recipient wallet
          example: '0x28c6c06298d514db089934071355e5743bf21d60'
      required:
      - assets
      - from_address
      - to_address
    NftResponse:
      type: object
      properties:
        nft:
          $ref: '#/components/schemas/NftDetailed'
      required:
      - nft
    ValidateMetadataAttribute:
      type: object
      properties:
        traitType:
          type: string
        value:
          type: string
        displayType:
          type: string
      required:
      - traitType
      - value
    NftBatchResponse:
      type: object
      properties:
        nfts:
          type: array
          items:
            $ref: '#/components/schemas/NftDetailed'
      required:
      - nfts
    NftListResponse:
      type: object
      properties:
        nfts:
          type: array
          items:
            $ref: '#/components/schemas/Nft'
        next:
          type: string
      required:
      - nfts
    JsonNode: {}
    TransferResponse:
      type: object
      description: Response containing ordered blockchain actions to execute for an asset transfer
      properties:
        steps:
          type: array
          description: Ordered list of blockchain actions to execute. Each action is a JSON object with a single field indicating the type (e.g. transferAction, approvalAction) and its associated data. Serialized using proto3 JSON format — fields with default values (empty string, 0, false) may be omitted.
          items:
            $ref: '#/components/schemas/JsonNode'
      required:
      - steps
    Nft:
      type: object
      properties:
        identifier:
          type: string
        collection:
          type: string
        contract:
          type: string
        token_standard:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        display_image_url:
          type: string
        display_animation_url:
          type: string
        metadata_url:
          type: string
        opensea_url:
          type: string
        updated_at:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        original_image_url:
          type: string
        original_animation_url:
          type: string
        traits:
          type: array
          items:
            $ref: '#/components/schemas/Trait'
      required:
      - collection
      - contract
      - identifier
      - is_disabled
      - is_nsfw
      - opensea_url
      - token_standard
      - traits
      - updated_at
    ValidateMetadataDetails:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        originalImageUrl:
          type: string
        processedImageUrl:
          type: string
        originalAnimationUrl:
          type: string
        processedAnimationUrl:
          type: string
        externalUrl:
          type: string
        backgroundColor:
          type: string
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/ValidateMetadataAttribute'
      required:
      - attributes
    TransferAsset:
      type: object
      description: An asset to transfer
      properties:
        chain:
          type: string
          description: The chain the asset is on (e.g. ethereum, base, solana)
          example: ethereum
        contract:
          type: string
          description: The contract address of the asset
          example: '0xBd3531dA5CF5857e7CfAA92426877b022e612cf8'
        token_id:
          type: string
          description: The token ID of the asset
          example: 1234
        quantity:
          type: string
          description: The quantity to transfer in raw units (1 for ERC721, raw amount for ERC1155/fungible)
          example: 1
      required:
      - chain
      - contract
      - quantity
      - token_id
    BatchNftsRequest:
      type: object
      description: Request body for batch NFT retrieval by identifiers
      properties:
        identifiers:
          type: array
          description: List of NFT identifiers to retrieve
          items:
            $ref: '#/components/schemas/NftIdentifierInput'
      required:
      - identifiers
    MetadataIngestionError:
      type: object
      properties:
        errorType:
          type: string
        message:
          type: string
        url:
          type: string
        statusCode:
          type: integer
          format: int32
      required:
      - errorType
      - message
    FloorPricePointResponse:
      type: object
      description: A floor price data point
      properties:
        time:
          type: string
          format: date-time
          description: Timestamp of the data point
        usd_price:
          type: string
          description: Floor price in USD
        token_unit:
          type: number
          format: double
          description: Floor price in token units
        symbol:
          type: string
          description: Payment token symbol
        chain:
          type: string
          description: Blockchain chain
      required:
      - time
    SubscriptionInfoResponse:
      type: object
      properties:
        expires_at:
          type: string
          format: date-time
        is_renewable:
          type: boolean
        is_expired:
          type: boolean
      required:
      - is_expired
      - is_renewable
    Owner:
      type: object
      properties:
        address:
          type: string
        quantity:
          type: integer
          format: int32
        quantity_string:
          type: string
      required:
      - address
      - quantity
      - quantity_string
  responses:
    NotFound:
      description: Resource not found
    InternalError:
      description: Internal server error. Please open a support ticket so OpenSea can investigate.
    BadRequest:
      description: For error reasons, review the response data.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key required for authentication
      name: x-api-key
      in: header
x-tagGroups:
- name: Data & Discovery
  tags:
  - Chain Endpoints
  - Account Endpoints
  - Collection Endpoints
  - NFT Endpoints
  - Contract Endpoints
  - Token Endpoints
  - Search Endpoints
- name: Marketplace & Trading
  tags:
  - Listing Endpoints
  - Offer Endpoints
  - Order Endpoints
  - Swap Endpoints
  - Drops Endpoints
- name: Analytics & Events
  tags:
  - Analytics Endpoints
- name: Tools [Beta]
  tags:
  - Tool Endpoints [Beta]
- name: Transactions
  tags:
  - Transaction Endpoints